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.
2. Register or link the intended patient
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.