1. Get started
1.1 Your first request
Submit a job, then fetch its result. Start here for a working request; use Swagger UI when you want to inspect every field interactively.
/v1/process/upload. A quick-evaluation sandbox key needs only the Authorization header; partner-parity sandbox uses the pairing-code header described below.Choose the tool that fits your workflow
Skipping curl? Drop your sandbox key into Try It Live in the browser, or import the Postman collection — both run the full integration in under a minute.
Document mode: Notes → Report
Send clinical notes, get a structured report back. No prompt_id required — the default
template handles standard consultation notes. (Add audio + tardoc:true for the full
transcription + report + Swiss billing-code chain — see Try with Real Data.)
· Run this in the playground →
# Requires curl + jq. Runs end-to-end without copying the job ID. JOB_ID=$(curl -fsS -X POST https://api.documenter.ch/v1/process/upload \ -H "Authorization: Bearer YOUR_SANDBOX_KEY" \ -F "mode=document" \ -F "text=Patient de 45 ans. Cephalees frontales bilaterales depuis 2 semaines. TA 130/85. Examen neurologique normal. Paracetamol 1g x3/jour." \ -F "locale=fr" | jq -er '.job_id') curl -fsS "https://api.documenter.ch/v1/process/$JOB_ID" \ -H "Authorization: Bearer YOUR_SANDBOX_KEY" | jq
import time import httpx headers = {"Authorization": "Bearer YOUR_SANDBOX_KEY"} deadline = time.monotonic() + 300 with httpx.Client(timeout=30) as client: resp = client.post("https://api.documenter.ch/v1/process/upload", headers=headers, data={ "mode": "document", "text": "Patient de 45 ans. Cephalees frontales...", "locale": "fr", }) resp.raise_for_status() job_id = resp.json()["job_id"] while time.monotonic() < deadline: resp = client.get(f"https://api.documenter.ch/v1/process/{job_id}", headers=headers) resp.raise_for_status() result = resp.json() if result["status"] in ("completed", "error", "cancelled"): break time.sleep(5) else: raise TimeoutError(f"Job {job_id} did not finish within 5 minutes") if result["status"] == "error": raise RuntimeError(result["error"]) if result["status"] == "cancelled": raise RuntimeError("Job was cancelled") report_html = result["results"]["generation"]["content"]
Using C#, Java, PHP, or another stack? Import the OpenAPI spec to generate a typed client instead of translating this example by hand.
Response
{
"status": "completed",
"results": {
"generation": {
"content": "<article class=\"documenter-report\">\n <section data-key=\"anamnese\">\n <h2>Anamnèse</h2>\n<p>Patient de 45 ans...</p>\n </section>\n</article>",
"format": "html",
"tokens_out": 420
}
}
}
# Want TARDOC billing codes? Add "tardoc": true with audio — see the audio example below.
Want to send real audio + PDFs together? See Try with Real Data. Don't want to install anything? Try It Live in your browser (paste your sandbox key, no install needed).
1.2 Sandbox vs production
Everything below is exercisable entirely in sandbox — no production key or real physician code required. Build and self-test your whole integration against three fake pairing codes, then flip a handful of values to go live.
The test triad
Like Stripe's test cards, three fake pairing codes drive all three plan tiers in sandbox. Put a code in
X-User-Token: GET /v1/entitlements returns that tier's capabilities, and submits behave
exactly as the live tier gate would. Use the fixed codes below with a sandbox partner key minted
in your organisation’s developer console.
Each code is a different doctor. The three synthetic physicians carry DIFFERENT saved preferences, so switching code changes the output the way switching doctor does in production — which is what lets you assert on per-doctor resolution rather than on one anonymous default. They are SHARED, READ-ONLY fixtures: every partner testing against sandbox resolves the same three doctors, so the values below are stable and are re-seeded if anything edits them. To test against your OWN saved preferences, use your own pairing code with your organisation’s sandbox key — your real subscription, tier and entitlements apply then, exactly as they will live.
| Pairing code | Tier | Renaming settings (results.renaming.format) |
Personal instruction (a real prompt_id you can pass) |
|---|---|---|---|
DOC-SBXSCRB1 |
Scribe | surname, birthdate, docdate, doctype, type_detail (the platform default)NOM (DDN) - DATE Type Détail |
Sandbox — Note de suite (Scribe)titre, motif_consultation, anamnese, traitements |
DOC-SBXIAST2 |
IA-ssistant | doctype, surname, docdateType - NOM DATE |
private prompttitre, motif_consultation, appreciation, suivi — deliberately shorter than the house default, so switching prompt_id visibly changes the output |
DOC-SBXPRO03 |
IA-ssistant Pro | surname, docdate, type_detail, sourceNOM - DATE - Détail - Établissement |
Sandbox — Rapport détaillé (Pro)titre, motif_consultation, anamnese, examen_clinique, appreciation, suivi |
| Pairing code (tier) | /v1/entitlements → capabilities |
Submit behavior |
|---|---|---|
Scribe (tier 1)DOC-SBXSCRB1 |
transcription:true, generation_from_transcript:true, generation_from_documents:false, tardoc:false, form_fill:false |
Transcript-grounded generation only. Uploading documents or free-text notes → 403 DOC_BILL_001 (nothing runs), and so does mode: "form". tardoc:true is dropped with a DOC_BILL_002 billing_notices[] entry (transcript + note still returned). |
IA-ssistant (tier 2)DOC-SBXIAST2 |
generation_from_documents:true, form_fill:true, tardoc:false (others true) |
Documents, notes and mode: "form" all run normally. tardoc:true is dropped with a DOC_BILL_002 billing_notices[] entry. |
IA-ssistant Pro (tier 3)DOC-SBXPRO03 |
All five true |
Documents, forms and tardoc all run — the full transcription + report + Swiss billing-code chain. |
Sandbox jobs produce a synthetic result rather than running a model, so real latency and the
pairing-code lifecycle are not exercised (see Authentication). The poll
ladder IS: a sandbox submit returns 202 {"status": "processing"} and the job becomes
completed on your first poll, so the state machine and the webhook timing you build
against are the ones you will meet live. (One exception, by construction:
mode: "form"
really parses and really renders your form in sandbox, so it stays processing for a few
seconds and completes on a later poll — only the answers are synthetic.) Everything else — auth, tier gates, entitlements,
per-key rate and concurrency limits, idempotency, webhook signatures — matches production.
The sandbox runs the SAME pipeline as production with the model mocked: your organisation’s field
map is applied to the result, the acting physician’s own preferences and naming convention resolve
exactly as they would live, and the output formats are identical. Only generated report text and
transcription content are synthetic.
Sandbox → production: what changes, what stays
Migrating is a small, well-defined swap — four things change; your integration logic does not.
| Changes | Stays the same |
|---|---|
|
|
1.3 Go-live checklist
- Idempotency: send a unique
Idempotency-Keyper logical job so retries are safe (see Request shape → Idempotency). - Retry / backoff: on
429and503, honor theRetry-Afterheader before retrying — do not hammer, and do not rotate your key on a503. - Webhooks: verify
X-Webhook-Signaturebefore processing, and dedup onX-Webhook-Delivery-ID(constant across retries of one payload) — process each delivery once. - Bounded polling: terminate on
statusincompleted/error/cancelled. A cancelled job never becomes completed, so a loop that waits only forcompletedspins forever. - HTTP status first: check the response status code before parsing the body as a job — a
4xx/5xxbody is an error envelope, not a job. -
Entitlement → UI capability map (from
GET /v1/entitlements; always treat per-requestbilling_notices[]as the runtime authority):transcription→ the transcript-only pathgeneration_from_transcript→ audio-to-notegeneration_from_documents→ PDF / DOCX / notes generationform_fill→ the fill-a-form action (mode: "form")tardoc→ the TARDOC toggle
- Key rotation: rotate keys from the developer console on documenter.ch; pairings are org-bound and survive rotation, so physicians do not re-pair.
- Alerting: alert on sustained
4xx(integration bug) and5xx(retry, then escalate) rates; quote theX-Request-Idof any failing response in support tickets.
2. Authenticate
How many headers a request needs depends on the key:
| Environment | Required headers |
|---|---|
Quick-evaluation sandbox (doc_test_) |
API key only. Physician auth and plan gates are bypassed so you can make a first request quickly. |
Partner-parity sandbox (doc_test_) |
API key + X-User-Token containing one of the supplied fake pairing codes. This is the sandbox to use for production integration testing. |
Production (doc_partner_ / doc_live_) |
API key + X-User-Token — the physician identifier (a pairing code or a signed JWT, per your integration model below). |
doc_test_) skips the
JWT / pairing-code / subscription / billing checks and returns mock results — just the
API key is enough, no X-User-Token needed. Request validation still applies: the
body schema, prompt resolution, file/document extraction (a corrupt file still returns
400 DOC_VAL_001), the tardoc-needs-audio rule, the webhook SSRF guard, and the
Idempotency-Key length cap all run exactly as on a live key — so what you validate in
sandbox matches production. Sandbox keys are created by your organisation’s members in Settings → Developers, once DOCumenter has registered your organisation — write to dev@documenter.ch to get registered (response within 1 business hour). The key and the three parity pairing codes are shown together, so you can call the API immediately. A sandbox key needs no contract: it runs the production pipeline against a mock model and never touches patient content.
/v1/entitlements —
against the tier the pairing code carries; only the generated report is mocked (returned instantly). You pick the
simulated plan by which pairing code you put in X-User-Token. The per-tier
behavior, and what the sandbox does and does not simulate, are laid out in
Sandbox vs production → The test triad.
Curated prompts. GET /v1/prompts on a sandbox partner key returns exactly three
stable prompts — Rapport de consultation, Synthese de dossier, Courrier medical
— and those are the only prompt_ids a submit accepts (any other returns
404 DOC_VAL_007; omitting it uses Rapport de consultation). The generated report
varies by prompt AND by what you sent: it reflects a transcript section when you include audio, a
documents section when you upload files, and a notes line when you send free text — across all four locales
(fr/de/it/en), rendered exactly as a live key would render it.
The primary path for EHR vendors. Individual physicians subscribe on documenter.ch and
self-provision a pairing code — no JWT signing, no token expiry to manage. Every
/v1/process request carries two headers. Every API key is issued a
signing secret at creation time; it is only required if you verify webhook signatures
— polling-only integrations can ignore it.
| Header | Value | Purpose |
|---|---|---|
Authorization |
Bearer doc_partner_<secret> |
Your EHR vendor API key — the secret. Admin-minted by DOCumenter and issued to you out-of-band. One key per vendor; never expose it client-side. |
X-User-Token |
DOC-XXXXXXXX |
The physician's pairing code — an identifier, not a secret (like an IBAN). It says which physician's DOCumenter subscription this request bills against. |
How it works
One-time setup per physician: the doctor logs in to
documenter.ch, opens their Profile page, finds the “Patient record integration” card, creates a
pairing code (e.g., DOC-A7K2M3P9) — generated on demand, never minted automatically — and pastes it into your EHR's settings panel. Done. They
self-provision — you never handle their credentials.
The pairing code is not a secret; it's an identifier. The physician can't call the API with it alone (they don't have your partner key), and your key alone can't act for a physician (it has no pairing code). Security comes from the combination of both headers — the secret API key plus the physician identifier.
# Partner integration: secret API key + physician pairing code. That's it. curl -X POST https://api.documenter.ch/v1/process \ -H "Authorization: Bearer doc_partner_YOUR_KEY" \ -H "X-User-Token: DOC-A7K2M3P9" \ -H "Content-Type: application/json" \ -d '{"mode":"document","content":"..."}' # Full body in Quickstart above.
/v1/process submit (any mode — document, transcript, chat, or rename) binds the code to your EHR
vendor (trust-on-first-use): after that only your keys can use that
code — another vendor’s keys are rejected, and a physician switching EHR vendors regenerates the code
to re-pair. Regenerating from the “Patient record integration” card revokes the old code immediately. A
code that is unknown, revoked, expired, never-activated, or bound to a different vendor returns
401 DOC_AUTH_005 — prompt the physician to paste a fresh code. The token is matched case- and
whitespace-insensitively, with or without the DOC- prefix.
Partner auth errors:
DOC_AUTH_001 (invalid key) and DOC_AUTH_002 (revoked key) are 401;
DOC_AUTH_005 (pairing code missing, unknown, revoked, expired, never-activated, or bound to another vendor) is 401; and if the paired
physician has no active subscription, the API returns 403 DOC_SUB_001 with a link to subscribe.
For hospitals and institutions that buy physician licenses. Your IT signs a JWT for each physician.
| Header | Value | Purpose |
|---|---|---|
Authorization |
Bearer doc_live_xxx... |
Your institution |
X-User-Token |
eyJhbGci... |
Physician JWT (signed with your signing secret) |
# Institution integration: API key + signed physician JWT curl -X POST https://api.documenter.ch/v1/process \ -H "Authorization: Bearer doc_live_YOUR_KEY" \ -H "X-User-Token: YOUR_PHYSICIAN_JWT" \ -H "Content-Type: application/json" \ -d '{"mode":"document","content":"..."}' # Full body in Quickstart above.
Sign a Physician JWT
Your backend signs a short-lived JWT using HS256 with the signing secret provided with your
API key. Required claims: sub, name, org, exp.
| Claim | Rules |
|---|---|
sub |
The physician's identity. Must be stable across every request for that physician —
it drives physician identity, license counting, and prompt scoping, so a value that changes between
requests fragments their history and can over-count seats. Non-empty (rejected as
401 DOC_AUTH_004 if blank/whitespace) and ≤ 255 characters. Use a durable
id from your directory (e.g. an email or a stable internal user id), not a per-session token.
|
exp |
Expiry (Unix seconds). Keep tokens short-lived. Validation allows ±5 minutes of
clock skew, so your signer and our verifier don't need perfectly synced clocks. An expired token returns
401 DOC_AUTH_003.
|
name, org |
Display name and organization label, for attribution and reporting. |
import jwt, time token = jwt.encode({ "sub": "dr.muller@chuv.ch", "name": "Dr. Sarah Mueller", "org": "CHUV", "iat": int(time.time()), "exp": int(time.time()) + 3600, }, "your_signing_secret", algorithm="HS256")
using System.IdentityModel.Tokens.Jwt; using Microsoft.IdentityModel.Tokens; var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("your_signing_secret")); var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256); var token = new JwtSecurityToken( claims: new[] { new Claim("sub", "dr.muller@chuv.ch"), new Claim("name", "Dr. Sarah Mueller"), new Claim("org", "CHUV"), }, expires: DateTime.UtcNow.AddHours(1), signingCredentials: creds ); string jwt = new JwtSecurityTokenHandler().WriteToken(token);
import io.jsonwebtoken.Jwts; import io.jsonwebtoken.security.Keys; var key = Keys.hmacShaKeyFor("your_signing_secret".getBytes()); String token = Jwts.builder() .claim("sub", "dr.muller@chuv.ch") .claim("name", "Dr. Sarah Mueller") .claim("org", "CHUV") .issuedAt(new Date()) .expiration(new Date(System.currentTimeMillis() + 3600000)) .signWith(key) .compact();
use Firebase\JWT\JWT; $token = JWT::encode([ 'sub' => 'dr.muller@chuv.ch', 'name' => 'Dr. Sarah Mueller', 'org' => 'CHUV', 'iat' => time(), 'exp' => time() + 3600, ], $signingSecret, 'HS256');
If license cap is exceeded (e.g., physician #81 on an 80-seat plan), the API returns 403 with
error code DOC_LIC_001 on every /v1 route except GET /v1/health and
GET /v1/entitlements, which stay reachable for that physician. Slots free up monthly when
physicians stop making requests.
JWT errors (institution mode). The three failure modes return distinct codes so your backend
can react precisely: an expired JWT returns 401 DOC_AUTH_003 (sign a fresh
token), an invalid signature or malformed JWT returns 401 DOC_AUTH_004 (check
your signing secret and encoding), and a missing X-User-Token returns
401 DOC_AUTH_005.
What authentication does not cover.
API-key management (POST / GET / DELETE /v1/keys and
POST /v1/keys/{id}/rotate) is driven from a logged-in browser session on
documenter.ch — not from an API key — so those routes are not
part of the machine-to-machine surface documented here (calling them with a partner key returns
403 DOC_AUTH_006).
2.1 Onboard a doctor (signup intents)
If your organisation is enabled for it (contact dev@documenter.ch), you can
prepare a DOCumenter signup for a doctor and receive their pairing code automatically once they finish. The doctor
still creates the account in their own browser: the account's keys are generated on their device, so no API can
create it for them. These two routes take your API key only (live or sandbox, no
X-User-Token) and have their own budget of 10 requests/minute per key.
| Call | Returns |
|---|---|
POST /v1/partner/signup-intents{email, first_name, last_name, phone?, specialty?, address?, external_ref?, return_url?} |
201 {intent_id, status: "open", signup_url, expires_at}. Send the doctor to
signup_url (valid 7 days, single link). Calling again for the same email while the intent is
open returns 200 with the same intent_id and a new link; the previous link stops
working. specialty is a TARDOC dignity code, external_ref is your own reference
(max 128 chars, echoed back), return_url must be https. 403 DOC_SIGNUP_001 if your
organisation is not enabled. |
GET /v1/partner/signup-intents/{intent_id} |
{intent_id, status, external_ref, pairing_code, completed_at, expires_at, livemode}.
status is open, completed, delivered or
expired. pairing_code is present only during the hour after completion, then
always null. livemode is false for an intent created with a sandbox key. An
intent created by another organisation, or with a key of the other mode (sandbox vs production), returns
404. |
Callback. When the doctor completes the signup, we POST
{"intent_id", "external_ref", "pairing_code", "status": "completed", "livemode"} to the callback URL your organisation
sets in the developer console (/settings/dev; never a URL sent in the request), signed with the creating key's signing secret and the same
headers as job webhooks (X-Webhook-Signature, X-Webhook-Timestamp,
X-Webhook-Delivery-ID = intent_id). A 2xx response is the acknowledgement:
return 2xx only after you have stored the pairing code, and deduplicate on intent_id. Delivery is at-least-once: the same callback can arrive more than once (for example when your 2xx is lost), so treat a repeat as success.
Non-2xx responses and timeouts are retried with backoff for up to 1 hour after completion; after that we stop,
and polling no longer returns the code. If the creating key has been revoked, no callback is sent. With no registered callback URL, poll the GET route within
that hour instead. After the hour (or at expiry), the contact details stored for this intent (name, email, phone, address) are deleted; the account the doctor created keeps its own profile. external_ref and return_url are kept with the intent as an audit record, so do not put personal data in them.
Sandbox. With a doc_test_ key, POST validates the body exactly as live but
creates no account, no trial and no signup page, and stores none of the doctor's contact details (only a keyed hash of the email, so a repeat call within the hour returns the same intent; it is cleared afterwards). It answers
201 {intent_id, status: "completed", signup_url: null, expires_at, pairing_code} right away, where
pairing_code is the IA-ssistant Pro sandbox code listed in your developer console, and fires the
normal signed callback. Polling returns the code for 1 hour, so you can test the whole integration. The same
email within that hour returns the same intent (200). 409 DOC_SIGNUP_008 means no
sandbox code is available in this environment.
Good to know. In production, the pairing code minted for your organisation is bound to it and
never expires until the doctor revokes or regenerates it. Over the 10
requests/minute budget, these routes return 429 DOC_RATE_001 with Retry-After.
| Code | Meaning |
|---|---|
403 DOC_SIGNUP_001 | Your organisation is not enabled for signup intents. |
404 DOC_SIGNUP_002 | Unknown intent_id, one created by another organisation, or one created with a key of the other mode (sandbox vs production). |
409 DOC_SIGNUP_003 | Signup page: the link was already completed by another account. |
410 DOC_SIGNUP_004 | Signup page: the link expired (7 days). |
404 DOC_SIGNUP_005 | Signup page: unknown or replaced link. |
409 DOC_SIGNUP_006 | The doctor is completing this signup right now, so it cannot be re-created with a new link. Poll the intent; if the doctor's attempt fails, the intent is released and can be re-created. |
422 DOC_SIGNUP_007 | Signup page: the doctor used a disposable email address. |
409 DOC_SIGNUP_008 | Sandbox key: no IA-ssistant Pro sandbox pairing code is available in this environment. |
503 DOC_SVC_001 | POST: the intent for this email is locked by a concurrent request. Retry after the Retry-After delay (5 seconds). |
503 DOC_SRV_001 | POST: signup intents are temporarily unavailable on our side. Retry later. |
3. Quickstart
Three copy-pasteable requests: submit text, submit files, poll for the result. Nothing to configure —
no prompt_id, no length, no mapping. Replace
doc_partner_YOUR_KEY with your key and DOC-A7K2M3P9 with the physician's pairing
code (or a signed JWT in institution mode — see Authenticate).
The bodies below came out of the API unedited, except that long clinical strings are cut at their first clause and marked
…. Timestamps and job ids are the ones that run produced.
prompt_id is the shortest path to a usable note.
It selects the platform default instruction — Note de suite — Cabinet at the
equilibre length, the everyday follow-up note. It is a structured instruction,
so output_format: "json" returns the six canonical sections below, in this order:
titre, motif_consultation, anamnese, examen_clinique,
appreciation (titled « Attitude et suivi »), traitements
(titled « Traitement prescrit »). A section with nothing to say is dropped silently,
so treat all six as optional on arrival and route on key, never on position.
Anything else the instruction produces lands on autre, and document chrome such as a closing
salutation lands on unmapped — see Structured JSON output.
3.1 Text only, zero configuration
Post clinical notes as JSON. The pipeline infers a single generation step because there is no
audio to transcribe.
curl -X POST https://api.documenter.ch/v1/process \ -H "Authorization: Bearer doc_partner_YOUR_KEY" \ -H "X-User-Token: DOC-A7K2M3P9" \ -H "Content-Type: application/json" \ -d '{ "mode": "document", "content": "Consultation de suivi, patient de 58 ans connu pour une hypertension arterielle et un diabete de type 2. Revient pour le controle trimestriel. Bonne observance du traitement, aucun episode hypoglycemique. Se plaint depuis trois semaines de douleurs du genou droit a la marche prolongee, sans traumatisme. Pas de fievre, pas de gonflement rapporte. Marche environ trente minutes par jour. Tension arterielle 138/84 mmHg, pouls 72/min regulier, poids 88 kg stable. Auscultation cardiaque et pulmonaire sans particularite. Genou droit sans epanchement, douleur a la palpation de la face interne, mobilite conservee. Derniere HbA1c a 7.1 pourcent il y a trois mois, fonction renale conservee. Poursuite du traitement antihypertenseur et antidiabetique sans changement. Introduction de paracetamol en reserve pour la gonalgie, radiographie du genou droit demandee, controle dans six semaines.", "output_format": "json", "locale": "fr" }'
202 Accepted
{
"job_id": "doc_job_bzZu1Nls1CqRFZPn_wXw_g",
"status": "processing",
"mode": "document",
"steps": ["generation"],
"poll_url": "/v1/process/doc_job_bzZu1Nls1CqRFZPn_wXw_g",
"estimated_seconds": 30,
"billing_notices": []
}
steps is what the pipeline inferred from your inputs, poll_url is where 3.3 goes
next, and billing_notices is empty because every requested step was dispatched (it fills in
when a step is dropped for lack of entitlement — see Poll & webhooks).
3.2 Audio, a PDF and notes in one request
POST /v1/process/upload takes raw files — no base64. Repeat the files field
per file (at most one audio file per request) and put any free-text notes in
text. Everything is fused into one consultation: the audio is transcribed, the PDF's text is
extracted, and the note is appended.
curl -X POST https://api.documenter.ch/v1/process/upload \ -H "Authorization: Bearer doc_partner_YOUR_KEY" \ -H "X-User-Token: DOC-A7K2M3P9" \ -F "mode=document" \ -F "files=@consultation.mp3" \ -F "files=@protocole_operatoire.pdf" \ -F "text=Controle a six semaines de la cholecystectomie. Cicatrices calmes, pas de douleur parietale. La patiente signale des brulures epigastriques le soir. Poursuite du pantoprazole 40 mg 1x/jour le matin pendant un mois. Reprise du travail autorisee." \ -F "output_format=json" \ -F "locale=fr"
202 Accepted
{
"job_id": "doc_job_8J0v_HyWxUR7l91c_lmXtg",
"status": "processing",
"mode": "document",
"steps": ["transcription", "generation"],
"poll_url": "/v1/process/doc_job_8J0v_HyWxUR7l91c_lmXtg",
"estimated_seconds": 75,
"billing_notices": []
}
Same envelope as 3.1 — only steps and estimated_seconds changed, because the
audio added a transcription step ahead of generation. The response shape does not
depend on which endpoint you submitted to.
3.3 Poll until the job is done
GET /v1/process/{job_id} with the same auth headers you submitted with. Stop
when status is completed, error, or cancelled — a
cancelled job never becomes completed, so a loop that waits only for completed spins forever.
Poll no faster than every 2 seconds per job; a tighter loop returns
429 DOC_RATE_001 with a Retry-After header. Results are available for one hour,
then the job returns 410.
curl https://api.documenter.ch/v1/process/doc_job_bzZu1Nls1CqRFZPn_wXw_g \ -H "Authorization: Bearer doc_partner_YOUR_KEY" \ -H "X-User-Token: DOC-A7K2M3P9"
While it runs
{
"job_id": "doc_job_bzZu1Nls1CqRFZPn_wXw_g",
"status": "processing",
"mode": "document",
"steps": ["generation"],
"current_step": "generation",
"estimated_seconds_remaining": null,
"results": null,
"error": null,
"billing_notices": [],
"created_at": "2026-08-29T22:39:56.341223Z",
"completed_at": null
}
When it is done (3.1's job)
results.generation.content is always a string. With
output_format: "json" that string is JSON — parse it to get the sections object.
{
"job_id": "doc_job_bzZu1Nls1CqRFZPn_wXw_g",
"status": "completed",
"mode": "document",
"steps": ["generation"],
"current_step": null,
"estimated_seconds_remaining": null,
"results": {
"generation": {
"content": "{\n \"schema_version\": 1,\n \"output_mode\": \"structured\",\n \"sections\": […",
"format": "json",
"tokens_in": 6553,
"tokens_out": 864
}
},
"error": null,
"billing_notices": [],
"created_at": "2026-08-29T22:39:56.341223Z",
"completed_at": "2026-08-29T22:40:03.128407Z"
}
Parsed generation.content
{
"schema_version": 1,
"output_mode": "structured",
"sections": [
{
"key": "titre",
"title": "Note de suite",
"parent": null,
"content": ""
},
{
"key": "motif_consultation",
"title": "Motif de consultation",
"parent": null,
"content": "Contrôle trimestriel, gonalgie droite"
},
{
"key": "anamnese",
"title": "Anamnèse",
"parent": null,
"content": "1. **Hypertension artérielle et diabète de type 2**\nBonne observance du traitement. Aucun épisode hypoglycémique rapporté.…"
},
{
"key": "examen_clinique",
"title": "Examen clinique",
"parent": null,
"content": "Constantes : TA 138/84 mmHg, pouls 72/min régulier, poids 88 kg stable\n__Cardio-vasculaire__ : auscultation sans particularité…"
},
{
"key": "appreciation",
"title": "Attitude et suivi",
"parent": null,
"content": "1. **Hypertension artérielle et diabète de type 2**\nLe contrôle trimestriel est satisfaisant avec une bonne observance et des paramètres stables.…"
},
{
"key": "traitements",
"title": "Traitement prescrit",
"parent": null,
"content": "Paracétamol en réserve"
}
],
"extracted_at": "2026-08-29T22:40:03.128247+00:00"
}
The transcription block (3.2's job)
A job that ran transcription returns it alongside generation, under its own key.
generation is the same shape as above — that run returned the same six sections, written
from the audio, the PDF and the note together.
"results": { "transcription": { "text": "[Medecin] Bonjour, madame de Lafleur…", "speakers": [ {"id": 1, "label": "Medecin"}, {"id": 2, "label": "Patient"} ], "medications": [ {"name": "Pantoprazol", "dosage": null, "frequency": null}, {"name": "Irfen", "dosage": null, "frequency": null}, {"name": "Freka-Clyss", "dosage": null, "frequency": null} ], "audio_events": [], "duration_seconds": null, "language": null }, "generation": { /* as in 3.1 */ } }
medications lists Swissmedic-matched names, and a dictated drug with no reliable match under its spoken name;
dosage and frequency are declared but not surfaced today, so read them as always
null. language is reported only when language identification ran, and
audio_events is often empty — treat both as possibly absent rather than as fields you
can key on. audio_events and medications are always ARRAYS, empty or not.
What next
- Map the keys to your own fields. Fetch the full catalogue from
GET /v1/section-keys, or have DOCumenter return your EHR's field names directly — configured in the developer console's Mapping tab (Structured JSON output). - Stop polling. Pass
webhook_urlat submit time and we POST the finished job to you, signed withX-Webhook-Signature(Poll & webhooks). - Choose another instruction.
GET /v1/promptslists the instructions available to the physician, the sections each produces (with your field map applied) and which one is the default; pass itsidasprompt_id, andlength(concis/equilibre/exhaustif) when it has a length family (Instruction library & section keys). - Handle the five errors that matter.
401(bad key),403(plan does not include the step),429and503(honorRetry-After),410(results expired) — every code with its client action is in the error catalogue.
4. Send a request
4.1 Endpoints
This page teaches the integration flow and operational decisions. The OpenAPI document is the authoritative EHR integration contract for request and response schemas; Swagger UI renders that contract as a human-friendly, interactive explorer. The error catalog below adds the client action for each
DOC_* code. If you find a mismatch,
treat the OpenAPI schema as authoritative and report it with the page's support details.
OpenAPI spec
Import into Postman/Insomnia, generate a typed SDK with openapi-generator, or validate requests in CI.
Download /v1/openapi.jsonMarkdown guide
A portable narrative API guide for AI coding assistants, including the integration flow, API scope, and credential-safety rules.
Download for an AI assistantA map for orientation. For full request/response detail, follow the linked narrative section or the Swagger UI above.
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/section-keys |
The canonical section-key catalogue your field mapping targets. See Section keys. |
| POST | /v1/process |
Submit a job with a JSON body (all modes; chat is JSON-only). See Modes. |
| POST | /v1/process/upload |
Submit a job with raw file uploads (multipart) — document, transcript, dictation, rename, or form. Same response envelope. |
| GET | /v1/process/{job_id} |
Poll for status and results. 410 after the 1-hour result TTL. |
| DELETE | /v1/process/{job_id} |
Cancel an in-progress job. A cancelled job polls as {status:"cancelled", error:null}. |
| GET | /v1/prompts |
List the prompt templates visible to your key. See Prompt Library. |
| GET | /v1/entitlements |
Read the physician's plan tier + capabilities before submitting. See Poll & webhooks. |
| POST | /v1/partner/signup-intents |
Prepare a doctor signup and get its link (API key only, no X-User-Token; organisation must be enabled). See Onboard a doctor. |
| GET | /v1/partner/signup-intents/{intent_id} |
Signup intent status, with the pairing code during the hour after completion. See Onboard a doctor. |
| GET | /v1/health |
Liveness check, no auth. Returns {"status":"ok"}. |
Uploads (/v1/process/upload): multipart files (repeatable; at most one
audio file per request), plus mode, text, transcript,
transcript_token, prompt_id, length,
tardoc, output_format, locale, webhook_url, and
form (the blank form to fill, required with mode=form and ignored otherwise).
Accepted file
formats and size caps are in Limits & Edge Cases; full field types are in the
Swagger UI.
4.2 Request shape
POST /v1/process/upload (multipart) accepts any combination of audio, PDFs, DOCX, images,
and free text — even text-only with no files. At most one audio file per request;
combine that one audio with any number of documents, images, and text (more than one audio returns
400 DOC_VAL_001). Use it for document, transcript, dictation, rename and form modes (form mode adds
one more part, form, for the blank form itself).
Chat mode uses
POST /v1/process (JSON) instead — the messages array
doesn't map cleanly to multipart form-data.
Request fields (JSON body, POST /v1/process)
| Field | Type | Required | Description |
|---|---|---|---|
mode |
"document" | "transcript" | "dictation" | "form" | "chat" | "rename" |
Yes | Processing mode: "document", "transcript", "dictation" (see Dictation mode), "form", "chat", or "rename". Required for JSON POST /v1/process — the request body is a discriminated union selected by this field, so omitting it returns 422. Only the multipart POST /v1/process/upload defaults to "document". "form" takes its own form field / file part — see Form mode. |
content |
string | null | Conditional | Clinical text, or base64-encoded audio when content_type: "audio". For raw file uploads use /v1/process/upload. At least one of content / documents / (uploaded) audio is required for the inferred steps. |
content_type |
"text" | "audio" | null |
No | How to treat content. "text" (default) → report generation; "audio" → the base64 content is transcribed. |
documents |
array<DocumentAttachment> | null | No | Base64-encoded attachments (text extracted automatically). See the DocumentAttachment table below. |
prompt_id |
string (UUID) | null | No | Prompt template for generation. Omit to use the platform default (Note de suite - Cabinet, equilibre); for production stability pass an explicit id from GET /v1/prompts. |
length |
"concis" | "equilibre" | "exhaustif" | null |
No | Length variant. Valid only when the chosen prompt has a length family (non-empty lengths on GET /v1/prompts); otherwise returns 400 DOC_VAL_008. The platform default prompt has one. Omit to use the family's default_length. |
output_format |
"text" | "markdown" | "html" | "json" | "docx" |
No (default "html") |
Output format for the generated report. "json" returns the structured-section schema as a JSON-encoded string in content; "docx" returns base64-encoded Word bytes in content (see Word (.docx) output). |
tardoc |
boolean | No (default false) |
When true, append TARDOC billing-code extraction. Accepted in document and transcript mode. Requires an audio source (transcription step), else 400 DOC_VAL_006. Requires an ia-ssistant-pro subscription: without it the step is silently dropped (the rest of the pipeline still runs) and a billing_notices[] entry (DOC_BILL_002) is added — not a hard error. |
locale |
"fr" | "de" | "it" | "en" |
No (default "fr") |
Report language and TARDOC code descriptions. |
webhook_url |
string (https URL) | null | No | HTTPS callback for result delivery. Must resolve to a public IP (SSRF-guarded). A non-https:// URL is rejected as 422 DOC_VAL_001. |
DocumentAttachment (items of documents)
| Field | Type | Required | Description |
|---|---|---|---|
type |
"pdf" | "text" | "image" |
Yes | Attachment kind. pdf → text layer + OCR fallback; image → OCR; text → decoded UTF-8. |
name |
string | Yes | Original filename (used as the document label). |
data |
string (base64) | Yes | Base64-encoded file content. |
chat, rename and form modes share locale and
webhook_url; see their tabs below for mode-specific fields (form requires
its own form field and rejects the note-shaping ones). Multipart form fields for
POST /v1/process/upload are listed in the Endpoints section.
Use a prompt_id from GET /v1/prompts.
For prompts with a length family, pass length too.
See Prompt Library for scoping (defaults + your org + the physician's personal library)
and the length-variant guide.
Idempotency — sending the same request twice
Add an Idempotency-Key header (a UUID is ideal). The key is scoped to the
API key + physician. Repeating the same logical request replays the original job and
adds Idempotent-Replayed: true to the 202 response. JSON object-key order,
whitespace, and omitted versus explicit defaults do not matter; multipart boundary/header serialization
does not matter. JSON array order, file order, filenames, media types, file bytes, and field values do matter.
A meaningful change returns 409 DOC_VAL_016; use a new key for a new logical
job. Works on both submission endpoints and has no TTL.
4.3 Modes
Every request has a mode. The quickstart used "document", which
always generates a note: audio-only transcribes then generates from that
transcript, text/documents produce a report, and audio + documents transcribes then generates from
both. For transcription only (no note), send "mode": "transcript". Add
"tardoc": true together with audio to extract Swiss billing codes — it works in
both document and transcript mode (requires an
ia-ssistant-pro subscription — see below). To fill an official form instead of
writing a note, send "mode": "form" with the blank form. Here are all five.
Document mode always generates a note and adapts to what you send: audio alone
transcribes then generates from that transcript; text produces a report; audio + documents
transcribes first then generates with both as context. No need to specify steps. Want the transcript
only, with no note? Use "transcript" mode.
| You send | Steps run | Duration |
|---|---|---|
| Text / PDFs only | Generation | ~30-120s |
| Audio only | Transcription → Generation (note from the transcript). Use "mode": "transcript" for transcription only. |
~45-150s |
| Audio + text/PDFs | Transcription → Generation (with context) | ~55-190s |
403 DOC_BILL_001 and nothing runs (a partial note that silently omitted the documents
would be clinically misleading). Call GET /v1/entitlements to
check a physician's plan up front.
transcript_token. Send the transcript as content together with
transcript_token to generate another document from it: it still counts as a transcript, so
Scribe physicians can use it too. On /v1/process/upload, send it in the transcript
field with transcript_token; it stays the consultation next to a text note and
files. Store the token next to the transcript; it does not expire. Line endings, surrounding whitespace and
Unicode normalization do not matter; an edited transcript, or a token issued to another physician, is
treated as a free-text note.
TARDOC billing codes (ia-ssistant-pro): Set "tardoc": true together with
audio to also extract Swiss TARDOC billing codes (tax points, quantities). Adds ~10s. Default is
false. Codes use the chapter-prefixed format AA.00.0010 (consultation),
AA.00.0110 (neuro exam), etc. TARDOC requires an ia-ssistant-pro
subscription. Unlike documents, an under-entitled request is not rejected: the tardoc
step is dropped, the transcript + note are still returned, and a
billing_notices[] entry (DOC_BILL_002) explains the
drop. You are billed only for the steps that ran.
// Excerpt of results.tardoc on a real consultation: "tardoc": { "codes": [ {"code": "AA.00.0010", "description": "Consultation de base", "tp": 9.57, "quantity": 1}, {"code": "AA.00.0020", "description": "Consultation, +5 min", "tp": 9.57, "quantity": 3}, {"code": "AA.00.0110", "description": "Examen neurologique", "tp": 15.45, "quantity": 1} ], "total_tp": 53.73, "currency": "CHF" }
Transcription only. Submit audio, get back a speaker-labeled transcript with
medications — a note is never generated. This is the no-note counterpart to the
note-generating document mode. Available on every plan (Scribe included).
Add "tardoc": true to also extract billing codes from the transcript (still no note).
| Field | Required | Description |
|---|---|---|
mode |
Yes | "transcript" |
content |
Either | Base64-encoded audio. Or upload a raw audio file via POST /v1/process/upload with mode=transcript. |
content_type |
No | Always "audio" (the default). Transcript mode is audio-only. |
tardoc |
No | Default false. When true, TARDOC billing codes are extracted from the transcript — still with no note. Same ia-ssistant-pro gate as in document mode (dropped with a DOC_BILL_002 notice when unentitled). |
Audio-only by construction: documents, prompt_id,
length and output_format are meaningless here and rejected with
422 DOC_VAL_001 — on the multipart upload endpoint too, so both surfaces
agree. Shares locale and webhook_url with the other modes.
Duration: ~15-60s.
{
"mode": "transcript",
"content": "<base64 audio>",
"content_type": "audio"
}
Dictation mode
One speaker dictating, plain text out. Send "mode": "dictation" (or
mode=dictation on POST /v1/process/upload) with the audio, exactly as in
transcript mode. Use it when a physician dictates a letter or a report rather than recording a
consultation. Available on every plan.
results.transcription keeps the transcript shape: text is the dictated text
with no speaker tags, speakers and audio_events are always
[], language is null, and medications and
duration_seconds are filled as in transcript mode. A dictation carries no
transcript_token: it is not a consultation transcript. The poll, the webhook and an
idempotent replay report "mode": "dictation".
Spoken punctuation (French). The physician can dictate the punctuation:
virgule, point, deux points, point-virgule,
point d'interrogation, à la ligne, nouveau paragraphe, tiret,
ouvrez/fermez la parenthèse. They arrive in text as symbols, line breaks
(\n) and blank lines (\n\n); keep line breaks when you display or store
the text. When the context is ambiguous the command word is left as dictated rather than risk
removing a clinical word ("trois points de suture", "point d'appel", "ligne médiane" stay words),
so the physician may occasionally see a stray point to correct. A decimal dictated with
digits joins (11 virgule 4 becomes 11,4). French dictations only.
Audio-only with no add-on: documents, prompt_id, length,
output_format, tardoc, transcript,
transcript_token, free text and non-audio files are rejected with
422 DOC_VAL_001 on both endpoints.
{
"mode": "dictation",
"content": "<base64 audio>",
"content_type": "audio"
}
Fill an official form from the consultation. Send the blank form and the sources it
should be answered from; you get the same form back, filled, plus every field's value
as data. The output follows the input: a PDF AcroForm comes back as a filled PDF
(still an editable AcroForm, so the physician can correct any value in a normal PDF viewer), a
Word form with native controls comes back as a filled .docx. No note is
generated. Requires an ia-ssistant subscription
(GET /v1/entitlements →
capabilities.form_fill); below that, the submit is rejected with
403 DOC_BILL_001 and nothing runs.
| Field | Type | Required | Description |
|---|---|---|---|
mode |
"form" |
Yes | Selects form mode. Available on both POST /v1/process (JSON) and POST /v1/process/upload (multipart). |
form |
object {filename, content_base64} |
Yes |
The blank form. On the multipart endpoint it is its own form file part instead
(exactly one; a second form part is 400 DOC_VAL_001), kept separate from
files so a source document can never be mistaken for the form. The type is admitted
from the file's own bytes, never from filename or the part's
content type: a PDF AcroForm (max 8 MB) or a Word form with native controls,
.docx/.dotx (max 2 MB). Anything else — a text
file, an image — is rejected at submit with 400 DOC_VAL_001. Fillable fields
are not checked at submit: a PDF with none (a scan, a flattened form) is accepted with
202 and the job ends with DOC_FORM_006.
|
content |
string | null | Conditional | A source: clinical text, or base64-encoded audio with content_type: "audio". At least one source is required — content, documents, or an uploaded file. |
content_type |
"text" | "audio" | null |
No | How to treat content. With "audio" the recording is transcribed first and the transcript becomes a source, so results.transcription is returned alongside results.form. |
documents |
array<DocumentAttachment> | null | No | Base64-encoded source attachments (same shape as in document mode; text is extracted automatically). On the multipart endpoint these are the files parts, plus the text field. |
locale |
"fr" | "de" | "it" | "en" |
No (default "fr") |
Language of the answering. |
webhook_url |
string (https URL) | null | No | HTTPS callback for the result — same delivery, signing, and SSRF guard as the other modes. |
There is no note to shape here, so prompt_id, length,
output_format and tardoc are rejected with
422 DOC_VAL_001 — on the multipart endpoint too, so both surfaces agree.
Submitting
Multipart is the natural shape: the form and the sources are files. The JSON endpoint takes the same request with the form base64-encoded.
# multipart — the form in its own part, the sources in files/text
curl -X POST https://api.documenter.ch/v1/process/upload \
-H "Authorization: Bearer doc_live_YOUR_KEY" \
-H "X-User-Token: DOC-XXXXXXXX" \
-F "mode=form" \
-F "form=@rapport_medical_laa.pdf" \
-F "files=@Consultation.ogg" \
-F "text=Accident du 20.09.2026, chute d'une echelle."
// JSON — same request, form base64-encoded { "mode": "form", "form": { "filename": "rapport_medical_laa.pdf", "content_base64": "JVBERi0xLjcK..." }, "content": "Accident du 20.09.2026, chute d'une echelle. Fracture du poignet droit...", "locale": "fr" }
Steps & states
steps is ["form"], or ["transcription", "form"] when you send
audio. The job walks the same state machine as every other mode —
202 {"status": "processing"}, then GET /v1/process/{job_id} until
completed / error / cancelled, or a webhook_url.
DELETE /v1/process/{job_id} cancels it. Answering runs page by page, so the time scales
with the form: a 59-field, 3-page form measured about 11 s (plus the
transcription time when you send audio). The 202's estimated_seconds is a
conservative 120 — poll or use a webhook rather than budgeting on a fixed number.
results.form
{
"status": "completed",
"mode": "form",
"steps": ["form"],
"results": {
"form": {
"document": {
"content_base64": "JVBERi0xLjcKJc...",
"format": "pdf",
"media_type": "application/pdf",
"sha256": "1bc089c1b4dc..."
},
"fields": [
{
"key": "p001:q001:f001",
"question": "Numero de sinistre",
"label": "Numéro de sinistre:",
"section": "Rapport médical LAA",
"page": 1,
"type": "text",
"options": null,
"value": "24.128.456"
},
{
"key": "p002:q004:f001",
"question": "Incapacite de travail",
"label": "Incapacité de travail",
"section": "Incapacité",
"page": 2,
"type": "choice",
"options": ["oui", "non"],
"value": "oui"
}
],
"summary": {
"field_count": 59,
"answered_count": 26,
"failed_page_count": 0,
"unplaced_field_count": 0,
"continuation_page_count": 1
}
}
}
}
| document — the filled form | ||
|---|---|---|
content_base64 |
string | Base64-encoded file bytes — decode before writing them to a file. |
format |
"pdf" | "docx" |
Follows the form you submitted. Never a conversion: a PDF form returns a PDF, a Word form returns a Word document. |
media_type |
string | application/pdf, or the Word package media type. Use it verbatim when you store or serve the file. |
sha256 |
string | SHA-256 hex digest of the decoded bytes — verify your decode against it. |
| fields[] — every field of the form, in form order | ||
key |
string | Stable field key, deterministic for a given form file: the same blank form always yields the same keys, so a mapping you build once keeps working. It is not stable across two different versions of a form. |
question |
string? | The question the model restated for this field, when it did. May be null — and is always null in sandbox. |
label |
string? | The form's own label for the field, as printed on it. May be null when the control carries none. |
section |
string? | The form section the field belongs to. May be null. |
page |
int | 1-based page of the submitted form. |
type |
string | Field type: text, date, number, checkbox, choice, signature, … Treat it as an open set and fall back to text rendering. |
options |
array<string>? | The accepted values of a choice field; null for every other type. A non-empty value of a choice field is always one of them. |
value |
string | The value written into the field — always a string, "" when the field was left blank (not answered, or the physician's to fill: signatures, attachments, the treating doctor's identity). |
| summary — what the fill achieved | ||
field_count |
int | Fields the form declares — always fields.length. |
answered_count |
int | Fields that received a non-empty value. A low count on a long form usually means the sources did not cover it, not that the fill failed. |
failed_page_count |
int | Pages whose answering failed; their fields come back blank. Not an error — the job still completes and the rest of the form is filled. |
unplaced_field_count |
int | Fields whose value did not fit its control and was moved to an appended annex page. |
continuation_page_count |
int | Pages appended to the returned document to carry overflow text. Expect the returned file to have more pages than the blank form when this is non-zero. |
Limits
- The form: 8 MB for a PDF, 2 MB for a Word form. Over either →
413 DOC_VAL_004. - The sources: at most 16 of them, and 512 KiB of extracted text in total — counted after extraction, and including the transcript when you send audio, so a very long recording can push a request over the limit mid-job and terminate it with
DOC_VAL_004. - Per key: unchanged — the usual 30 requests/minute and 10 concurrent jobs (see Limits & data handling).
- Result TTL: unchanged — 1 hour, like every other job.
Errors
| Code | When |
|---|---|
DOC_FORM_006200, terminal job error |
The uploaded form cannot be filled: no native fillable fields, a scan, a flattened form, a Word file whose controls are not native, refused active content, or bytes we cannot read. Also when the filled document would exceed 9 MB — the ceiling on what a single result may carry. Arrives as error.error inside a 200 poll body with "status": "error", with no error.reason. Do not retry the same file — re-export the form from its source with its fields intact, or send a different one. |
DOC_VAL_001 400 / 422 |
The form part is not a PDF or a Word form (admitted from its bytes), its content_base64 is not valid base64, more than one form part was sent, or the request carries a note-only field (prompt_id, length, output_format, tardoc). |
DOC_VAL_002 400 |
No form part with mode=form. Also when no readable text could be extracted from any source — and, as a terminal job error, when the audio produced no transcript and nothing else was supplied. |
DOC_VAL_004 413 |
The form exceeds its size limit, or the sources exceed 16 files / 512 KiB of extracted text (as a terminal job error when the transcript is what pushed them over). |
DOC_BILL_001 403 |
The physician's plan does not include form filling (ia-ssistant+). Nothing runs. Read capabilities.form_fill from GET /v1/entitlements to gray the option out up front. |
DOC_SVC_001 200, terminal |
The fill did not finish (it exceeded its processing deadline, or the answering failed). Resubmit under a new Idempotency-Key. |
DOC_SVC_001 503 at submit |
Form filling runs on the instance that accepts your request, and that instance is already holding
as many form jobs as it will take. Nothing was queued and no job id was minted. Honor
Retry-After and resubmit — you may reuse the same
Idempotency-Key. |
A page whose answering failed is not an error: its fields come back blank and are
counted in summary.failed_page_count, and the job completes normally.
In sandbox
A doc_test_ key runs the real lane: your form is really parsed, and the
document you get back is really rendered — the same bytes-level path a live key takes. Only the
answers are synthetic: no model is called, every text field is filled with
"Exemple", a choice field takes its first option, and question is
null. So fields[], the keys, the types, the options and the returned file are
all exactly what you will parse in production. Unlike the other modes, a form job is
not complete on your first poll: it goes 202 processing →
completed within a few seconds, so poll (or use a webhook) as you would live. With audio,
the transcription step returns the usual sandbox mock transcript.
Medical AI assistant for clinical questions. Multi-turn conversation. Currently async (poll for response). Streaming via SSE is on the roadmap.
| Field | Type | Required | Description |
|---|---|---|---|
mode |
"chat" |
Yes | Selects chat mode. Chat is JSON-only — POST /v1/process, not the multipart upload endpoint. |
messages |
array<{role, content}> | Yes |
Non-empty conversation history. Only roles
user and assistant are accepted (each with a string content). We
apply our own medical system instruction — passing role: "system" returns
422.
|
locale |
"fr" | "de" | "it" | "en" |
No (default "fr") |
Reply language. |
webhook_url |
string (https URL) | null | No | HTTPS callback for the reply — same delivery, signing, and SSRF guard as the other modes. |
{
"mode": "chat",
"messages": [
{"role": "user", "content": "Diagnostics differentiels pour cephalees frontales?"},
{"role": "assistant", "content": "Céphalées de tension, migraine, sinusite, HTIC..."},
{"role": "user", "content": "Patiente 45 ans, depuis 2 semaines, aggravées par le stress. Lequel?"}
]
}
Duration: ~5-30s. Streaming via SSE is on the roadmap; meanwhile poll
GET /v1/process/{job_id} or set a webhook_url.
AI-powered document renaming. Extracts patient name, date, document type, and suggests a structured filename.
| Field | Type | Required | Description |
|---|---|---|---|
mode |
"rename" |
Yes | Selects rename mode. |
content |
string | null | Either | Document text to analyze. |
documents |
array<DocumentAttachment> | null | Either | Base64-encoded document attachments (alternative to content); same shape as the Document-mode DocumentAttachment table above. Or upload raw files via /v1/process/upload. |
locale |
"fr" | "de" | "it" | "en" |
No (default "fr") |
Language hint for the extraction. |
webhook_url |
string (https URL) | null | No | HTTPS callback for the result. |
Provide at least one of content or documents (via
/v1/process/upload, an uploaded file's extracted text becomes content). An
empty / whitespace-only request returns 400 DOC_VAL_002. Duration: ~10-30s
Filename layout. There are no format parameters on the request. The
naming convention lives on your API key: set it in the developer console (Keys → naming
convention) as either imposed (it beats the doctor's own preference) or default (the
doctor's preference wins and the key is the fallback). Allowed fields are surname,
firstname, birthdate, docdate, doctype,
type_detail, doctor, source, recipient. Listing
type_detail splits the document type in two: doctype then renders the bare
catalogue label (“Imagerie”) and type_detail the precision on its own
(“CT de la hanche”). Both are in the platform default layout
NOM (DDN) - DATE Type Détail; leave type_detail out of your own order and
doctype falls back to the merged form. Every response reports which
convention was actually applied in results.renaming.format. The composed
filename is capped at 120 characters before the extension; over the cap whole words are
given back from the free-text fields (type_detail, then doctype,
then source, then recipient), so a name is never cut mid-word and
the identity fields are never shortened.
| Convention on the key | Mode | Doctor has a preference | Applied | format.source |
|---|---|---|---|---|
| set | override | either | the key's | "key" |
| set | default | yes | the doctor's | "user" |
| set | default | no | the key's | "key" |
| none | — | yes | the doctor's | "user" |
| none | — | no | the platform default | "default" |
4.4 Prompts & section keys
GET /v1/prompts and the prompt_id field on POST /v1/process resolve to
the union of three tiers, scoped to the API key and (optionally) the physician identified by
X-User-Token:
| Tier | What it contains | How to populate |
|---|---|---|
| System defaults | Templates curated by DOCumenter for common Swiss clinical use cases. | Always visible. Nothing to configure. |
| Institution library | Templates your organization shares with every integrated physician. | Sign in to documenter.ch as the org account, create or import the prompts you want shared. |
| Physician's personal library | The doctor's own templates, writing preferences, and tweaks — whatever they configure on documenter.ch. | Each physician on the EHR is mapped to their DOCumenter account on demand (via pairing code, verified email, or similar). Once mapped, anything they edit on documenter.ch is reflected in the API responses for that physician's requests automatically. |
Quick-evaluation sandbox keys see system defaults. Partner-parity sandbox keys expose the three curated prompt fixtures described under Sandbox vs production; their UUIDs are sandbox-only.
A prompt_id outside these three tiers (e.g. another tenant's private prompt, or a UUID that doesn't
exist) returns 404 DOC_VAL_007 on POST /v1/process. We return 404 rather than 403 to
avoid leaking the existence of other tenants' prompts.
Note: The web app's "public" share-link prompts are not surfaced through the developer API. If you need a community prompt for an integration, fork it into your org's library — that surfaces it via the institution tier.
Section keys (the mapping contract)
GET /v1/section-keys returns the canonical keys that appear in
sections[].key when you request output_format: "json" — the list your field
mapping is built against. Each entry has a key, a human label, and
deprecated.
Keys are append-only. A published key is never renamed or removed. Retirement is
deprecated: true: the key stays in this list and is still assigned to reports, so an existing
mapping keeps working — but you should not point new fields at it.
Poll catalogue_version to notice that the vocabulary or the heading-matching rules moved. It is a
change signal only — a request cannot pin a version, and results do not carry one. Aliases (the heading
phrases that resolve to each key) are intentionally not published; they are internal matching detail.
curl -s https://api.documenter.ch/v1/section-keys \ -H "Authorization: Bearer doc_live_YOUR_KEY" \ -H "X-User-Token: YOUR_JWT"
{
"catalogue_version": 1,
"keys": [
{"key": "anamnese", "label": "Anamnèse", "deprecated": false},
{"key": "titre", "label": "Titre du document", "deprecated": false},
{"key": "unmapped", "label": "Salutations", "deprecated": false},
{"key": "autre", "label": "Autre section", "deprecated": false}
]
}
Prompt listing, defaults, and length variants
Listing prompts
GET /v1/prompts returns the templates visible to your key. Each item has a stable
id (UUID), a title, a visibility, an optional
description (string | null), an is_default flag, an
is_favorite flag (the physician starred it on documenter.ch; list those first), a
sections preview, and — for templates that come in length variants
— a lengths array plus a default_length. Singletons return
null for the last two.
sections is what this instruction produces, in the order it declares it, with
your organisation's field map already applied: canonical_key is
DOCumenter's own key, and key is what you will actually receive in
results.generation.sections[].key. Two entries may carry the same key —
that is a many-to-one mapping, and their contents arrive appended under it in report order; they are
listed separately so you can see which sections merge. The document title is always the first entry.
sections is null when the instruction does not declare its structure up front
(free-text instructions, instructions whose structure the model derives at generation time, and every
sandbox instruction).
The map reflected here is your organisation's current one. A job that has already completed keeps the map that was in force at its completion, so editing the map never re-keys a finished job — see Section keys.
curl -s https://api.documenter.ch/v1/prompts \ -H "Authorization: Bearer doc_live_YOUR_KEY" \ -H "X-User-Token: YOUR_JWT"
[
{
"id": "a8badc28-...", // singleton — no length family
"title": "Laboratoire",
"description": null,
"visibility": "default",
"lengths": null,
"default_length": null,
"is_default": false,
"is_favorite": false,
"sections": null // structure not declared up front
},
{
"id": "1d8ba499-...", // id = the equilibre variant of the family
"title": "Note de suite - Cabinet",
"description": "Note de suite pour le dossier médical au cabinet",
"visibility": "default",
"lengths": ["concis", "equilibre", "exhaustif"],
"default_length": "equilibre",
"is_default": true, // used when you omit prompt_id
"is_favorite": true, // starred by this physician
"sections": [
{"canonical_key": "titre", "title": "Titre du document", "key": "titre", "presence": "required"},
{"canonical_key": "motif_consultation", "title": "Motif de consultation", "key": "motif_consultation", "presence": "required"},
{"canonical_key": "anamnese", "title": "Anamnèse", "key": "ehr_history", "presence": "required"},
{"canonical_key": "examen_clinique", "title": "Examen clinique", "key": "ehr_history", "presence": "required"},
{"canonical_key": "appreciation", "title": "Attitude et suivi", "key": "appreciation", "presence": "required"},
{"canonical_key": "traitements", "title": "Traitement prescrit", "key": "traitements", "presence": "required"}
]
}
]
This organisation maps anamnese and examen_clinique onto the same
ehr_history field, so both are listed and both arrive under
ehr_history; the unmapped keys pass through as themselves.
Default prompt
prompt_id is optional. Omitting it gives you Note de suite - Cabinet at
equilibre length — the everyday follow-up note, and the quickest way to get a
result on a first integration before you wire up template selection. For production stability, use an
explicit prompt_id from GET /v1/prompts. Add
output_format: "json" for the structured, per-section response. The default is a length
family, so length works without a prompt_id too.
curl -s -X POST https://api.documenter.ch/v1/process \ -H "Authorization: Bearer doc_live_YOUR_KEY" \ -H "X-User-Token: YOUR_JWT" \ -H "Content-Type: application/json" \ -d '{ "mode": "document", "content": "Patient présente fièvre 38.5 et toux sèche.", "output_format": "json" }'
For production, select an explicit prompt_id from GET /v1/prompts so your
output stays stable as platform defaults evolve.
Length variants
Some prompts come in three lengths. Items with a non-null lengths array are part of a length family;
pass the length parameter on POST /v1/process to pick the variant. Omit length
to get the variant identified by default_length (always equilibre when available).
concis— stripped to key facts. ~40-50% fewer tokens thanequilibre. Use when the EHR slot is small or the doctor wants to skim.equilibre— balanced detail. The recommended starting point and what most doctors pick. If you skiplength, this is what you get.exhaustif— maximum detail. ~30-40% more tokens thanequilibre. Use for legal-quality reports (LAA, AI, expertises) where omitted context can hurt.
All three share the same prompt family — same model, only the requested verbosity differs. If you build a length
toggle in your EHR UI, pre-select equilibre. Passing length on a prompt without a family
returns 400 DOC_VAL_008; the default prompt has one, so omitting prompt_id does not.
5. Get the results
5.1 Poll & webhooks
Two options. Use whichever fits your architecture.
Call GET /v1/process/{job_id} every 5 seconds with the same auth headers you
used to submit. The job is tied to your API key and the physician who submitted it — another key, or another physician under the same key, gets 404. Results expire after 1 hour.
# Poll with the same auth headers (job is tied to your API key) while status == "processing": sleep(5) result = GET /v1/process/{job_id} -H "Authorization: Bearer YOUR_API_KEY" -H "X-User-Token: YOUR_TOKEN" # status: "completed" | "error" | "cancelled"
Recommended strategy: Poll every 5 seconds for the first 30 seconds, then every 10 seconds.
Polls do not count against rate_limit_rpm, but polling one job much more often than every
2 seconds returns 429 DOC_RATE_001 — treat 2 seconds as a floor, not a quota. Once the per-minute
window is already full, polls are refused too until it frees a slot (Rate limits). For high-volume integrations, use webhooks instead. While
processing, the response contains no partial data:
{
"job_id": "doc_job_...",
"status": "processing",
"mode": "document",
"steps": ["generation"],
"current_step": "generation",
"results": null,
"error": null
}
Progress tracking. While status is processing, the poll response
includes the step currently executing:
current_step |
string? | Name of the step currently executing (e.g. "transcription", "generation"). Present only while processing. |
202 Accepted (submit response). Every POST /v1/process (and /v1/process/upload) returns 202 Accepted immediately with:
{
"job_id": "doc_job_kVG4OV0K...",
"status": "processing",
"mode": "document",
"steps": ["transcription", "generation"],
"poll_url": "/v1/process/doc_job_kVG4OV0K...",
"estimated_seconds": 75,
"billing_notices": []
}
The submit status is "processing" for every new job, live or sandbox. (A
sandbox job becomes completed on your first poll; an Idempotency-Key replay
returns the original job's current status.) estimated_seconds is the sum of per-step
estimates — roughly 45s transcription, 30s generation, 10s TARDOC — so it varies with the
inferred steps; a sandbox submit returns 1.
Partial fulfillment — billing_notices[]. When a request asks for a step
the physician's plan does not include but the rest of the pipeline can still run, that step is
dropped (never dispatched, never billed) and a notice is returned in
billing_notices[] — present on the 202 submit, every
poll, and the webhook payload (identical in all three). It is
empty when every requested step ran. Today the only case is TARDOC on a non-pro plan:
{
"job_id": "doc_job_...",
"status": "processing",
"steps": ["transcription", "generation"], // tardoc dropped
"billing_notices": [
{
"code": "DOC_BILL_002",
"step": "tardoc",
"message": "TARDOC billing extraction requires an ia-ssistant-pro subscription; the step was skipped.",
"required_tier": "ia-ssistant-pro"
}
]
}
billing_notices[] is the authoritative runtime signal. To check a physician's plan
before submitting, read GET /v1/entitlements.
Set webhook_url in your request and we POST the full result to your server when done. Must be
HTTPS. We make up to 3 delivery attempts, roughly 30 s apart. After 3 failed attempts
the result is not lost — it remains pollable via
GET /v1/process/{job_id} for 1 hour. Any 2xx acknowledges delivery; redirects are
not followed and the request timeout is 30 seconds. Verify, persist/deduplicate, and acknowledge quickly;
process heavier downstream work from your own queue.
A webhook always carries a terminal outcome. If a finished result is lost
within the delivery window — an unplanned restart of the processing service, or the result
otherwise gone from its store — the callback is delivered as "status": "error" with
"results": null and error.error = DOC_JOB_002, signed and retried
like any other delivery. Poll GET /v1/process/{job_id} for the job's own state, then resubmit
with a new Idempotency-Key. A completed callback always carries results.
Delivery attempts stop one hour after the job reaches its terminal state: a callback that
has not succeeded by then is not retried and no further callback of any kind is sent for that job, so treat
the 1-hour window as the outer bound on hearing from us at all.
That error carries its own X-Webhook-Delivery-ID. The delivery id is stable
across the retries of one payload, but a job whose earlier attempt already sent you completed
results (an acknowledgement can be lost after your server stored them) gets a DIFFERENT id for the
DOC_JOB_002 error, so deduplicating on the header never makes the two collapse into one and
never makes the error overwrite a result you already hold.
# Submit with webhook — no polling needed curl -X POST https://api.documenter.ch/v1/process \ -H "Authorization: Bearer doc_live_YOUR_KEY" \ -H "X-User-Token: YOUR_JWT" \ -H "Content-Type: application/json" \ -d '{ "mode": "document", "content": "Patient de 45 ans...", "webhook_url": "https://your-ehr.hospital.ch/webhooks/documenter" }'
Webhook Headers
Every webhook POST includes these headers:
| Header | Value | Purpose |
|---|---|---|
Content-Type |
application/json |
Body is the full result JSON |
X-Webhook-Signature |
a1b2c3d4e5... (hex HMAC-SHA256) |
HMAC-SHA256 over {timestamp}.{raw_body}, signed with your API key's signing secret. The timestamp prefix prevents replay. |
X-Webhook-Timestamp |
1714327200 |
Unix epoch seconds at signature time. Reject if drift exceeds your tolerance (we recommend 5 minutes). |
X-Webhook-Signature-Version |
v1 |
Signature scheme. Reject unknown versions so a future scheme upgrade can't trick old verifiers. |
X-Job-Id |
doc_job_xxx |
Job ID for correlation |
X-Webhook-Delivery-ID |
550e8400-e29b-41d4-a716-446655440000 (UUID) |
Unique delivery ID, constant across all retries of one payload. A job’s terminal DOC_JOB_002 error callback carries its own delivery id (see the webhook notes above). Use it to idempotently dedup webhook notifications — if the same delivery ID arrives twice (a retry after a slow ack), process it once. |
Verify the Signature
You must verify X-Webhook-Signature before processing the payload. The signature
is HMAC-SHA256(signing_secret, "{timestamp}." + raw_body) where {timestamp} is the value of X-Webhook-Timestamp — the signing secret provided with your API key. Reject
any request where the signature doesn't match.
import hashlib, hmac, json, time def verify_webhook(raw_body: bytes, signature: str, timestamp: str, signing_secret: str) -> bool: # Reject missing/malformed timestamps and signatures older than 5 minutes. try: age = abs(int(time.time()) - int(timestamp)) except (TypeError, ValueError): return False if age > 300: return False signed = timestamp.encode() + b"." + raw_body expected = hmac.new(signing_secret.encode(), signed, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature) # In your Flask/FastAPI webhook handler: @app.post("/webhooks/documenter") async def handle_webhook(request: Request): raw_body = await request.body() signature = request.headers.get("X-Webhook-Signature", "") timestamp = request.headers.get("X-Webhook-Timestamp", "") version = request.headers.get("X-Webhook-Signature-Version", "") delivery_id = request.headers.get("X-Webhook-Delivery-ID", "") if not delivery_id or version != "v1" or not verify_webhook(raw_body, signature, timestamp, SIGNING_SECRET): return Response(status_code=401) result = json.loads(raw_body) # In one DB transaction: INSERT delivery_id into a UNIQUE column and persist # the result. If INSERT ... ON CONFLICT DO NOTHING inserts 0 rows, this # delivery was already processed: return 200 without applying it twice. await webhook_inbox.store_once(delivery_id, result) return Response(status_code=200)
using System.Security.Cryptography; bool VerifyWebhook(byte[] rawBody, string signature, string timestamp, string signingSecret) { // Reject signatures older than 5 minutes (replay defense). var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds(); if (Math.Abs(now - long.Parse(timestamp)) > 300) return false; var signed = Encoding.UTF8.GetBytes(timestamp + ".").Concat(rawBody).ToArray(); using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(signingSecret)); var expected = Convert.ToHexString(hmac.ComputeHash(signed)).ToLowerInvariant(); return CryptographicOperations.FixedTimeEquals( Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(signature)); } // In your ASP.NET controller: [HttpPost("/webhooks/documenter")] public async Task<IActionResult> HandleWebhook() { using var reader = new StreamReader(Request.Body); var rawBody = await reader.ReadToEndAsync(); var signature = Request.Headers["X-Webhook-Signature"].ToString(); var timestamp = Request.Headers["X-Webhook-Timestamp"].ToString(); var version = Request.Headers["X-Webhook-Signature-Version"].ToString(); if (version != "v1" || !VerifyWebhook(Encoding.UTF8.GetBytes(rawBody), signature, timestamp, _signingSecret)) return Unauthorized(); var result = JsonSerializer.Deserialize<JsonElement>(rawBody); // Process result... return Ok(); }
import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.security.MessageDigest; import java.util.HexFormat; boolean verifyWebhook(byte[] rawBody, String signature, String timestamp, String signingSecret) { try { // Reject signatures older than 5 minutes (replay defense). long now = System.currentTimeMillis() / 1000; if (Math.abs(now - Long.parseLong(timestamp)) > 300) return false; byte[] signed = ByteBuffer.allocate((timestamp + ".").getBytes().length + rawBody.length) .put((timestamp + ".").getBytes()).put(rawBody).array(); Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(signingSecret.getBytes(), "HmacSHA256")); String expected = HexFormat.of().formatHex(mac.doFinal(signed)); return MessageDigest.isEqual(expected.getBytes(), signature.getBytes()); } catch (Exception e) { return false; } } // In your Spring controller: @PostMapping("/webhooks/documenter") public ResponseEntity<Void> handleWebhook( @RequestBody byte[] rawBody, @RequestHeader("X-Webhook-Signature") String signature, @RequestHeader("X-Webhook-Timestamp") String timestamp, @RequestHeader("X-Webhook-Signature-Version") String version) { if (!"v1".equals(version) || !verifyWebhook(rawBody, signature, timestamp, signingSecret)) return ResponseEntity.status(401).build(); // Process result... return ResponseEntity.ok().build(); }
// In your webhook endpoint: $rawBody = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''; $timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? ''; $version = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE_VERSION'] ?? ''; // Reject unknown scheme version + timestamps older than 5 minutes (replay defense). if ($version !== 'v1' || abs(time() - (int)$timestamp) > 300) { http_response_code(401); exit; } $signed = $timestamp . '.' . $rawBody; $expected = hash_hmac('sha256', $signed, $signingSecret); if (!hash_equals($expected, $signature)) { http_response_code(401); exit('Invalid signature'); } $result = json_decode($rawBody, true); // Process result... http_response_code(200);
const crypto = require('crypto'); function verifyWebhook(rawBody, signature, timestamp, signingSecret) { // Reject signatures older than 5 minutes (replay defense). if (Math.abs(Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)) > 300) return false; const signed = Buffer.concat([Buffer.from(timestamp + '.'), rawBody]); const expected = crypto.createHmac('sha256', signingSecret).update(signed).digest('hex'); if (expected.length !== signature.length) return false; return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); } // Express.js (use raw body parser): app.post('/webhooks/documenter', express.raw({type: 'application/json'}), (req, res) => { const signature = req.headers['x-webhook-signature'] || ''; const timestamp = req.headers['x-webhook-timestamp'] || ''; const version = req.headers['x-webhook-signature-version'] || ''; if (version !== 'v1' || !verifyWebhook(req.body, signature, timestamp, SIGNING_SECRET)) return res.status(401).send('Invalid signature'); const result = JSON.parse(req.body); // Process result... res.status(200).send(); });
5.2 Response schemas
Job responses use two closely-related envelopes: a compact 202 submission acknowledgement,
then the status envelope returned by polling and webhooks. Immediate 4xx/5xx failures
use the separate error envelope shown under Error Codes.
The envelope, field by field
| Field | 202 submit | processing | completed | error | cancelled |
|---|---|---|---|---|---|
job_id |
yes | yes | yes | yes | yes |
status |
"processing" |
"processing" |
"completed" |
"error" |
"cancelled" |
mode |
yes | yes | yes | yes | yes |
steps |
yes | yes | yes | yes | yes |
poll_url |
yes | — | — | — | — |
estimated_seconds |
yes | — | — | — | — |
current_step |
— | yes | — | — | — |
estimated_seconds_remaining (reserved) |
— | null | null | null | null |
billing_notices |
yes | yes | yes | yes | yes |
results |
— | null |
object | null |
null |
error |
— | null |
null |
{error, message} |
null |
created_at / completed_at |
— | created_at |
both | created_at |
created_at |
billing_notices is always present as an array — empty when every requested step ran (see
Poll & webhooks). A cancelled job carries error: null
— a deliberate cancel is not a failure. The per-mode results shapes follow.
Detailed result schemas and complete examples
Document mode with transcription + generation + TARDOC. Each key only appears if that step ran.
{
"job_id": "doc_job_kVG4OV0K...",
"status": "completed",
"mode": "document",
"steps": ["transcription", "generation", "tardoc"],
"results": {
"transcription": {
"text": "[Medecin] Bonjour...\n[Patient] J'ai des maux de tete...",
"speakers": [
{"id": 1, "label": "Medecin"},
{"id": 2, "label": "Patient"}
],
"medications": [
{"name": "Paracetamol", "dosage": null, "frequency": null}
],
"audio_events": [],
"duration_seconds": null,
"language": null
},
"generation": {
"content": "<article class=\"documenter-report\">\n <section data-key=\"titre\"><h2>Rapport de consultation</h2></section>\n <section data-key=\"anamnese\"><h2>Anamnèse</h2><p>Patient de 45 ans...</p></section>\n ...\n</article>",
"format": "html",
"tokens_in": 850,
"tokens_out": 420
},
"tardoc": {
"codes": [
{"code": "AA.00.0010", "description": "Consultation de base, 5 min", "tp": 9.57, "quantity": 1},
{"code": "AA.00.0020", "description": "Consultation, +5 min", "tp": 9.57, "quantity": 3}
],
"total_tp": 53.73,
"currency": "CHF",
"diagnoses": [
{"patient_index": 1, "letter": "E", "code_range": "E10-E14", "description": "Diabète sucré"}
]
}
},
"error": null,
"created_at": "2026-04-04T14:30:00Z",
"completed_at": "2026-04-04T14:31:25Z"
}
Field Reference
| transcription | ||
|---|---|---|
text |
string | Full transcript with speaker labels: [Medecin] ...\n[Patient] ... |
speakers |
array | [{id: int, label: "Medecin"|"Patient"}] |
medications |
array |
[{name, dosage, frequency}], names matched against the Swissmedic DB (a drug with no reliable match keeps its spoken name).
dosage and frequency are declared but not surfaced today —
read them as always null.
|
audio_events |
array |
Detected non-speech events. May be empty — treat [] as the
normal case rather than a signal.
|
duration_seconds |
float? | Audio duration in seconds. Populated on every audio job; still declared nullable, so handle null defensively. |
language |
string? | Detected language (FR, DE, IT, EN). May be null — it is reported only when language identification ran on the audio, so handle null. |
transcript_token |
string? |
Send it back with this exact text as content to generate further
documents from the transcript on any plan. No expiry. Returned on the poll and in webhooks.
|
| generation | ||
content |
string |
The real medical report, always a string, rendered in the requested
output_format. html: an
<article class="documenter-report"> wrapping one
<section data-key="…"> per report section (each with an
<h2> heading). text: plain text.
markdown: Markdown. json: a JSON-encoded string on a
locked schema — parse it (e.g. JSON.parse) to get the
{schema_version, output_mode, sections, extracted_at} object; see
Structured JSON output just below.
docx: base64-encoded Word bytes — decode before writing
the file; see Word (.docx) output. The model's internal
<reasoning> and per-source <extraction> provenance are
never included in any format.
|
format |
string | Output format used |
tokens_in |
int? | Input tokens consumed |
tokens_out |
int? | Output tokens generated |
| tardoc | ||
codes |
array | [{code, description, tp: float, quantity: int}] |
total_tp |
float | Total tax points |
currency |
string | Always "CHF" |
diagnoses |
array | [{patient_index: int, letter, code_range, description}] — primary diagnosis per patient as extracted by the pipeline: the ICD-10-GM first letter plus the block range containing it and its French label (e.g. "E", "E10-E14", "Diabète sucré"). Never the full code. patient_index is the 1-based position of the patient in the consultation; patients are never named. Patients without an extracted diagnosis are omitted, so the array may be empty. |
Structured JSON output (output_format: "json")
When you request output_format: "json", generation.content is a
JSON-encoded string — parse it (e.g. JSON.parse /
json.loads) to get the structured object on a locked schema:
{schema_version, output_mode, sections, extracted_at}, where the medical report is split into
ordered sections, each carrying a stable machine key for your EHR to map and the report's
original human title. (The JSON below is the parsed object — on the wire it
arrives as a string inside content.)
{"sections":[{"name","relevance","content"}], "reasoning", "extracted_at"}. The
name field is renamed and split into two: key (the stable
snake_case English machine key) and title (the verbatim human heading). The
relevance and top-level reasoning fields are gone — the
model's reasoning is never emitted. If you previously read section.name, switch to
section.key for routing and section.title for display.
{
"schema_version": 1,
"output_mode": "structured",
"sections": [
{
"key": "diagnostic",
"title": "Diagnostic",
"parent": null,
"content": "Céphalées de tension chroniques. Hypertension artérielle de stade 1."
},
{
"key": "anamnese",
"title": "Anamnèse",
"parent": null,
"content": "Patiente de 45 ans consultant pour des céphalées frontales bilatérales évoluant depuis 2 semaines, aggravées par le stress."
},
{
"key": "antecedents",
"title": "Antécédents",
"parent": null,
"content": "Pas d'antécédent neurologique. Migraine maternelle."
},
{
"key": "examen_clinique",
"title": "Examen clinique",
"parent": null,
"content": "TA 138/86 mmHg. Examen neurologique sans particularité. Pas de raideur de nuque."
},
{
"key": "laboratoire",
"title": "Laboratoire",
"parent": null,
"content": "FSC, ionogramme et CRP dans les normes."
},
{
"key": "appreciation",
"title": "Appréciation",
"parent": null,
"content": "Tableau compatible avec des céphalées de tension dans un contexte de stress, sans signe d'alarme."
},
{
"key": "suivi",
"title": "Suivi",
"parent": null,
"content": "Contrôle tensionnel à domicile. Réévaluation dans 3 semaines si persistance."
},
{
"key": "unmapped",
"title": "Salutations",
"parent": null,
"content": "Avec mes meilleures salutations,\nDr méd. Anne Favre"
}
],
"extracted_at": "2026-06-10T14:31:25Z"
}
| Field | Type | Description |
|---|---|---|
schema_version |
int | Currently 1. Bumped only on a breaking schema change. |
output_mode |
string |
"structured" = the report was split into canonical sections.
"free_text" = a narrative / insurance-form template returned as a single section with
key: "free_text". The mode is determined by the chosen prompt, not by a request flag.
|
sections[].key |
string |
The stable machine key your EHR maps to its own fields (or have DOCumenter return
your field names directly — see below) — always snake_case
English (e.g. diagnostic, anamnese, antecedents,
examen_clinique, laboratoire, appreciation,
traitements, suivi). The canonical catalog is roughly
31 keys — it is the section taxonomy, not a tiny closed set. Fetch the full,
authoritative list from GET /v1/section-keys (also shown in the
developer console’s Mapping tab). A report-level top heading (the document title) is emitted as
key: "titre"; document chrome (no heading at all) falls back to
"unmapped", and a titled heading the catalog does not recognise falls back to the
reserved key "autre" (below) — nothing is dropped. Route on this, not on
title.
|
sections[].title |
string | null |
The report's original heading, verbatim, in the report's language (French, German,
or Italian). For display only — it varies by locale and prompt. null for a
preamble section (text before the first heading) and for the single free_text section.
|
sections[].parent |
string | null |
The original parent heading when a sub-section was promoted to top-level; null at the top
level.
|
sections[].content |
string | The clinical text of that section, Markdown-formatted. The clinical content is preserved, but a
sub-heading that doesn't match a canonical section may be folded into its parent's content as a
bold label (e.g. **Résultats**) rather than emitted as its own section
— so it is faithful, not strictly byte-for-byte verbatim. |
extracted_at |
string | ISO 8601 timestamp of when the structured output was produced. Note: timestamps in real responses
serialize with a numeric UTC offset (…+00:00), not a Z suffix — both are
valid ISO 8601, so use a parser that accepts either (the examples on this page abbreviate to Z). |
key: "titre". A titled
heading that doesn't match a canonical key is emitted under the reserved key "autre", with the
heading itself preserved verbatim in title — so every key you receive is one you can map,
and the fallback is never derived from the report's own wording. Document chrome (salutation, signature) and any
preamble before the first heading are bucketed under key: "unmapped" rather than discarded, so
the round-trip is lossless. The same report-body fix applies to html, markdown, and
text: they now render the real medical report and never leak the model's
<reasoning> or <extraction> blocks.
key is the
canonical snake_case key above and your EHR maps it on your side. Alternatively, DOCumenter can return
your EHR's own field names directly — and merge several canonical keys into one of your
fields — applied server-side, organisation-wide (one map per organisation, shared by every key your org
owns). Unmapped keys pass through unchanged. One exception to merging: autre is a
whole class of unclassified sections rather than a single field, so mapping it remaps each such section
independently — they keep their own title and are never folded together, even when
another canonical key targets the same field. You edit the map yourself in the developer console
(documenter.ch → Developers → Mapping), with a live preview. The map in force when a job
completes is the one applied to it — a later edit affects new jobs only, never a job that has
already finished. Sandbox honors the same map —
sandbox structured output is rendered through the real converter with your org’s field map applied, so what you
see in sandbox matches live exactly.
Word (.docx) output (output_format: "docx")
When you request output_format: "docx", generation.content is the
base64-encoded bytes of a Word document and generation.format is
"docx". The response envelope is unchanged — content is still a string, so
polling, webhooks and sandbox all work exactly as they do for the text formats. Decode it before writing
the file:
# Python import base64 docx = base64.b64decode(result["results"]["generation"]["content"]) open("rapport.docx", "wb").write(docx) // JavaScript (Node) const docx = Buffer.from(result.results.generation.content, "base64") fs.writeFileSync("rapport.docx", docx)
The document is plain styled — the same headings-and-paragraphs rendering as the
html output, with no practice letterhead. Applying your own uploaded canvas template to
/v1 exports is not supported today; if you need letterhead, generate the report as
html and merge it into your own template on your side.
On a rendering failure this endpoint does not downgrade. If the document cannot be
built, the poll returns a retryable 503 DOC_SVC_001 rather than a text body
— the same fail-closed rule output_format: "json" follows. Poll again: the result
stays available and the conversion is retried. You will never receive a content that is
plain text while format claims docx, so it is always safe to
base64-decode-and-write once you get a 200.
{
"job_id": "doc_job_...",
"status": "completed",
"mode": "chat",
"steps": ["chat"],
"results": {
"chat": {
"content": "Les cephalees de tension sont le type le plus frequent...",
"tokens_in": 120,
"tokens_out": 85
}
}
}
content |
string | Assistant response text |
tokens_in |
int? | Input tokens |
tokens_out |
int? | Output tokens |
Sources: Source citations (Swiss medical references) are available in the web platform. API
source citations are on the roadmap and will be added as a sources array in a future non-breaking
update.
{
"job_id": "doc_job_...",
"status": "completed",
"mode": "rename",
"steps": ["renaming"],
"results": {
"renaming": {
"suggestions": [{
"original": "scan005.pdf",
"suggested": "BERNARD (15.03.1956) - 2026-04-04 Imagerie CT de la hanche.pdf",
"fields": {
"surname": "BERNARD",
"firstname": "Jean-Claude",
"birthdate": "15.03.1956",
"docdate": "2026-04-04",
"doctype": "Imagerie",
"content": "CT de la hanche",
"type_detail": "CT de la hanche",
"type_key": "imaging_report",
"doctor": "Dr Martin",
"source": "Cabinet Medical Lausanne",
"recipient": "Dr Rousseau",
"category": "imaging",
"modality": "CT"
}
}],
"format": {
"field_order": ["surname", "birthdate", "docdate", "doctype", "type_detail"],
"separators": [" (", ") - ", " ", " "],
"source": "key"
}
}
}
}
suggestions[].original |
string | Original filename |
suggestions[].suggested |
string | Structured filename suggestion |
suggestions[].fields |
object | Extracted: surname, firstname, birthdate, docdate, doctype, content, type_detail, type_key, doctor, source, recipient, category, modality. EVERY value is nullable — a field is null whenever the document does not name it, which in practice is common for firstname, recipient, source and doctor. The keys are always all present; only the values vary. The sandbox fixture returns two of them as null on purpose, so a parser meets that case before production. doctype is always the composed type string the filename used, so it stays consistent with suggested; type_key and type_detail give you the parts. category is derived from type_key by a fixed table, one of imaging, laboratory, functional, correspondence, procedure, legal, administrative, prescription, other; most type changes observed between repeated runs stay within one category, but not all (an operative report read as a discharge letter changes category). modality is set only when type_key is imaging_report and is otherwise null: one of RX, CT, IRM, US (including doppler), PET, SCINTI, MAMMO, DEXA, ANGIO (catheter angiography and coronarography only; an angio-CT is CT, an angio-MRI IRM). Both vocabularies are additive-only: values may be added, never renamed or removed, so treat an unknown value as other / null. |
format |
object | The naming convention this job ran under: field_order (array), separators (array), source ("key" | "user" | "default") |
Form mode. results.form.document is the filled form itself (base64, in the submitted
form's own format); fields[] carries the same values as data, in form order. With audio,
results.transcription is present too. Field-by-field reference:
Form mode.
{
"job_id": "doc_job_...",
"status": "completed",
"mode": "form",
"steps": ["form"],
"results": {
"form": {
"document": {
"content_base64": "JVBERi0xLjcKJc...",
"format": "pdf",
"media_type": "application/pdf",
"sha256": "1bc089c1b4dc..."
},
"fields": [
{"key": "p001:q001:f001", "question": "Numero de sinistre", "label": "Numéro de sinistre:",
"section": "Rapport médical LAA", "page": 1, "type": "text", "options": null, "value": "24.128.456"}
],
"summary": {
"field_count": 59, "answered_count": 26, "failed_page_count": 0,
"unplaced_field_count": 0, "continuation_page_count": 1
}
}
},
"error": null
}
value is an AI draft for the physician to verify; blanks are expected (the treating
doctor's identity and signatures are always left for you to fill).
All /v1 endpoints — including the /v1/keys management routes — return errors in the flat {error, message} shape below; structured route errors and 422 schema-validation failures both use it (validation failures add an errors array). The one exception is an unhandled 500, which returns a plain {"detail": "…"} body. In a poll response the error field replaces results.
// Job-level error (poll response) { "job_id": "doc_job_...", "status": "error", "mode": "document", "steps": ["generation"], "results": null, "error": { "error": "DOC_SVC_001", "message": "audio_truncated", "reason": "audio_truncated" // optional, see Errors → reason } } // Request-level error (immediate, no job created) { "error": "DOC_AUTH_001", "message": "Invalid API key" }
Request errors (401, 400, 403, 413) return immediately with {error, message}. No
job is created.
Job errors (processing failures) create a job that transitions to
"status": "error" with details in the error field. A job error may also carry
an optional reason, a bounded machine-readable cause (see
Terminal job error reasons); it is absent when the cause is unknown.
6. Errors & retries
All public machine-to-machine /v1 endpoints — processing, prompts, entitlements, and health
— return errors in the flat envelope below; both structured route errors and
422 schema-validation errors use it, and schema validations also add an errors array
for debugging (route-raised 400s do not — only 422 schema
failures). Exception: an unhandled 500 returns a plain
{"detail": "Internal server error"} body, which does not use the flat
error/message envelope.
// Structured route error (most error codes) { "error": "DOC_VAL_007", "message": "prompt_id not found or not accessible to this API key" } // Schema validation error (missing field, bad enum, type mismatch) { "error": "DOC_VAL_001", "message": "Input should be 'concis', 'equilibre' or 'exhaustif' at `document.length`.", "errors": [ {"type": "literal_error", "loc": ["body","document","length"], "msg": "Input should be 'concis', 'equilibre' or 'exhaustif'", "input": "banana", "ctx": {"expected": "'concis', 'equilibre' or 'exhaustif'"}} ] }
Every response (including errors) includes an X-Request-Id header with a unique correlation ID for
that request. When filing a support ticket at dev@documenter.ch,
quote that ID so we can pull the full trace from our logs.
See the Error tab in Response Schemas for the full response shape.
Terminal job error reasons
A job that ends in "status": "error" may carry error.reason: a bounded
machine-readable cause, set on any terminal code (most often DOC_SVC_001). Branch on
reason, never on message. The field is absent when the cause
is unknown, and request errors never carry it. The value set is additive-only: new values
may appear, existing ones never change meaning, so treat an unknown value like an absent one.
DOC_FORM_006 never carries a reason: the code alone already means the form
itself cannot be filled.
reason |
Code | Meaning | Resubmitting the same input helps? |
|---|---|---|---|
upstream_timeout |
DOC_SVC_001 |
A model server did not answer in time. | Yes, after a short backoff. |
upstream_unavailable |
DOC_SVC_001 |
No processing node could take the job. | Yes, after a short backoff. |
internal_error |
DOC_SVC_001 |
An unexpected failure on our side. | Once. If it fails again, contact support with the job_id. |
retries_exhausted |
DOC_SVC_001 |
We already retried the job on several nodes and every attempt failed. | Once, later. If it fails again, contact support with the job_id. |
audio_truncated |
DOC_SVC_001 |
The audio file is cut short (an interrupted upload or recording). | No. Send the complete file. |
audio_unreadable_format |
DOC_SVC_001 |
The audio container cannot be read (for example a missing index). | No. Re-export the recording. |
audio_proprietary_format |
DOC_SVC_001 |
A proprietary dictaphone format we cannot decode. | No. Convert it to a standard format first. |
audio_drm_protected |
DOC_SVC_001 |
The audio is copy-protected. | No. |
audio_decode_failed |
DOC_SVC_001 |
The audio could not be decoded, for no more specific reason. | No. Re-export the recording. |
audio_empty |
DOC_SVC_001 |
The audio file is empty. | No. |
audio_silent |
DOC_SVC_001 |
The recording contains no speech. | No. |
audio_too_large |
DOC_SVC_001 |
The audio exceeds the processing size limit. | No. Split or compress the recording. |
generation_input_too_large |
DOC_SVC_001 |
The sources and instruction do not fit the model's context. | No. Send fewer or shorter sources. |
generation_loop |
DOC_SVC_001 |
The model kept repeating itself; we already retried once with different sampling. | No. Change the sources or the instruction. |
generation_length |
DOC_SVC_001 |
The document hit the output limit; we already retried once with different sampling. | No. Request a shorter document or send fewer sources. |
exam_type_undetermined |
DOC_SVC_002 |
The dictation did not name the exam. | No. See DOC_SVC_002 below. |
form_source_size |
DOC_VAL_004 |
mode: "form": the transcript pushed the sources past 512 KiB. |
No. Send less source material. |
form_no_source |
DOC_VAL_002 |
mode: "form": the audio produced no transcript and nothing else was supplied. |
No. Supply a source. |
How to react — the retry taxonomy
Before the per-code table, here is the decision your integration should make for each class of failure.
Every failure maps to exactly one action: retry-now, backoff (honor
Retry-After), refresh-credential, ask-physician,
upgrade-plan, or never (fix the request; a blind retry will fail identically).
| Failure class | Signal | Action |
|---|---|---|
| Rate limited | 429 (DOC_RATE_001, DOC_RATE_002) |
backoff — wait for Retry-After, then retry. Not a bug. |
| Service transient | 503 (DOC_SRV_001, DOC_SVC_001) |
backoff — retry with backoff, honoring Retry-After. Never rotate your key on a 503. |
| Async job failed | poll status: "error" |
retry-now — resubmit as a new job (a fresh Idempotency-Key), unless
error.reason says the input itself failed (see reasons). |
| Async job rejected your input | poll status: "error" with DOC_FORM_006 or DOC_SVC_002 |
never — nothing failed on our side and the same file/audio fails identically. Send a fillable form, or supply the exam type. |
| Invalid / revoked key | 401 (DOC_AUTH_001, DOC_AUTH_002) |
refresh-credential — fix or replace the API key. Do not retry unchanged. |
| Expired / invalid JWT | 401 (DOC_AUTH_003, DOC_AUTH_004) |
refresh-credential — sign a fresh physician JWT with the correct secret. |
| Pairing-code problem | 401 (DOC_AUTH_005) |
ask-physician — have them regenerate the pairing code on documenter.ch. |
| Plan / entitlement | 403 (DOC_BILL_001, DOC_SUB_001, DOC_LIC_001) |
upgrade-plan — ask the physician to subscribe / upgrade, or free a license seat. Never retry unchanged. |
| Bad request | 400 / 413 / 422 (DOC_VAL_001–009, 015) |
never — fix the request. The same body will fail identically. |
| Idempotency conflict | 409 (DOC_VAL_016) |
never (as-is) — use a new Idempotency-Key for the changed logical request, or retry the original request to replay its job. |
| Job gone / expired | 404 (DOC_JOB_001) / 410 (DOC_JOB_002) |
never the poll — resubmit a new job if the result expired (1-hour TTL). |
DOC_BILL_002 is not in this table — it is a non-fatal partial-fulfillment notice in
billing_notices[], not an error to react to. The full per-code reference follows; the
DOC_SIGNUP_* codes of the signup-intent routes are listed with those routes in
Onboard a doctor.
Full DOC_* error-code catalog
| Code | HTTP | Meaning |
|---|---|---|
DOC_AUTH_001 |
401 / 403 | 401: invalid or missing API key — check the Authorization: Bearer header. 403: a valid non-API-key credential (e.g. a logged-in documenter.ch browser session) was used on a /v1 data-plane endpoint — /v1 is machine-only and requires API-key auth. |
DOC_AUTH_002 |
401 | API key revoked. Issue a new one or contact dev@documenter.ch |
DOC_AUTH_003 |
401 | Physician JWT expired (institution mode) — sign a fresh token |
DOC_AUTH_004 |
401 | JWT signature invalid or malformed (institution mode) |
DOC_AUTH_005 |
401 | Missing or unrecognized X-User-Token. Institution mode: the X-User-Token header is missing (an expired JWT is DOC_AUTH_003; an invalid/malformed JWT is DOC_AUTH_004 — see those rows). Partner mode: the pairing code is missing, unknown, revoked, expired (an unpaired code expires one year after creation; a code already bound to a vendor, or minted for your organisation through a signup intent, never expires), never activated (a freshly-created code left unused for 7 days is deactivated), or bound to a different EHR vendor (a code locks to the first vendor that uses it). All partner-mode conditions return this same code so the API never reveals which one tripped. Have the physician regenerate from documenter.ch → Profile → Patient record integration. |
DOC_AUTH_006 |
403 | Key or pairing-code management requires a logged-in browser session on documenter.ch, not API-key auth — mint/rotate/revoke keys and manage pairing codes there, not through /v1. |
DOC_AUTH_007 |
403 | Your API key was used on a non-/v1 endpoint. Partner keys are restricted to the /v1 machine surface documented here — browser and account endpoints are not reachable with an API key. |
DOC_VAL_001 |
400 / 422 |
Schema validation failed: invalid mode, missing required field, bad enum value
(e.g. length: "banana", role: "system"), or type mismatch — returned as
422 with an errors array carrying the per-field validation detail for debugging. The
route-raised 400 variants — a corrupt or unsupported uploaded/base64
document, more than one audio file in a multipart upload, or (in form mode) a
form that is neither a PDF AcroForm nor a Word form, invalid
form.content_base64, or more than one form part — use the same code
but without an errors array (just {error, message}).
|
DOC_VAL_002 |
400 | No usable input for the inferred steps — document/rename mode with no content, no documents, and no audio. In form mode: no form file part with mode=form, or no readable text in any source; as a terminal job error, audio that produced no transcript with nothing else supplied. (A missing chat messages array is caught earlier as 422 DOC_VAL_001 schema validation, not this code.) |
DOC_VAL_003 |
400 | Invalid webhook URL: the URL uses https:// but resolves to a private or loopback IP (SSRF guard). A http:// URL is rejected earlier by schema validation as DOC_VAL_001 (422) because webhook_url requires the https:// scheme. |
DOC_VAL_004 |
413 | File too large (100MB/file or 200MB total). In form mode the form itself is capped at 8 MB (PDF) / 2 MB (Word) and its sources at 16 files and 512 KiB of extracted text; the source bound is re-checked once a transcript joins, so it can also arrive as a terminal job error. |
DOC_VAL_006 |
400 |
tardoc:true requires an audio source. TARDOC bills against a consultation transcript;
send audio via /v1/process/upload or with content_type=audio.
|
DOC_VAL_007 |
404 | prompt_id not found, malformed, or not accessible to this API key |
DOC_VAL_008 |
400 |
length not valid for the chosen prompt — either the prompt has no
length family, or the requested variant doesn't exist in this family. The error
message lists what's available for that prompt.
|
DOC_VAL_009 |
400 | The Idempotency-Key header exceeds 255 characters. It is rejected up front (never silently dropped, which would risk a duplicate job). Use a short unique token (e.g. a UUID). |
DOC_SRV_001 |
503 | Retryable. A server-side failure during authentication or request processing (e.g. a transient database outage) — not a problem with your key. Honor Retry-After and retry; do not rotate your key. |
DOC_RATE_001 |
429 | Per-key request rate exceeded (default 30/min). Honor Retry-After. |
DOC_RATE_002 |
429 | Concurrent job limit exceeded (default 10 active jobs per key) — wait for active jobs to finish. Returns Retry-After: 10 (vs DOC_RATE_001, whose Retry-After is the number of seconds until the window frees a slot, at most 60). |
DOC_BILL_001 |
403 | The request includes uploaded documents or free-text notes, which require a higher plan. Tier-1 (Scribe) may only generate from the audio transcript. Upgrade the physician's subscription to IA-ssistant or IA-ssistant Pro to generate from documents in addition to the transcript. mode: "form" rides the same boundary: a Scribe-plan form request is rejected the same way (capabilities.form_fill). |
DOC_BILL_002 |
— (notice) | Not an HTTP error — a non-fatal partial-fulfillment notice returned in billing_notices[] on the 202/poll/webhook. TARDOC was requested without an ia-ssistant-pro subscription, so the tardoc step was dropped; the transcript + note still ran. Upgrade the physician's plan to get billing codes. |
DOC_LIC_001 |
403 | License limit reached (institution mode, monthly cap). Blocks every /v1 call for that
physician except GET /v1/health and GET /v1/entitlements, so a monitoring
probe keeps working and you can read the plan that hit the cap. |
DOC_SUB_001 |
403 | The paired physician has no active subscription (partner mode) — they must subscribe at documenter.ch |
DOC_SVC_001 |
503 / 200 | Processing service unavailable. As a 503 — on submit, or on a poll whose result
rendering failed transiently, or whose result could not be fetched transiently — it is
retryable as-is: back off and retry, honoring
Retry-After (the underlying result is untouched; the next poll re-attempts it). As error.error inside a 200 poll body
(with "status": "error", "results": null and no Retry-After) the
job itself has failed and will never advance — this is the terminal you get when the processing
service restarted while your job was in flight (see
Edge cases → Processing restarts mid-job). The terminal form also
covers input-specific failures (a truncated or unreadable audio file, sources too
large for the model) that fail the same way on every resubmission: check
error.reason before retrying (see reasons).
When reason is absent or says the failure is transient, it is
retryable by resubmission only: submit the request again under a
new Idempotency-Key; polling the dead job forever returns the same error,
and replaying the original key returns that same dead job. |
DOC_SVC_002 |
200 | The exam type could not be determined from the dictation, so no report was generated.
Radiology only, and only where the instruction is configured with an exam-template
catalogue. Arrives as error.error inside a 200 poll body with
"status": "error" and "results": null.
Do not retry the same audio — the dictation contains no answer, so a
retry asks the same question and fails identically. Either resubmit with the exam type
supplied, or have the dictation re-recorded with the exam named in the header. Distinct
from DOC_SVC_001 on purpose: nothing failed on our side, and rotating keys or
backing off will not help. |
DOC_FORM_006 |
200 | The form you submitted with mode: "form" cannot be filled: it has no native fillable
fields — a scan, a flattened form, a Word file whose controls are not native — or it
carries active content we refuse, or bytes we cannot read. Arrives as error.error
inside a 200 poll body with "status": "error" and
"results": null; the message names the cause, and the error carries no
error.reason.
Do not retry the same file — re-export the form from its source with its
fields intact, or send a different one. The same code also ends a job whose filled document would
exceed 9 MB: send a lighter form. A form that fills only partially is not this
error: it completes, with the blank fields counted in
results.form.summary. |
DOC_JOB_001 |
404 | Job not found (or not owned by this API key) |
DOC_JOB_002 |
410 | Result expired (1h TTL, resubmit) |
DOC_VAL_015 |
400 | On POST /v1/process: the requested prompt_id is a form-fill preset, which cannot be used via the API (it is driven by an internal PDF form template you can't supply). Pick a prompt from GET /v1/prompts. |
DOC_VAL_016 |
409 | A submission reused an Idempotency-Key for a meaningfully different request. Use a new key for a new logical job. Harmless JSON reserialization and regenerated multipart boundaries are normalized and do not trigger this conflict. |
Health Check
GET /v1/health returns {"status": "ok"} when the API is operational. Use this for
uptime monitoring and alerting. No authentication required.
API versioning & stability
/v2/ with at least 6 months overlap. Non-breaking additions (new optional
fields, new result types) are added in-place. Document mode always generates a note
(including audio-only requests); if you want the transcript only, send "mode": "transcript".
mode is the single note / no-note axis, and tardoc is an orthogonal add-on
accepted in both modes.
7. Limits & data handling
Rate Limits
Every API key — partner, institution, and sandbox alike — defaults to
30 requests/minute and 10 concurrent jobs per key (a partner key's budget is shared across
all physicians paired to it); raisable per-key on request. Exceeding returns 429 with
Retry-After. The X-RateLimit-Limit (the per-minute cap) and
X-RateLimit-Window (always 60 — the window in seconds) headers appear on
normal post-auth responses (once the key is resolved), not on the early
401 auth-failure responses and not on the 429 DOC_RATE_001
rate-limit response (which carries only Retry-After: the number of seconds until the
window frees a slot, at most 60).
Polling does not count. GET /v1/process/{job_id} is exempt from
rate_limit_rpm — poll as many jobs as you have in flight without spending the budget
your submissions need, and the X-RateLimit-* headers are therefore not stamped on a poll
response. Polling the same job more often than about every 2 seconds returns
429 DOC_RATE_001 with a short Retry-After; treat it as a floor on your poll
interval, not a precise quota. Poll each job every 5 seconds (10 s after the first
30 s), or register a webhook_url and stop polling entirely. Polling job ids you do
not own is the one poll shape that DOES spend rate_limit_rpm. Once the key's 60 s window is already full (rate_limit_rpm requests
that spend the budget in the last 60 s), a poll is refused too, before its pairing code or
JWT is evaluated, with 429 DOC_RATE_001 and a Retry-After of the seconds until the
oldest of them leaves the window (1–60), so the poll route cannot be used to guess pairing
codes. Keep submissions under the budget, or honour Retry-After on polls too.
Capacity & concurrency
Defaults are 30 requests/minute and 10 concurrent jobs per key. When you batch, work
queues behind the concurrency cap rather than running in parallel: submissions beyond 10 jobs already
accepted or processing are refused with
429 DOC_RATE_002 and Retry-After: 10, and the cap frees a slot as each
job reaches a terminal state — so submit as slots free up rather than firing a whole batch at once.
Polls do not spend that budget: ten jobs in flight polled every five seconds costs
nothing against the 30/minute limit, which is reserved for submissions and the other reads. Poll one
job much faster than every 2 seconds and that poll returns 429 DOC_RATE_001 with a
short Retry-After — a floor on the interval, not a precise quota. Polls are free
only while the window has room: once submissions fill it, polls also get
429 DOC_RATE_001 until a slot frees. A
webhook_url removes polling altogether.
Transcription is the narrower path: audio jobs drain with limited parallelism, so a batch of
recordings queues behind itself — expect the wall-time of a batch to grow with its size,
rather than the whole batch finishing in the time one recording takes. Text-only document and
chat requests are not bound by that.
Audio Duration
Recommended max ~60 minutes per file (not hard-enforced). Supported: WAV, MP3, M4A, OGG, FLAC, WebM, AAC, Opus, WMA, AMR, MP4, 3GP, DSS, DVF. All audio is converted to WAV 16 kHz mono internally.
Forms (mode: "form")
The blank form: 8 MB for a PDF AcroForm, 2 MB for a Word form
(.docx/.dotx), admitted from the file's own bytes. Its sources:
16 files and 512 KiB of extracted text in total — counted
after extraction and including the transcript when you send audio. Over any of them returns
413 DOC_VAL_004. Per-key rate, concurrency and the 1-hour result TTL are the same as
every other mode.
Result TTL
Results expire after 1 hour. Fetch them promptly or use a webhook.
Need FHIR? The json output format gives you structured data you can map to FHIR resources. Native
FHIR R4 output (Composition resource) is planned —
let us know if this is a priority for your integration.
Edge cases
| Scenario | What happens |
|---|---|
| Audio is silent / too short | Transcription returns empty (or near-empty) text and no medications. The normalized
speakers array still lists the canonical Medecin / Patient labels —
don't rely on a zero-speaker count to detect silence; check text instead. |
| PDF is a scanned image | OCR runs automatically. Quality depends on scan resolution |
| Content is empty | 400 DOC_VAL_002 — "Content or documents required" |
| Webhook endpoint is down | Up to 3 delivery attempts, roughly 30s apart. After 3 failures, result is still pollable via GET for 1 hour |
| Result not polled within 1 hour | 410 DOC_JOB_002 — result expired, must resubmit |
| JSON body too large |
Recommended max ~10 MB for the /v1/process JSON body. There is no hard 10 MB
app-level cap today — the gateway accepts up to ~200 MB — but keep JSON bodies small and send
bulky audio / PDFs via /v1/process/upload (multipart) instead.
|
| Rate limit exceeded |
429 DOC_RATE_001 with only a Retry-After header (seconds until the window frees a slot, at most 60; a short 1–2 s when it is one job polled faster than the ~2 s floor, which is throttled per job and never spends the per-minute budget; a poll arriving while the window is already full gets the window's Retry-After) — the
X-RateLimit-Limit / X-RateLimit-Window headers are not on this
response (nor on the early 401 auth-failure responses). They appear on normal post-auth
responses, and on the route-level 429 DOC_RATE_002 concurrent-job limit (which carries
Retry-After: 10).
|
| Processing restarts mid-job |
An unplanned restart of the processing service loses every job it was holding. A
multi-step job — a chained pipeline such as
transcription → generation or
transcription → generation → tardoc — additionally
loses the accepted context that carries your uploaded source between steps. What you observe depends
on where the job was:
Idempotency-Key. Replaying the original key returns the original failed job
(202 whose body already carries "status": "error") and starts no new work.
Results are pollable only within the stated window and are not durable across a restart of
the processing service.
|
8. Test it live
Three ways to validate your integration before going live, in order of fastest to most thorough:
- In the browser — paste your sandbox key, click Send. ~30 seconds.
- Postman collection — pre-built requests for every endpoint, set
api_key, hit Send. ~2 minutes. - Real test files + curl — download our Bernard sample bundle (audio + PDFs + transcripts) and run the full transcription + report + TARDOC chain end-to-end. ~5 minutes.
Real test files
Download these synthetic test files (fictional patient, Swiss-realistic) and run the full pipeline yourself. The audio is a ~90-second doctor-patient consultation in French.
Postman Collection
Pre-built requests for every endpoint. Set your api_key variable and Send.
| File | Description |
|---|---|
Consultation.ogg |
Doctor-patient dialogue, 85s (audio) |
Dictée.mp3 |
Doctor dictation, 80s (audio) |
Transcript_dictee.txt |
Text transcript of the dictation |
lettre_urgences.pdf |
Emergency referral letter to CHUV |
resultats_labo.pdf |
Unilabs blood work (troponin, BNP, creatinine) |
Rapport_cardio_2025.pdf |
Cardiology report (echo + stress test) |
rapport_hospitalier.pdf |
Inpatient discharge summary |
The Exact Query: Send Raw Files → Get Everything Back
These examples use POST /v1/process/upload (multipart) to send raw files directly — no
base64, no preprocessing. We extract text from PDFs, transcribe audio, and run the full pipeline.
# Upload raw files — no encoding, no preprocessing # Audio → transcribed, PDFs → text extracted, .txt → read as-is curl -X POST https://api.documenter.ch/v1/process/upload \ -H "Authorization: Bearer doc_live_YOUR_KEY" \ -H "X-User-Token: YOUR_PHYSICIAN_JWT" \ -F "tardoc=true" \ -F "locale=fr" \ -F "output_format=json" \ -F "files=@Consultation.ogg" \ -F "files=@lettre_urgences.pdf" \ -F "files=@Rapport_cardio_2025.pdf" \ -F "files=@Transcript_dictee.txt" \ -F "text=Complément: patient anxieux, épouse présente et informée." # Returns: {"job_id": "doc_job_...", "poll_url": "/v1/process/doc_job_..."} # Poll until done (~60-120s) curl https://api.documenter.ch/v1/process/doc_job_YOUR_ID \ -H "Authorization: Bearer doc_live_YOUR_KEY" \ -H "X-User-Token: YOUR_PHYSICIAN_JWT" # You get back: # results.transcription.text → speaker-labeled transcript from audio # results.transcription.medications → extracted medications # results.generation.content → structured report (uses PDF + text context) # results.tardoc.codes → TARDOC billing codes + tax points
import time import httpx API = "https://api.documenter.ch/v1" headers = { "Authorization": "Bearer doc_live_YOUR_KEY", "X-User-Token": "YOUR_PHYSICIAN_JWT", } # Upload raw files — no encoding needed resp = httpx.post(f"{API}/process/upload", headers=headers, timeout=120, data={ "tardoc": "true", "locale": "fr", "output_format": "json", "text": "Complément: patient anxieux, épouse présente.", }, files=[ ("files", ("Consultation.ogg", open("Consultation.ogg", "rb"), "audio/ogg")), ("files", ("lettre_urgences.pdf", open("lettre_urgences.pdf", "rb"), "application/pdf")), ("files", ("Rapport_cardio_2025.pdf", open("Rapport_cardio_2025.pdf", "rb"), "application/pdf")), ("files", ("Transcript_dictee.txt", open("Transcript_dictee.txt", "rb"), "text/plain")), ]) resp.raise_for_status() job_id = resp.json()["job_id"] # Poll for at most 10 minutes. deadline = time.monotonic() + 600 while time.monotonic() < deadline: poll = httpx.get(f"{API}/process/{job_id}", headers=headers, timeout=30) poll.raise_for_status() r = poll.json() if r["status"] in ("completed", "error", "cancelled"): break time.sleep(5) else: raise TimeoutError(f"Job {job_id} did not finish within 10 minutes") if r["status"] != "completed": raise RuntimeError(r.get("error") or "Job was cancelled") print(r["results"]["transcription"]["text"]) print(r["results"]["generation"]["content"][:500]) for c in r["results"]["tardoc"]["codes"]: print(f" {c['code']} - {c['description']} ({c['tp']} TP)")
See the results
The completed poll response from the call above — one job, every step back, shown with
output_format: "json" (trimmed for readability). The html and
markdown shapes, and each step's full field reference, are in
Response Schemas.
{
"job_id": "doc_job_kVG4OV0K...",
"status": "completed", "mode": "document",
"steps": ["transcription", "generation", "tardoc"],
"results": {
"transcription": {
"text": "[Medecin] Bonjour Monsieur Bernard, qu'est-ce qui vous amene ?\n[Patient] Des douleurs dans la poitrine depuis deux jours...",
"speakers": [{"id": 1, "label": "Medecin"}, {"id": 2, "label": "Patient"}],
"medications": [{"name": "Aspirine Cardio", "dosage": null, "frequency": null}],
"audio_events": [], "duration_seconds": null, "language": null
},
"generation": {
"content": "{\"schema_version\":1,\"output_mode\":\"structured\",\"sections\":[{\"key\":\"motif_consultation\",\"title\":\"Motif de consultation\",\"parent\":null,\"content\":\"Douleurs thoraciques depuis deux jours.\"}, ...],\"extracted_at\":\"2026-06-10T14:31:25Z\"}", // JSON-encoded string — JSON.parse() it (parsed view below)
"format": "json", "tokens_in": 3120, "tokens_out": 640
},
"tardoc": {
"codes": [
{"code": "AA.00.0010", "description": "Consultation de base, 5 min", "tp": 9.57, "quantity": 1},
{"code": "AA.00.0020", "description": "Consultation, +5 min", "tp": 9.57, "quantity": 4}
],
"total_tp": 47.85, "currency": "CHF"
}
},
"error": null, "completed_at": "2026-06-10T14:31:25Z"
}
// results.generation.content after JSON.parse():
{
"schema_version": 1, "output_mode": "structured",
"sections": [
{"key": "motif_consultation", "title": "Motif de consultation", "parent": null, "content": "Douleurs thoraciques depuis deux jours."},
{"key": "anamnese", "title": "Anamnèse", "parent": null, "content": "Douleur retrosternale a l'effort, irradiation au bras gauche; dyspnee..."},
{"key": "examen_clinique", "title": "Examen clinique", "parent": null, "content": "TA 148/88 mmHg, FC 92/min. Auscultation cardiaque sans souffle."},
{"key": "diagnostic", "title": "Diagnostic", "parent": null, "content": "Suspicion de syndrome coronarien; antecedents cardiologiques (cf. rapport 2025)."}
],
"extracted_at": "2026-06-10T14:31:25Z"
}
Each step's full field reference — and the output_format: "json" structured-section
shape — is in Response Schemas.
All files are synthetic (fictional patient "Jean-Claude BERNARD"). Safe for testing. The audio files are French-language doctor-patient consultations recorded at 48kHz.
Try it live
Paste your sandbox key and send a real request.
Quick-evaluation sandbox keys need only the API key. For partner-parity sandbox, paste one of
the test-triad pairing codes into X-User-Token. Create a key
from your organisation’s developer console, or ask
dev@documenter.ch (response within 1
business hour). Your key is stored locally in your browser only — refresh-safe, never sent to us beyond
the API call itself.
9. Changelog & status
Notable, partner-visible changes to the /v1 API, newest first. Non-breaking additions (new
fields, new result types) ship in place; breaking changes ship under /v2 with at least 6 months
of overlap.
Status & support
There is no public status page yet. For a quick operational signal, poll GET /v1/health. To
report an incident or degraded performance, email
dev@documenter.ch with the X-Request-Id of a failing
response — we monitor 4xx/5xx rates and API health, and that ID lets us pull
the full trace.
View release history
-
2026-10-20
Spoken punctuation in dictation
In
"mode": "dictation", French punctuation commands (virgule, point, à la ligne, …) now come back as punctuation and line breaks inresults.transcription.text. See Dictation mode. -
2026-10-19
Dictation mode
New
"mode": "dictation"onPOST /v1/processand/v1/process/upload: one speaker dictating, plain text inresults.transcription.text, withspeakersandaudio_eventsalways[]and notranscript_token. Every plan. See Dictation mode. Additive. -
2026-10-19
Starred instructions in the listing
Each
GET /v1/promptsitem carriesis_favorite: true when the physician starred that instruction on documenter.ch, where favourites are listed first. Always false without a physician. In the sandbox, the three parity physicians star Courrier medical, so you can build against it. Additive. -
2026-10-17
Returned transcripts on multipart uploads
POST /v1/process/upload(document mode) acceptstranscriptandtranscript_token, so a returned transcript keeps counting as the consultation next to a note and documents. Other modes, an audio file sent withtranscript, or atranscript_tokenwithout itstranscriptare rejected with422 DOC_VAL_001. Additive. -
2026-10-16
Generate more documents from one transcript, on every plan
Transcripts now carry a
transcript_token. Send it back with the unchanged transcript to generate another document: the text keeps counting as a transcript, so Scribe physicians are no longer refused with403 DOC_BILL_001. Additive; nothing else changes. -
2026-10-04
Markdown links keep their brackets, and render as links in
htmlA report link written
[text](url)used to lose its brackets in every format (text(url)).htmlnow rendershttpandhttpslinks as<a href>anchors;text,markdownandjsonkeep the markdown[text](url);docxshows the link text only, without the URL. A link with any other scheme stays plain text. No field, type or default changes. -
2026-10-04
Free-text headings render as headings
In
free_textmode, a#heading directly followed by text used to appear literally (## Plan) inside a paragraph, and could be pulled into the list before it. It now renders as a heading inhtmlanddocxand ends any open list. Structured output is unchanged. No field, type or default changes. -
2026-10-04
Year-led lines stay text, not numbered lists
A line that starts with a year, such as
2019. Cholecystectomy, is now rendered as text inhtmlanddocxoutput. Before, it became a numbered list item: thehtmloutput began a list atstart="2019", and could fold the following heading or lines into it. Only markers of up to three digits start a list item. No field, type or default changes. -
2026-10-04
Bold labels split from their value are rejoined
When a report puts a bold label on one line and its colon-led value on the next (
**BP**then: 128/92), every format now renders them as one line,**BP** : 128/92. In structuredjson, such a label no longer appears as a section of its own; its value stays in the enclosing section. A label that already ends in a colon is left as it is. No field, type or default changes. -
2026-10-02
Default concurrent-job cap raised from 5 to 10
Every API key — partner, institution and sandbox — now defaults to 10 concurrent jobs instead of 5, existing keys on the old default included. A key whose cap was set to another value on request keeps it. The 30 requests/minute rate limit is unchanged, as are
429 DOC_RATE_002and itsRetry-After: 10. Additive — the cap only grows. See Limits & data handling. -
2026-10-02
Terminal job errors carry an optional
reasonA job that ends in
"status": "error"may now carryerror.reason, a bounded cause such asaudio_truncatedorupstream_timeout, identical on every poll and in the webhook body. It tells a transient failure apart from one that resubmitting the same input cannot fix. The value set is additive-only and the field is absent when the cause is unknown. Additive — no error code, HTTP status or default changed. See Terminal job error reasons. Sandbox:lengthwith an explicitprompt_idof one of the curated sandbox prompts (which list nolengths) now returns400 DOC_VAL_008, as in production; omittingprompt_idis unchanged. -
2026-10-01
Rename records carry
categoryandmodalityTwo additive keys on
suggestions[].fields.categorygroupstype_keyinto nine broad classes through a fixed table, so most changes between neighbouring types leave it unchanged.modalityis the imaging modality, set only whentype_keyisimaging_reportand null otherwise. Both value sets are additive-only; see Rename mode. Nothing on the request changed. -
2026-09-26
New: signup intents — onboard a doctor and receive their pairing code
Two new routes,
POST /v1/partner/signup-intentsandGET /v1/partner/signup-intents/{intent_id}, for organisations enabled for them. They take your API key only (noX-User-Token) and have their own 10 requests/minute budget. You get a signup link for the doctor; once they finish, the pairing code minted for your organisation is delivered by signed callback and by polling. New error codesDOC_SIGNUP_001–DOC_SIGNUP_008. Additive — no existing route, field or code changed. See Onboard a doctor. -
2026-09-25
results.tardoc.diagnoses: the primary diagnosis per patientAn additive array
[{patient_index, letter, code_range, description}]onresults.tardoc: the ICD-10-GM first letter, the block range containing the diagnosis and its French label, never the full code. Patients without an extracted diagnosis are omitted, so the array may be empty. See Response schemas. -
2026-09-25
New
formmode: send a blank official form, get it back filledPOST /v1/processandPOST /v1/process/uploadacceptmode: "form"with the blank form in its ownformfield / file part and the consultation as sources (text, documents, or audio — audio is transcribed first andresults.transcriptioncomes back too). The answer is the same form, filled, in its own format: a PDF AcroForm returns a filled, still editable AcroForm PDF, a Word form a filled.docx. The newresults.formcarries the document (base64 +sha256), every field with its value in form order, and bounded counts. Requires ia-ssistant (capabilities.form_fill, new onGET /v1/entitlements); a form that has no fillable fields terminates the job with the newDOC_FORM_006. Everything here is additive — no existing field, default, status or error code changed. Values are AI drafts the physician must verify, and the treating doctor's own identity is always left blank; see Form mode for the limits. -
2026-09-11
A paired pairing code no longer expires
A pairing code now expires one year after creation only while it is still unpaired. Once bound to your organisation by its first use it never expires, until the physician revokes or regenerates it. No request or response changed; an integration that used to stop with
DOC_AUTH_005after a year now keeps working. See Authentication. -
2026-09-08
Sandbox submits return
processing; your own pairing code works on your sandbox keyA sandbox submit now returns
202 {"status": "processing", "estimated_seconds": 1}and the job becomescompletedon your first poll, so your polling and webhook code meets the same state ladder as live; it used to return"completed"at submit. Sandbox jobs also count against the concurrent-job cap. A member of your organisation can use their own pairing code with the organisation's sandbox keys, with their real tier and preferences. No field or error code changed. See Sandbox vs production. -
2026-09-05
Rename mode follows a naming convention carried by your API key
Set the filename layout once on the key, in either imposed or default mode — see Rename mode for the resolution table. Two additive response changes:
results.renaming.formatnow reports the convention actually applied and where it came from, andsuggestions[].fieldscarries four more extracted fields (type_key,doctor,source,recipient) plustype_detail, the type's precision on its own.type_detailis also a filename field, so a convention can print the bare type label and the precision in separate slots. Nothing on the request changed. -
2026-08-30
GET /v1/promptsnow shows the sections each instruction producesEvery item carries a
sectionspreview —canonical_key,title, thepresencerule, and thekeyyou will actually receive, with your organisation's field map already applied. Build your field mapping against the listing instead of running a job to discover what comes back. It isnullfor instructions that do not declare their structure up front.is_defaultmarks the one instruction used when you omitprompt_id. Both fields are additive — nothing existing changed. See Listing prompts. -
2026-08-29
Lost results: a terminal error webhook, and
503split from410A result the processing service confirms it lost now fires a terminal error callback (
"status": "error",error.error=DOC_JOB_002) under its ownX-Webhook-Delivery-ID— so a webhook consumer learns about the loss without polling, and dedup on the delivery id still works. Polling now distinguishes the two cases: a result that is merely unreachable returns a retryable503 DOC_SVC_001withRetry-After: 30, and the410is reserved for a result that is authoritatively gone. If you treated every non-200poll as a lost job, retry the503instead. See Edge cases. -
2026-08-29
Polling is off the per-minute budget, with a ~2 s per-job floor
GET /v1/process/{job_id}no longer spendsrate_limit_rpm: poll every job you have in flight without competing with your own submissions. In its place, each (key, physician, job) is throttled to about one poll per 2 seconds — exceed it and you get429 DOC_RATE_001with a shortRetry-After. Treat it as a floor on your poll interval, not a quota.Retry-Afteron the per-minute limit is now derived from the actual window (seconds until a slot frees, never above60) rather than a flat value. Polling job ids you do not own still spends the budget. See Rate limits. -
2026-08-29
GET /v1/entitlementsand/v1/healthstay reachable over the licence capBoth routes are now exempt from the licence-cap short-circuit, so they never return
DOC_LIC_001. A monitoring probe carrying an over-cap physician’s token can still reach/v1/entitlements— which is how it discovers the cap it hit — and liveness checks keep working. Every other/v1route is unchanged. -
2026-08-29
Your EHR field map is frozen at completion
A job records the field map it completed under, and every later poll and webhook for that job is keyed with that frozen map. Editing your mapping in the developer console no longer silently re-keys results a partner already received, so a replayed webhook and the original delivery agree. New mappings apply to jobs submitted after the edit. See Section keys.
-
2026-08-28
Documented: what a processing-service restart does to an in-flight job
An unplanned restart of the processing service loses the jobs it was holding. The observable behaviour is now spelled out per case — a running job keeps returning
processingfor roughly two and a half minutes, then terminates as a200poll body with"status": "error"andDOC_SVC_001; you never receive acompletedcarrying a partial result.DOC_SVC_001also has its own row in the error catalogue. See Edge cases. -
2026-08-05
modeis the note / no-note axis;tardocworks in bothdocumentmode always generates a note, including for audio-only requests (transcribe then generate from that transcript); for the transcript only, send"mode": "transcript"."tardoc": trueis now accepted in transcript mode too — transcription plus billing codes, with no note. Four shapes in total. See Four Modes. -
2026-07-31
Closed key set —
autrereplaces ad-hoc fallback keysA titled section the catalogue cannot classify is now emitted under the reserved key
autreinstead of a slug derived from the heading's own wording. The key set is therefore closed: everykeyyou receive appears inGET /v1/section-keys. The original heading is still preserved verbatim intitle, andcatalogue_versionwas bumped with the addition. If you special-cased unknown slug keys, mapautreinstead. See Section keys. -
2026-07-30
New
GET /v1/section-keys— the mapping contract, fetchableThe canonical section-key catalogue is now an API endpoint instead of a screen in the developer console. Keys are append-only: a published key is never renamed or removed, and retirement is
deprecated: true, which keeps the key in the list and still assigned so existing mappings keep working. Pollcatalogue_versionto notice the vocabulary moving. See Section keys. -
2026-07-12
Sandbox tier simulation (the “test triad”)
Three fake pairing codes — Scribe, IA-ssistant, and IA-ssistant Pro — now let you exercise all three plan tiers entirely in sandbox: real auth, real tier gates, and
GET /v1/entitlements, with only the generated report mocked. Build and self-test your whole integration before you hold a real key. See Sandbox vs production. -
2026-07-11
New
transcriptmodeSubmit audio to the new
transcriptmode for a speaker-labeled transcript with no note generated — a first-class transcription-only path with its own tighter request schema.documentmode generates a note (including from audio); usetranscriptmode when you only ever want the transcript. -
2026-07-11
Plan tier gates + partial fulfillment (
billing_notices[])Generating from uploaded documents or free-text notes now requires an IA-ssistant plan — a Scribe-tier request that attaches them is rejected with
403 DOC_BILL_001and nothing runs. TARDOC requires IA-ssistant Pro; on a lower plan the tardoc step is dropped (transcript + note still returned) and abilling_notices[]entry (DOC_BILL_002) explains it. The newbilling_notices[]array is present on the submit response, every poll, and the webhook. -
2026-07-11
GET /v1/entitlementsRead a physician's plan tier and capabilities before submitting, so your UI can gray out unavailable options up front. The per-request
billing_notices[]remains the authoritative runtime signal. -
2026-07-11
Idempotency scoped to key + physician; conflict returns
409An
Idempotency-Keyis now scoped to your API key and the physician, so a shared partner key can't let one physician replay another's job. Reusing a key with a different logical request returns409 DOC_VAL_016; a semantically equivalent retry replays the original job and carriesIdempotent-Replayed: true. Form-fill preset templates are rejected over the API with400 DOC_VAL_015. -
2026-07-11
Webhook signing secret — self-service reveal
When you mint or rotate a key in the developer console, you can now reveal and copy its webhook signing secret once, so a console-minted key can verify the
X-Webhook-SignatureHMAC. -
2026-06-16
Contract corrections + robustness hardening
Malformed inputs that previously returned
500now return clean4xxerrors in the standard envelope. Clarified thatmodeis required on JSONPOST /v1/process, thatoutput_format: "json"returns the structured sections as a JSON-encoded string, and that omittingprompt_idselects the platform default (Note de suite - Cabinet,equilibre). -
2026-06-10
Partner API v1 launch
Initial release: submit + poll/webhook, document / chat / rename modes, structured JSON output with a stable per-section key schema and an optional organization-wide field map, plus partner (pairing-code) and institution (JWT) authentication.