Document input

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"
    }
  ]
}

Field	Required	Description
`content`	Yes	The base64-encoded file content.
`mime_type`	No	MIME type of the file (e.g. `application/pdf`, `image/png`). Strongly recommended.
`filename`	No	Original 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"
}

import fs from "fs";

const content = fs.readFileSync("invoice.pdf").toString("base64");

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

# Encode and send in one command
curl -X POST "https://api.matil.ai/v3/deployments/{deployment_id}" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d "{
    \"documents\": [{
      \"type\": \"base64\",
      \"content\": \"$(base64 -i invoice.pdf)\",
      \"mime_type\": \"application/pdf\",
      \"filename\": \"invoice.pdf\"
    }]
  }"

byte[] bytes = File.ReadAllBytes("invoice.pdf");
string content = Convert.ToBase64String(bytes);

var document = new {
    type = "base64",
    content = content,
    mime_type = "application/pdf",
    filename = "invoice.pdf"
};

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

byte[] bytes = Files.readAllBytes(Path.of("invoice.pdf"));
String content = Base64.getEncoder().encodeToString(bytes);

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"}
    }
  ]
}

API Reference

Endpoints

URL

Base64

Encoding a file to base64

Text

Multiple documents

Per-document metadata

​URL

​Base64

​Encoding a file to base64

​Text

​Multiple documents

​Per-document metadata

URL

Base64

Encoding a file to base64

Text

Multiple documents

Per-document metadata