Your first document integration

This walkthrough illustrates the draft contract. It has not been run against a live partner sandbox. Use the base URL and token URL confirmed during onboarding; the token endpoint's final deployment path remains to be confirmed.

Before you begin

Obtain sandbox credentials, the confirmed token URL, a synthetic document and an authorized synthetic patient relationship. Request only the scopes your integration needs. Never place a client secret in a browser, mobile app or public repository.

export ENO_API_BASE="https://sandbox.api.eno.health/v1"
export ENO_TOKEN_URL="<token URL confirmed during onboarding>"
export ENO_CLIENT_ID="<sandbox client ID>"
export ENO_CLIENT_SECRET="<sandbox client secret>"

1. Authenticate from your backend

curl --request POST "$ENO_TOKEN_URL" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=$ENO_CLIENT_ID" \
  --data-urlencode "client_secret=$ENO_CLIENT_SECRET" \
  --data-urlencode 'scope=users:write documents:write documents:read snapshots:read'

Store the returned access token in your backend's credential handling, then set ENO_ACCESS_TOKEN for these examples. The draft token response retains OAuth's standard access_token, token_type and expires_in names.

curl --request POST "$ENO_API_BASE/users" \
  --header "Authorization: Bearer $ENO_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: synthetic-user-demo-001' \
  --data '{"externalId":"demo-patient-001","email":"synthetic.patient@example.com","consents":[{"type":"terms_of_service","version":"2026-09","grantedAt":"2026-10-12T08:00:00Z"},{"type":"health_data_processing","version":"2026-09","grantedAt":"2026-10-12T08:00:00Z"}]}'

Use the returned id as ENO_USER_ID. The consent values above are synthetic fixtures, not evidence that a real person consented. Verified linking of an existing ENO identity and authority to record consent require onboarding agreement.

An active Patient Access Grant and an upload Access Decision are prerequisites for the next step. Registration and processing consent alone do not authorize clinical access. The draft exposes grant reads, not a partner grant-creation endpoint.

3. Upload a synthetic report

curl --request POST "$ENO_API_BASE/users/$ENO_USER_ID/documents" \
  --header "Authorization: Bearer $ENO_ACCESS_TOKEN" \
  --header 'Idempotency-Key: synthetic-report-demo-001' \
  --form 'file=@./synthetic-lab-report.pdf;type=application/pdf' \
  --form 'metadata={"externalId":"demo-report-001","extractData":true,"scrubPII":true};type=application/json'

Both flags default to true when omitted. Never send extractData: false together with scrubPII: false; the draft rejects that combination with HTTP 422 (validation_failed).

Do not send a document category. DIP assigns it asynchronously; the returned document has category: null until a classification result is available.

The draft returns HTTP 202 with a document resource. language, issuers, title and documentDate are not upload inputs; DIP returns these read-only fields only after completing processing and deriving their values. They are absent from the initial receipt. Save its id as ENO_DOCUMENT_ID. A successful transfer does not mean extraction or patient-record publication has finished. Confirm enabled file types and deployment limits during onboarding.

4. Track availability

curl "$ENO_API_BASE/documents/$ENO_DOCUMENT_ID/processing-status" \
  --header "Authorization: Bearer $ENO_ACCESS_TOKEN"

This proposed aggregation distinguishes extraction, publication and Atlas delivery. Wait for availableInPatientRecord: true before presenting published results. Use bounded polling and honor Retry-After; switch to webhook notifications when delivery is available.

5. Retrieve evidence

curl "$ENO_API_BASE/documents/$ENO_DOCUMENT_ID/extraction" \
  --header "Authorization: Bearer $ENO_ACCESS_TOKEN"

curl "$ENO_API_BASE/users/$ENO_USER_ID/snapshots/latest" \
  --header "Authorization: Bearer $ENO_ACCESS_TOKEN"

The extraction describes one document. A snapshot identifies a patient's evidence set and its source revisions. Preserve snapshot identity if the response supports a report or consultation.

Recover from expected failures

Response Next action
401 Renew backend authentication and retry with the original idempotency key.
403 Check both endpoint scopes and patient grants. A fresh token cannot restore a revoked grant.
409 on extraction Processing is not ready; poll status rather than uploading again.
429 Honor Retry-After and back off.
5xx Retry eligible operations with bounded backoff and the same idempotency key.

Continue with document processing, access rules and webhook verification.

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