Your first request

This walkthrough takes you from a fresh JWT to a successfully submitted VLM-MAD work item. About 5 minutes.

The External API does not expose a "submit batch" endpoint directly — instead, each POST /api/VlmMad/AddWorkItem* call appends a work item to your tenant's current open batch (the server creates one if needed) and returns the resulting { workBatchId, workItemId }. The batch auto-starts after a short inactivity window once AutoStartBatch is configured for your tenant.

1. Get a JWT

See Authentication. From here on, assume JWT is set in your shell:

JWT="$(curl -s -X POST https://api.docmation.eu/api/Login/Authenticate \
  -H 'Content-Type: application/json' \
  -d '{"apiKey":"<key>","secret":"<secret>"}' | jq -r .bearerToken)"

2. Submit a VLM-MAD "create document" work item

POST /api/VlmMad/AddWorkItemCreate — the controller appends the item to your open batch and returns the assigned ids.

curl -X POST "https://api.docmation.eu/api/VlmMad/AddWorkItemCreate" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d @item.json

item.json (replace <…> placeholders with values from your planning system; field names must match VlmMadWorkItemCreate exactly — see Docmation.Server/Controllers/Api/Model/VLM/MAD/VlmMadWorkItemCreate.cs):

{
  "customerReference": "INT-0001",
  "documentReference": null,
  "webhookUrl": "https://example.com/docmation/webhook/{0}",
  "operatorCode": "EV.99999.000-99",
  "manureType": "PAARDEN (26) - Dierlijke - Vaste Mest",
  "date": "2026-06-04T00:00:00+02:00",
  "plannedLoad": 26,
  "transporter": "<transporter-code>",
  "sender": "<sender-code>",
  "receiver": "<receiver-code>"
}

Response:

{
  "workBatchId": 12345,
  "workItemId": 67890
}

3. Poll for the result

GET /api/VlmMad/GetResult?workItemId={id} returns the work item's current status and (when complete) the produced document data:

curl "https://api.docmation.eu/api/VlmMad/GetResult?workItemId=67890" \
  -H "Authorization: Bearer $JWT"

The work item moves through Queued → Running → Completed (or Failed). The parent batch's state is a computed projection of its items — see Work Batches for the full state diagram.

If you prefer not to poll, set webhookUrl on the work item (as in the example above) and Docmation will call you when the item completes — see Errors & retries for the delivery semantics.

Next

For task-driven recipes (cancel, download, webhooks, etc.) jump to How-to guides.

Routes and DTO field names verified against Docmation.Server/Controllers/Api/VlmMadController.cs and Docmation.Server/Controllers/Api/Model/VLM/MAD/VlmMadWorkItemCreate.cs on 2026-06-04. Re-verify if the controller or DTOs change.