Skip to main content
Every processing request includes a documents array. Each document must have a type field that determines how Matil receives the content.

​
URL

Send a direct download link. Matil fetches the file and processes it. 
{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/invoice.pdf"
    }
  ]
}
The URL must point directly to the file. Links that require authentication, redirect to a login page, or return HTML instead of the file will fail with a 400 error. For services like Google Drive or Dropbox, use the direct download URL, not the sharing link.

​
Base64

Send the file content encoded in base64. Always include mime_type so Matil knows how to process the file. 
{
  "documents": [
    {
      "type": "base64",
      "content": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZw...",
      "mime_type": "application/pdf",
      "filename": "invoice.pdf"
    }
  ]
}
FieldRequiredDescription
contentYesThe base64-encoded file content.
mime_typeNoMIME type of the file (e.g. application/pdf, image/png). Strongly recommended.
filenameNoOriginal filename. Helps Matil detect the file type when mime_type is not provided.
Send only the raw base64 string. Do not include the data:application/pdf;base64, prefix — that is a Data URI format used in browsers, not in API requests.

​
Encoding a file to base64

import base64

with open("invoice.pdf", "rb") as f:
    content = base64.b64encode(f.read()).decode("utf-8")

# Use in your request
document = {
    "type": "base64",
    "content": content,
    "mime_type": "application/pdf",
    "filename": "invoice.pdf"
}

​
Text

Send plain text directly. This is useful for passing additional instructions or context alongside other documents, or for processing text that you already have extracted. 
{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/invoice.pdf"
    },
    {
      "type": "text",
      "text": "The invoice currency is USD. The supplier VAT ID is ES12345678A."
    }
  ]
}
In this example, the first document is the actual file and the second provides extra context that helps Matil extract the data more accurately.

​
Multiple documents

You can send multiple documents in a single request. Matil processes them together as a single unit. 
{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/invoice-page1.pdf"
    },
    {
      "type": "url",
      "url": "https://example.com/invoice-page2.pdf"
    }
  ]
}

​
Per-document metadata

Each document accepts an optional metadata object for your own tracking: 
{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/invoice.pdf",
      "metadata": {"source": "email", "sender": "supplier@example.com"}
    }
  ]
}