Skip to main content
This guide walks you through making your first document processing request. By the end, you’ll have sent a document and received structured data back.

​
What you need

  1. A Matil account — sign up here
  2. An API key
  3. A deployment ID
Don’t have these yet? Follow the steps below.

​
Get your API key

1

Open the dashboard

Log in to the Matil Dashboard and go to Settings > API Keys.
2

Create a new key

Click Create New Key. Give it a name that helps you identify its purpose (e.g., “Development” or “Production”).
3

Copy the key

Copy your API key immediately — it won’t be shown again.
Store your API key in an environment variable. Never hardcode it in your source code or commit it to version control.

​
Find your deployment ID

Go to Deployments in the dashboard. Select the deployment you want to use and copy its ID. A deployment ID is a UUID like: 01234567-89ab-cdef-0123-456789abcdef
If you don’t have a deployment yet, create one in the dashboard first. A deployment defines what data you want to extract and from which type of document.

​
Make your first request

Send a document to your deployment: 
curl -X POST "https://api.matil.ai/v3/deployments/{your-deployment-id}" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "type": "url",
        "url": "https://example.com/invoice.pdf"
      }
    ]
  }'

import requests

API_KEY = "your-api-key"
DEPLOYMENT_ID = "your-deployment-id"

response = requests.post(
    f"https://api.matil.ai/v3/deployments/{DEPLOYMENT_ID}",
    headers={
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "documents": [
            {
                "type": "url",
                "url": "https://example.com/invoice.pdf"
            }
        ]
    }
)

result = response.json()
print(f"Entry ID: {result['entry_id']}")
print(f"Status: {result['status']}")
print(f"Extracted Data: {result['data']}")

const API_KEY = "your-api-key";
const DEPLOYMENT_ID = "your-deployment-id";

const response = await fetch(
  `https://api.matil.ai/v3/deployments/${DEPLOYMENT_ID}`,
  {
    method: "POST",
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      documents: [
        {
          type: "url",
          url: "https://example.com/invoice.pdf"
        }
      ]
    })
  }
);

const result = await response.json();
console.log("Entry ID:", result.entry_id);
console.log("Status:", result.status);
console.log("Extracted Data:", result.data);

​
Understand the response

A successful response looks like this: 
{
  "entry_id": "01934b1a-89ab-7def-0123-456789abcdef",
  "resource_type": "structure",
  "resource_id": "01934b1a-1234-7abc-0000-111122223333",
  "resource_version_number": 1,
  "data": {
    "invoice_number": "INV-2024-001",
    "date": "2024-01-15",
    "total": 150.00
  },
  "errors": null,
  "status": "completed",
  "time_ms": 2340,
  "price": 0.05
}
FieldDescription
entry_idUnique ID for this result. Use it to retrieve or correct the entry later.
resource_typeAlways "structure".
resource_idThe structure used for extraction.
resource_version_numberThe version of the structure that was applied.
dataThe extracted data, structured as JSON.
errorsValidation errors, if any. null when everything is correct.
statuscompleted, completed_with_errors, or failed.
time_msHow long processing took, in milliseconds.
priceCost of this request.

​
What’s next?

Deployments

Understand how deployments connect structures to API calls.

Document formats

Learn about all the ways you can send documents to Matil.

Processing modes

Sync, async, and batch processing explained.

Error handling

Handle errors gracefully in your integration.