Documents
Upload Document
Upload a lab report or any other document to a profile, and optionally extract its lab values
POST
/
api
/
v1
/
documents
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'
{
"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
}
{
"error": "duplicate_document",
"message": "This file is already on this profile",
"document_id": "f8a1b2c3-d4e5-4f6a-8b8c-9d0e1f2a3b4c"
}
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. You do not need to
poll: subscribe to the document.results.* webhooks.
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.
What extraction does
Withextract_results: true:
- Aniva sends the file to its OCR and AI subprocessors to read the values.
- The values appear in the member’s Aniva app, like every other result.
- Each value carries
origin: partner_uploadand the samestatusas every other result. A value Aniva’s automatic check doubts has statuslikely_wrong.
document_date.
Accuracy and data protection
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
required
The file. PDF, DOC, DOCX, PNG or JPEG, at most 4 MB.
string
required
UUID of the profile the document belongs to.
boolean
default:"false"
true to read the lab values out of the file. Send true or false.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 returns201 Created when it only stored the file, and 202 Accepted when extraction runs.
string
required
Document ID (UUID). Use it with Get Document Results and
Download Document.
string
required
processing while Aniva extracts the values, or stored when the file is only stored.string
required
The profile the document belongs to.
string
The sample date you sent, or the one Aniva read from a stored file. May be
null.string
required
The Get Document Results URL of this document.
string
required
File name for display, the same one Download Document sends.
string
required
The file name you uploaded.
string
required
Always
partner_upload.string
required
Media type of the file, e.g.
application/pdf.string
Version of the file content. May be
null.integer
File size in bytes. May be
null.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. |
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'
{
"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
}
{
"error": "duplicate_document",
"message": "This file is already on this profile",
"document_id": "f8a1b2c3-d4e5-4f6a-8b8c-9d0e1f2a3b4c"
}
⌘I
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'
{
"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
}
{
"error": "duplicate_document",
"message": "This file is already on this profile",
"document_id": "f8a1b2c3-d4e5-4f6a-8b8c-9d0e1f2a3b4c"
}