Skip to main content
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:
ValueBehavior
trueA webhook is sent as each item completes.
falseA single webhook is sent when the entire batch finishes.
Check batch progress at any time: 
GET /v3/batches/{batch_id}