Upload one batch item

POST/fhir2omop/batch/{job_id}/items

Stores one item: the body of one POST /fhir2omop/create request, with vocab_version required.

Upload checks only that fhir_resources is a JSON object and that vocab_version names a specific release. The FHIR content, and whether the release exists, are checked when the item is processed: input that POST /fhir2omop/create would reject with a 400 fails the item with invalid_input and the same message.

Use request_id for every upload so retries replace the same item. deduplicated is true only for an unchanged payload; a changed payload overwrites the item and returns false.

Uploads return 409 after finalization or at the item limit, and 413 when the item is too large.

RequiresBearerauthentication

Path parameters

job_idstringrequired

Body parameters

fhir_resourcesobjectrequired

A FHIR R4 resource or Bundle, the same as fhir_resources on POST /fhir2omop/create. Must contain at least one Patient resource for the item to succeed.

vocab_versionstringrequired

OMOP vocabulary release the item maps against, the same setting as vocab_version on POST /fhir2omop/create. Required here, and it must name a specific release: an item has no default release.

request_idstringoptional

Optional idempotency token (at most 256 UTF-8 bytes). Re-uploading under the same token overwrites the same item instead of adding a new one. The token is scoped to this job; the same token in another job is independent and creates a separate item.

idstringoptional

Optional caller-supplied correlation label (at most 512 UTF-8 bytes), echoed back on status and result listings so you can match the server's item_id to your own record.

Returns

Item accepted

Response fields

job_idstringoptional

request_idstringoptional

statusstringoptional

finalizedbooleanoptional

total_itemsintegeroptional

errorobjectoptional

kindstringoptional

messagestringoptional

created_atstringoptional

updated_atstringoptional

completed_atstringoptional

expires_atstringoptional

item_idstringoptional

idstringoptional

deduplicatedbooleanoptional

POSTRequest

# Get authentication token
PHENOML_TOKEN=$(curl -X POST "https://experiment.app.pheno.ml/v2/auth/token" \
  -u "$PHENOML_CLIENT_ID:$PHENOML_CLIENT_SECRET" \
  | jq -r '.access_token')

curl -X POST "https://experiment.app.pheno.ml/fhir2omop/batch/{job_id}/items" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "patient-000123",
  "request_id": "omop-cohort-2026-11-02-001-patient-000123",
  "vocab_version": "v20260829",
  "fhir_resources": {
    "resourceType": "Bundle",
    "type": "collection",
    "entry": [
      {
        "resource": {
          "resourceType": "Patient",
          "id": "patient-000123",
          "gender": "female",
          "birthDate": "1985-07-22"
        }
      },
      {
        "resource": {
          "resourceType": "Condition",
          "id": "condition-1",
          "subject": {
            "reference": "Patient/patient-000123"
          },
          "onsetDateTime": "2024-01-01",
          "code": {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "44054006",
                "display": "Type 2 diabetes mellitus"
              }
            ]
          }
        }
      }
    ]
  }
}'

202 AcceptedExample Response

{
  "job_id": "f2o_batch_6f1d2c3a-8b4e-4f5a-9c7d-0e1f2a3b4c5d",
  "request_id": "omop-cohort-2026-11-02-001",
  "status": "pending",
  "finalized": false,
  "total_items": 12,
  "error": {
    "kind": "invalid_input",
    "message": "no Patient resource found; OMOP requires at least one person"
  },
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "completed_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z",
  "item_id": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "id": "patient-000123",
  "deduplicated": false
}