Submit a study

One request uploads the DICOM study and starts the AI read.

Submitting is one call: POST /studies with the file as multipart form data. The study is stored and the read starts in the same request. The response is the study object, the same shape GET /studies/{study_id} returns.

Submit

curl -s -X POST "https://api.vitalview.ai/v1/studies" \
  -H "X-API-Key: $KEY" \
  -F "file=@study.zip" \
  -F "scan_type=ct_brain" \
  -F "patient[name]=DOE^JANE" \
  -F "patient[dob]=1980-01-01" \
  -F "patient[gender]=F" \
  -F "clinical_indication=Fall with loss of consciousness" \
  -F "callback_url=https://your-host.example/vitalview-hook"

Response (201):

{
  "study_id": "a1b2c3d4",
  "status": "queued",
  "step": null,
  "slices": null,
  "slices_read": null,
  "scan_type": "ct_brain",
  "quality": "smart",
  "patient": { "name": "DOE^JANE", "dob": "1980-01-01", "gender": "F" },
  "clinical_indication": "Fall with loss of consciousness",
  "created_at": "2026-07-05T09:12:44Z",
  "started_at": null,
  "completed_at": null,
  "error": null,
  "report": null
}

Form fields:

Field	Required	Notes
`file`	yes	A `.zip` containing the DICOM study, or a single `.dcm` slice. Up to 3 GB
`scan_type`	no	`ct_brain`, `ct_chest`, `ct_abdomen`, `ct_whole_body`, and other CT body regions. Omit it to detect it from the DICOM header; if the header does not say, you get `422 scan_type_undetected` and resubmit with `scan_type`
`patient[name]`	no	Patient name supplied by your integration. It is not automatically populated from DICOM; omit it to leave the API name empty
`patient[dob]`, `patient[gender]`	no	DOB (`YYYY-MM-DD`) and gender (`M`, `F` or `O`). DICOM birth date and sex take precedence when present; these form values are fallbacks
`clinical_indication`	no	Free text shown to the reader and on the report
`series_uid`	no	DICOM SeriesInstanceUID to read. Omit it and the best processable series is selected
`quality`	no	`fast`, `smart` (default) or `max`
`callback_url`	no	HTTPS URL we POST the finished read to, so you do not have to poll

See Retrieve results for callback payloads, signature verification and delivery requirements.

Send only the minimum patient demographics your workflow requires. Data is processed under your service agreement.

Series selection

A .zip may hold several series. We inspect the upload and pick the best processable one. If your PACS already knows which series to send, pass series_uid.

If the study cannot be read, nothing is kept: the request fails with 422 no_processable_series, 422 series_not_found or 422 scan_type_undetected, each carrying detected_series (every series found, with the reason any was not processable), and you resubmit with the corrected fields.

Retries

Send an Idempotency-Key header, any string up to 255 characters unique to the submission. A repeat of the same request returns the study the first one created instead of a second study and a second transfer. Without it, a response lost in transit cannot be told apart from a failed submit.

Next: Retrieve results