Skip to navigation
Overview

Overview

The Form-fill API turns a clinical document into structured answers. Send the document’s text with either:

  • a FHIR R4 Questionnaire, and get back a FHIR R4 QuestionnaireResponse filled from the document; or
  • a list of questions in plain language (“What was the most recent HbA1c?”), and get back a typed answer to each.

Every answer comes with a confidence between 0 and 1 and the verbatim evidence it was taken from, including its character position in your text, so your users can see exactly where each answer came from. A question the document does not answer is marked not_found.

How a request works

The API is asynchronous. You submit a job, wait for it to finish, then download the result once.

POST   /v1/jobs              → 202, the job: {"id": "job_…", "status": "queued", …}
GET    /v1/jobs/{id}         → status: queued → running → succeeded | failed | canceled
GET    /v1/jobs/{id}/result  → the result, once; a second request returns 410
DELETE /v1/jobs/{id}         → cancel the job, or delete its unread result

A job usually finishes within 5 to 10 seconds. Poll its status every second or two, or give a callback_url and receive a webhook when it finishes.

AuthenticationAuthorization: Bearer <key>, using an API key or an OAuth 2.0 access token with the formfill:process scope
FormatJSON in and out
InputUTF-8 text, up to 64 KiB per document
ResultsDownloadable once; a job expires 24 hours after submission
BillingOne document per job, billed to the organization that owns the key

Two kinds of job

QuestionnaireQuestions
You sendA FHIR R4 QuestionnaireUp to 100 questions, as strings or typed objects
You getA FHIR R4 QuestionnaireResponseOne typed answer per question, in your order
Coded answersOnly codes from your options (inline, or a contained ValueSet)Only values from your options
Form logicenableWhen and repeats are honoured; weighted scores are calculatedmultiple questions return a list
Completenessstatus is completed, or in-progress with the missing required items listedEach answer is answered or not_found
GuideFilling a QuestionnaireAsking questions

Negation, uncertainty and history are taken into account for both kinds of job, so “no perineural invasion” is not read as a positive finding, and a condition the document places in the past is not reported as current.

Versioning

The API is versioned in the path (/v1). Changes within v1 are additive: new optional fields, new error codes, new job types. Ignore fields you do not recognise. A breaking change will come as a new version, with advance notice.

Every result carries a pipeline_version, which identifies the release that produced it.

Support

Email support@emtelligent.com, quoting the request_id from an error response or the job id.