Processing modes

Matil offers three ways to process documents through a deployment. All three use the same document input format and return the same result structure.

Synchronous

The request blocks until processing completes. The result is returned directly in the response.

POST /v3/deployments/{deployment_id}

Use this when you need the result immediately and can wait for the response (typically 1-10 seconds).

Asynchronous

The request returns immediately with an entry_id and status: "pending". The result is delivered to your webhook URL when ready.

POST /v3/deployments/{deployment_id}/async

Include a webhook object in the request body:

{
  "documents": [{"type": "url", "url": "https://example.com/invoice.pdf"}],
  "webhook": {
    "url": "https://your-server.com/webhook",
    "secret": "your-webhook-secret"
  }
}

Use this when you don’t need the result immediately and want to decouple submission from result handling.

Batch

Submit up to 100 items in a single request. Returns a batch_id and total item count. Results are delivered via webhook.

POST /v3/deployments/{deployment_id}/batch

{
  "requests": [
    {
      "metadata": {"order_id": "ORD-001"},
      "documents": [{"type": "url", "url": "https://example.com/invoice-1.pdf"}]
    },
    {
      "metadata": {"order_id": "ORD-002"},
      "documents": [{"type": "url", "url": "https://example.com/invoice-2.pdf"}]
    }
  ],
  "webhook": {
    "url": "https://your-server.com/webhook",
    "secret": "your-webhook-secret",
    "incremental": true
  }
}

The incremental flag controls delivery:

Value	Behavior
`true`	A webhook is sent as each item completes.
`false`	A single webhook is sent when the entire batch finishes.

Check batch progress at any time:

GET /v3/batches/{batch_id}

API Reference

Endpoints

Synchronous

Asynchronous

Batch

​Synchronous

​Asynchronous

​Batch

Synchronous

Asynchronous

Batch