> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.emtelligent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emtelligent.com/_mcp/server.

# 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](/formfill/guides/webhooks)
when it finishes.

|                    |                                                                                                                                                                 |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authentication** | `Authorization: Bearer <key>`, using an [API key](/platform/api-keys) or an [OAuth 2.0 access token](/platform/oauth-clients) with the `formfill:process` scope |
| **Format**         | JSON in and out                                                                                                                                                 |
| **Input**          | UTF-8 text, up to 64 KiB per document                                                                                                                           |
| **Results**        | Downloadable once; a job expires 24 hours after submission                                                                                                      |
| **Billing**        | One document per job, billed to the organization that owns the key                                                                                              |

## Two kinds of job

|                   | Questionnaire                                                                    | Questions                                        |
| ----------------- | -------------------------------------------------------------------------------- | ------------------------------------------------ |
| **You send**      | A FHIR R4 Questionnaire                                                          | Up to 100 questions, as strings or typed objects |
| **You get**       | A FHIR R4 QuestionnaireResponse                                                  | One typed answer per question, in your order     |
| **Coded answers** | Only codes from your options (inline, or a contained ValueSet)                   | Only values from your `options`                  |
| **Form logic**    | `enableWhen` and `repeats` are honoured; weighted scores are calculated          | `multiple` questions return a list               |
| **Completeness**  | `status` is `completed`, or `in-progress` with the missing required items listed | Each answer is `answered` or `not_found`         |
| **Guide**         | [Filling a Questionnaire](/formfill/guides/questionnaires)                       | [Asking questions](/formfill/guides/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](mailto:support@emtelligent.com), quoting the
`request_id` from an error response or the job `id`.