Upload documents and retrieve results

Availability: draft. Confirm the enabled upload formats, extraction paths, size limits and grant prerequisites before implementing against a deployment.

Select an upload flow

Workflow Draft operation
One file up to the configured multipart limit POST /users/{userId}/documents
A large file POST /users/{userId}/document-uploads, PUT bytes to the returned URL, then POST /documents/{documentId}/complete
Historical multi-file import POST /users/{userId}/document-batches, then transfer each accepted file and complete it independently

The proposed batch registration limit is 100 files, pending capacity verification. Batch responses include per-file acceptance or rejection; one rejected file does not imply that the other files were rejected. Upload URLs are short-lived and retain Intake's quarantine, validation and sealing path.

Upload metadata contains only optional externalId, extractData and scrubPII. DocumentUploadMetadata does not contain category, language, issuers, title or documentDate: this applies to multipart, presigned and batch uploads.

DIP infers language, issuers, title and documentDate from the document. These fields are read-only in the returned DocumentMetadata; they are omitted until DIP completes and returned only when the values can be derived. documentDate is source evidence for the date of the test or consultation, distinct from upload time.

DIP assigns category through classification after ingestion. Returned DocumentMetadata.category is read-only and nullable while no classification result is available. A classified value of other is distinct from an unclassified null. The optional document-list category filter remains available. Type acceptance and successful structured extraction are separate capabilities.

Structured document issuers

The read-only issuers array replaces the former singular issuer string. Each DocumentIssuer has a document-derived name and type (lab, hospital, clinic, practice, other or unknown), an optional address, and optional verified organisationId and practitionerIds references. IssuerAddress.text preserves the observed address; structured address components are optional and included only when reliably derived. The array is omitted until DIP completes; after completion, [] means no issuer was identified.

A name or address extracted from a document does not establish an ENO identity. Organisation and practitioner references require verified directory matching and caller authorisation. Practitioner references identify practitioners attributed to this document and associated with that issuer; they are not patient /users identifiers or the issuer's entire practitioner roster. Omit unavailable or unauthorised identity references. Directory matching and reference visibility policy remain release prerequisites.

Extraction and PII scrubbing

Both extractData and scrubPII are optional booleans with an effective default of true when omitted. extractData: false disables structured data extraction, while PII scrubbing remains enabled. scrubPII: false disables PII scrubbing, while extraction must remain enabled. Setting both to false is invalid and returns HTTP 422 with code: validation_failed. The rule applies to multipart, presigned and per-file batch metadata.

extractData scrubPII Valid
true true Yes (default)
false true Yes
true false Yes
false false No — HTTP 422

Processing has multiple milestones

GET /documents/{documentId}
GET /documents/{documentId}/processing-status
GET /documents/{documentId}/extraction

Document lifecycle describes receipt, scanning and processing. The proposed processing-status resource adds publication and delivery into Health Atlas. Only availableInPatientRecord describes published patient-record availability.

The draft extraction read returns 409 while not processed. Failed states use client-safe failure codes and actions. canProcess and canRetry are informational; an authorised processing request uses the command below. Operator redo/replay control routes remain private.

Process or reprocess an already stored document

POST /documents/{documentId}/processing-runs starts first-time data extraction after storage with extractData: false, or reprocesses an eligible completed/failed attempt. This is a proposed partner command; stored-only admission and client-bound receipts require new backend work beyond the existing operator redo command.

POST /documents/{documentId}/processing-runs
Authorization: Bearer <backend-access-token>
Idempotency-Key: synthetic-processing-001
Content-Type: application/json

{"expectedAttempt": 1, "scrubPII": true, "reason": "Process a stored synthetic report"}

Obtain expectedAttempt from GET /documents/{documentId}/processing-status. Eligibility is reported by canProcess and an optional safe processingBlockReason; eligibility does not grant authority. Initiation needs documents:process, a current document-specific processing Access Decision, verified integration binding and applicable processing consent. Polling the receipt needs operations:read plus operation-specific authority.

The command enables data extraction. Omitting scrubPII preserves the stored scrubbing policy; passing scrubPII: true enables it if initially disabled, or retains it if already enabled. scrubPII: false is invalid and returns HTTP 422 (validation_failed). Unlike uploads, processing requests have no default for this optional field.

Stored scrubPII Processing request Effective scrubPII
false omitted false
false true true
true omitted true
true true true
either false Invalid — HTTP 422

The effective scrubPII policy is durably recorded with the accepted attempt and returned in its operation receipt. A queued receipt is not proof that scrubbing has completed. To enable scrubbing, the owner must scrub suitable retained input before downstream classification/extraction; an existing unscrubbed checkpoint cannot skip this step. Missing suitable input returns processing_input_unavailable. Retained historical artifacts remain governed by owner retention/access policy; enabling scrubbing does not promise retroactive modification of previous immutable publications.

The request accepts no bytes, storage URL, pipeline stage, model override or inferred metadata. The owner chooses safe retained input; scrubbing cannot be disabled and already scrubbed information cannot be restored. Processing never bypasses upload completion, malware/integrity checks, supported-format checks, mandatory review or erasure fences. All authority and retention prerequisites are rechecked at execution.

HTTP 202 returns a DocumentProcessingOperation receipt with documentId, the accepted attempt, and a Location for GET /operations/{operationId}. The type is document_processing for first-time extraction and reprocessing for subsequent runs. Honour Retry-After. Operation success means DIP completed this specific attempt; use processing-status to check publication and patient-record availability separately. It always describes the latest attempt, which may differ from the receipt being polled. Document webhooks are wake-up signals; correlate completion through the operation.

An identical request with the same idempotency key returns the same receipt for 24 hours. A changed payload under that key returns 409. A fresh request checks the expected attempt atomically and allows no concurrent queued/active run. Stale attempts, active work, missing retained input, non-eligible documents, erasure in progress or unresolved mandatory review return HTTP 409 with a safe code. Invalid input returns 422; rate limits return 429 and unavailable admission dependencies return 503. Durable receipt/dispatch recording and client-specific authorisation are launch prerequisites.

The document ID and previous immutable publications remain stable. A successful new publication receives a new source revision; failure does not silently overwrite prior clinical evidence. Historical reads retain current access checks.

Read human-review status

GET /documents/{documentId}/reviews is a proposed read-only projection of normalization review work. It requires reviews:read and access to the document. Accepting, correcting and rejecting extracted evidence require a separately designed reviewer role.

Preserve document ID, source revision and observation identity when storing a result in the partner application. Reprocessing can create a new immutable source publication. An older cached publication must not silently become the new revision.

Downloads and deletion

The draft file endpoint returns an authorized short-lived link. Stored ENO Envelope Objects are ciphertext; raw bucket downloads are not the plaintext file API. Every download retains authorization, decryption and audit rules.

Account erasure uses an asynchronous operation receipt. The document-delete initiation contract still needs alignment with service-owned asynchronous cleanup, holds and downstream evidence removal; do not interpret the draft's 204 response as verified removal of all retained copies.

Continue with snapshots, webhooks and retry rules.

Partner API 0.1.0-draft.3 · Draft contract · Sandbox and SDK availability require confirmation.