Introduction

Learn how to upload a file to the Documents API and asynchronously receive the processing result through the DocumentCompleted webhook.

Integration flow

Document processing is asynchronous. Before starting, register a URL for the DocumentCompleted event (webhookType: 9). Then your application should:

  1. upload the file to POST /Document;
  2. store the id returned by the API;
  3. wait for the Document Events Webhook request;
  4. confirm that DocumentStatusType is 4 (Completed) and correlate the result using Id.

Do not keep the upload request open while waiting for processing. The upload response confirms document creation; completion arrives asynchronously through the webhook.

File upload payload

Send the body as multipart/form-data, not JSON. The file part contains the file bytes; the other values are form fields.

curl --request POST \
  --url 'https://api.zild.ai/Document' \
  --header 'X-API-Key: YOUR_USER_API_KEY' \
  --form 'file=@Contract.pdf;type=application/pdf' \
  --form 'Title=Contract.pdf' \
  --form 'Description=Contract uploaded by the finance system' \
  --form 'DocumentChecklistId=7' \
  --form 'Private=false'

The API returns the created document. Store its id to correlate it with the webhook's Id field.

Processed file webhook payload

When processing completes, Zild sends a POST request with Content-Type: application/json to the URL registered for DocumentCompleted. The received body has this format:

{
  "Id": 123,
  "TenantId": 45,
  "Title": "Contract.pdf",
  "Description": "Contract uploaded by the finance system",
  "ExtractedText": "Extracted document text...",
  "QuantityPages": 8,
  "AnalysisText": "Analysis result...",
  "FileUrl": "https://...",
  "DocumentStatusId": 12,
  "DocumentType": 2,
  "CreatedAt": "2026-09-24T12:00:00Z",
  "AnalizedAt": "2026-09-24T12:01:30Z",
  "DocumentChecklistId": 7,
  "Private": false,
  "CreatedByUserId": 18,
  "DocumentStatusType": 4
}

DocumentStatusType: 4 means the file was processed successfully. Use Id to locate the uploaded document, handle duplicate deliveries idempotently, and respond quickly with a 2xx status.

Document webhooks

See Document webhooks for endpoint setup and every event in the document processing lifecycle.