Quickstart

Send clinical notes in a batch and read back coded entities. This guide uses a test client, which returns fixture results and never processes real data. Live clients make the same calls.

You need a client ID and secret from Amorphous. Test client IDs start with amh_test_.

Step	Request
1. Get a token	POST /oauth/token
2. Create a batch	POST /v1/data-engine/batches
3. Add documents	POST /v1/data-engine/batches/{batchId}/documents
4. Submit	POST /v1/data-engine/batches/{batchId}/submit
5. Poll	GET /v1/data-engine/batches/{batchId}
6. Read results	GET /v1/data-engine/batches/{batchId}/results

1. Get a Token

curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=batches:write batches:read" \
  https://api.amorphous.health/oauth/token

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "batches:write batches:read"
}

Reuse the token until it is about to expire. See Authentication.

2. Create a Batch

curl -s -X POST https://api.amorphous.health/v1/data-engine/batches \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"externalReference":"nightly-2026-10-08","metadata":{"site":"north"}}'

{
  "object": "data_engine.batch",
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "liveMode": false,
  "status": "pending",
  "externalReference": "nightly-2026-10-08",
  "metadata": { "site": "north" },
  "counts": {
    "total": 0,
    "awaitingUpload": 0,
    "pending": 0,
    "queued": 0,
    "processing": 0,
    "succeeded": 0,
    "failed": 0,
    "cancelled": 0
  },
  "cancellationReason": null,
  "createdAt": "2026-10-08T09:00:00Z",
  "submittedAt": null,
  "completedAt": null,
  "expiresAt": "2026-10-15T09:00:00Z"
}

Save id. externalReference is optional, but send one if you might retry: a repeat create returns 409 with existingBatchId.

3. Add Documents

curl -s -X POST \
  "https://api.amorphous.health/v1/data-engine/batches/$BATCH_ID/documents" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "externalReference": "note-8841",
        "mediaType": "text/plain",
        "content": "Clinical note text"
      }
    ]
  }'

The response lists the created documents. Save each document id. Inline text is limited to 1 MiB. For PDFs and larger files, see Uploading Files.

4. Submit

curl -s -X POST \
  "https://api.amorphous.health/v1/data-engine/batches/$BATCH_ID/submit" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Submit fails while any document is awaiting_upload. Live clients can submit once Amorphous enables live processing for your organization.

5. Poll

curl -s \
  "https://api.amorphous.health/v1/data-engine/batches/$BATCH_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

While status is processing, wait for Retry-After (10 seconds) between polls. Stop at completed or cancelled. A completed batch can contain failed documents, so check each document's status.

6. Read Results

Stream every document in a completed batch as NDJSON:

curl -s \
  "https://api.amorphous.health/v1/data-engine/batches/$BATCH_ID/results" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/x-ndjson"

Or page through one document's entities:

curl -s \
  "https://api.amorphous.health/v1/data-engine/batches/$BATCH_ID/documents/$DOCUMENT_ID/entities" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

See Pagination and Results for the entity fields.