Poll work-item status

When to use this

You submitted a work item (create / cancel / download / auto-sign) and want to know whether the bot has processed it. Use this when you cannot host a webhook receiver, when a webhook is taking too long to arrive, or as a defensive cross-check after retries. For result payloads with the underlying document data, use the channel-specific GetResult endpoints instead (see Download a document).

Prerequisites

• A valid JWT (see Authentication) issued for an API key with Role.ApiKey.
• Either the server-generated workItemId, or the original customerReference plus the taskType enum value.

Walkthrough

1. Look up by workItemId

GET /api/WorkItem/GetById?workItemId=<id>

curl "https://api.docmation.eu/api/WorkItem/GetById?workItemId=67890" \
  -H "Authorization: Bearer <jwt>"

Response (HTTP 200 OK):

{
  "creation": "2026-06-04T08:00:00+02:00",
  "workItemId": 67890,
  "customerReference": "ORDER-2026-0001",
  "documentReference": "MAD-BE-2026-000123456",
  "status": "Processing",
  "taskType": "Vlm_Mad_Create",
  "documentType": "Vlm_Mad",
  "webhookUrl": "https://example.com/docmation/webhook/{0}",
  "documentUrl": null,
  "logSummary": [
    { "code": "Generic_Item_Started", "count": 1 }
  ],
  "companyId": 42
}

status is the WorkItemStatus enum:

Value	Meaning	What to do
Created (20)	Submitted, not yet queued.	Keep polling.
Queued (30)	Waiting for a bot to pick it up.	Keep polling.
Processing (40)	A bot is actively working on it.	Keep polling.
Faulted (50)	Processing failed.	Inspect the channel-specific GetResult for the log; do not auto-retry.
Finished (60)	Done.	Fetch the result.
FeedbackSend (70)	Webhook delivered.	Done — no further action.
Invalid (10)	Validation failed before queue.	Fix the input and resubmit a new work item.

2. Look up by customerReference + taskType

Useful when you lost the workItemId (network failure during submit, replayed request):

curl "https://api.docmation.eu/api/WorkItem/GetByReference?reference=ORDER-2026-0001&taskType=Vlm_Mad_Create" \
  -H "Authorization: Bearer <jwt>"

Same response shape as GetById. taskType values: Vlm_Mad_Create (11), Vlm_Mad_Cancel (12), Vlm_Mad_Close (13), Vlm_Mad_Download (14), Vlm_Mad_AutoSign (15), Traces_Docom_Create (21), Traces_Docom_Cancel (22), Traces_Docom_Download (23), NvwaRvdmCreate (31).

3. Polling strategy

• Start at 5 second intervals while status is Created / Queued / Processing.
• Back off to 30 seconds once you have seen Processing for more than 2 minutes.
• Stop polling once status is Finished, FeedbackSend, Faulted, or Invalid.
• Prefer the webhook (see Receive webhooks) if your network can accept inbound calls — polling is the fallback, not the primary path.

What to watch for

• 404 Not Found — the workItemId (or customerReference + taskType combination) does not exist within your tenant. Tenant scoping is enforced via the JWT, so an id created under a different tenant will also return 404. Verify the id was issued for the same API key you are now using.
• 401 Unauthorized — re-authenticate via /api/Login/Authenticate.
• Faulted vs Invalid — Invalid means the input never made it to the bot (validation rejected it pre-queue); Faulted means the bot tried, failed, and recorded the failure. Both are terminal — do not retry the same work item; submit a new one with corrected data.
• No optimistic-concurrency on reads — these endpoints are pure GETs and are safe to retry as often as you like.
• Webhook race — if you also configured a webhookUrl, the webhook may arrive while you are polling. Treat them as idempotent signals of the same event.

AI-drafted from WorkItemController.cs. Verify field names against the live Swagger UI before publishing.