Quickstart

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

A Matil account — sign up here
An API key
A deployment ID

Don’t have these yet? Follow the steps below.

Get your API key

Open the dashboard

Create a new key

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

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
}

Field	Description
`entry_id`	Unique ID for this result. Use it to retrieve or correct the entry later.
`resource_type`	Always `"structure"`.
`resource_id`	The structure used for extraction.
`resource_version_number`	The version of the structure that was applied.
`data`	The extracted data, structured as JSON.
`errors`	Validation errors, if any. `null` when everything is correct.
`status`	`completed`, `completed_with_errors`, or `failed`.
`time_ms`	How long processing took, in milliseconds.
`price`	Cost 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.

Getting Started

Concepts

What you need

Get your API key

Find your deployment ID

Make your first request

Understand the response

What’s next?

Deployments

Document formats

Processing modes

Error handling

​What you need

​Get your API key

​Find your deployment ID

​Make your first request

​Understand the response

​What’s next?

Deployments

Document formats

Processing modes

Error handling

What you need

Get your API key

Find your deployment ID

Make your first request

Understand the response

What’s next?