# Introduction

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

Source: https://zild.ai/en-US/docs/api-reference/documents-introduction

## Integration flow

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

- upload the file to `POST /Document`;
- store the `id` returned by the API;
- wait for the Document Events Webhook request;
- 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](/en-US/docs/api-reference/webhooks#document-webhooks) for endpoint setup and every event in the document processing lifecycle.