> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Document

> Upload a lab report or any other document to a profile, and optionally extract its lab values

Upload one file to a profile. Send it as `multipart/form-data`. Without `extract_results`, Aniva only
stores the file. With `extract_results: true`, Aniva also reads the lab values out of the file.

You do not say what kind of report the file is. Aniva decides. A file without lab results, such as
a doctor's letter, ends as `stored` and is not an error.

Read the values with [Get Document Results](https://docs.anivahealth.com/api/documents/get-document-results.md). You do not need to
poll: subscribe to the `document.results.*` [webhooks](https://docs.anivahealth.com/concepts/webhooks.md).

Requires the `documents_upload` scope on a profile group of the profile. `extract_results: true`
also requires the `documents_extract_results` scope on the same group. Ask Aniva to add them. The
document belongs to that group: keys with `results_view` on it read the document and its results.

Send an optional `Idempotency-Key` header to make the upload safe to retry. See
[Idempotency](https://docs.anivahealth.com/concepts/idempotency.md).

## What extraction does

With `extract_results: true`:

1. Aniva sends the file to its OCR and AI subprocessors to read the values.
2. The values appear in the member's Aniva app, like every other result.
3. Each value carries `origin: partner_upload` and the same `status` as every other result. A value
   Aniva's automatic check doubts has status `likely_wrong`.

Without it, the file goes to no outside service when you also send `document_date`.

> **Accuracy and data protection**
>
> * Automated reading can misread a value, a unit or a date. The original file stays the source of
>   truth. Check a value against it before you use it for a medical decision. Extracted values are
>   not a diagnosis.
> * The subprocessors are Mistral AI (OCR, EU) and Google Cloud Vertex AI, reached through the
>   Vercel AI Gateway (extraction, may process outside the EU). They process the file only to read
>   it.
> * You need a legal basis to upload a member's health data, normally the member's explicit
>   consent. You are responsible for it.

## Request

### Form fields

**file** `file` *required*

The file. PDF, DOC, DOCX, PNG or JPEG, at most 4 MB.

**profile\_id** `string` *required*

UUID of the profile the document belongs to.

**extract\_results** `boolean` (default: false)

`true` to read the lab values out of the file. Send `true` or `false`.

**document\_date** `string`

The sample date in `YYYY-MM-DD` format, when you know it. Without it, Aniva reads the date from the
file.

## Response

The API returns `201 Created` when it only stored the file, and `202 Accepted` when extraction runs.

**id** `string` *required*

Document ID (UUID). Use it with [Get Document Results](https://docs.anivahealth.com/api/documents/get-document-results.md) and
[Download Document](https://docs.anivahealth.com/api/documents/download-document.md).

**status** `string` *required*

`processing` while Aniva extracts the values, or `stored` when the file is only stored.

**profile\_id** `string` *required*

The profile the document belongs to.

**document\_date** `string`

The sample date you sent, or the one Aniva read from a stored file. May be `null`.

**results\_url** `string` *required*

The [Get Document Results](https://docs.anivahealth.com/api/documents/get-document-results.md) URL of this document.

**file\_name** `string` *required*

File name for display, the same one [Download Document](https://docs.anivahealth.com/api/documents/download-document.md) sends.

**original\_file\_name** `string` *required*

The file name you uploaded.

**origin** `string` *required*

Always `partner_upload`.

**content\_type** `string` *required*

Media type of the file, e.g. `application/pdf`.

**etag** `string`

Version of the file content. May be `null`.

**size\_bytes** `integer`

File size in bytes. May be `null`.

**lab\_code** `string`

Always `null` for an uploaded document.

## Error responses

| Status | Description |
| - | - |
| `400` | A form field is invalid, or the body is not `multipart/form-data`. |
| `403` | Your API key lacks a scope, the profile is outside your access context, or you sent `extract_results: true` without `documents_extract_results`. |
| `404` | Profile not found. |
| `409` | `duplicate_document`: the same file is already on this profile. `document_id` names it, or is `null` when you cannot read it. Also sent for an `Idempotency-Key` conflict. |
| `413` | `file_too_large`: the file is over 4 MB. |
| `415` | `unsupported_media_type`: the file is not a PDF, DOC, DOCX, PNG or JPEG. The file name must end in `.pdf`, `.doc`, `.docx`, `.png`, `.jpg` or `.jpeg`. |
| `500` | Internal server error. `extraction_not_started`: the file is stored as `document_id`, but extraction could not start. Contact Aniva. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/documents \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: 5f0c2d9e-3b7a-4c1e-9f62-1d8a4e7b0c55' \
  --form 'file=@lab-report.pdf' \
  --form 'profile_id=b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e' \
  --form 'extract_results=true'
```

```json 202 theme={null}
{
  "id": "f8a1b2c3-d4e5-4f6a-8b8c-9d0e1f2a3b4c",
  "status": "processing",
  "profile_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "document_date": null,
  "results_url": "https://anivahealth.com/api/v1/documents/f8a1b2c3-d4e5-4f6a-8b8c-9d0e1f2a3b4c/results",
  "file_name": "20261023 - lab-report.pdf",
  "original_file_name": "lab-report.pdf",
  "origin": "partner_upload",
  "content_type": "application/pdf",
  "etag": "56104b36f860cfd5b41efc716fdf7b6f",
  "size_bytes": 312480,
  "lab_code": null
}
```

```json 409 theme={null}
{
  "error": "duplicate_document",
  "message": "This file is already on this profile",
  "document_id": "f8a1b2c3-d4e5-4f6a-8b8c-9d0e1f2a3b4c"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.