👨‍💻 Public API

API Base

All the API endpoints described in this article are relative to the base URL: https://api.airparser.com.

Authentication

To access the API, you will need the API key that you will find in your account:

This API key should be included in the X-API-Key HTTP header.

Unauthenticated responses will return in a HTTP 401 Unauthorized code.

Here's a request example using cURL:

curl -X GET https://api.airparser.com/inboxes/ -H "X-API-Key: <YOUR_API_KEY>"

Documents

Upload a document

API Endpont: POST /inboxes/<inbox_id>/upload

Parameters:

file: Binary file object
meta (object): Payload document data (optional)

If needed, you can provide some payload data in the meta field, which will be included in the parsed JSON as the __meta__ field. This can be helpful for linking the document with your external database, for example.

Supported formats: EML, PDF, HTML, TXT, MD and more (contact us if we've missed something).

Max. file size: 20MB

Returns: Document ID

Your Inbox ID can be found in the browser location bar:

Code samples

CURL:

curl \
-X POST \
https://api.airparser.com/inboxes/<INBOX_ID>/upload \
-F 'file=@./receipt.pdf' \
-H "X-API-Key: <YOUR_API_KEY>"

PHP:

<?php
 
$apikey = '<API_KEY>';
$url = 'https://api.airparser.com/inboxes/<INBOX_ID>/upload';
$filepath = './invoice.pdf';
 
$curl = curl_init();
 
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'X-API-Key: ' . $apikey
));
curl_setopt($curl, CURLOPT_POST, true);
 
$meta = array(
  'foo' => 'bar',
  'my_id' => 42,
);
$metaJson = json_encode($meta);
 
curl_setopt($curl, CURLOPT_POSTFIELDS, array(
    'file' => curl_file_create($filepath, 'application/pdf', 'invoice.pdf'),
    'meta' => $metaJson
));
 
$response = curl_exec($curl);
curl_close($curl);
 
echo $response;

Python:

import requests
 
header = {"X-API-Key": "<API_KEY>"}
url = "https://api.airparser.com/inboxes/<INBOX_ID>/upload"
 
with open('invoice.pdf', 'rb') as f:
    files = {'file': f}
    with requests.request("POST", url, files=files, headers=header) as response:
        print('response: ', response)

Node.js:

const fetch = require("node-fetch");
const fs = require("fs");
const FormData = require("form-data");
 
const APIKEY = "<YOUR_API_KEY>";
const inboxId = "<INBOX_ID>";
const filePath = "/path/to/your/file.pdf";
// Optional: Pass custom payload which will be avalable in the parsed data.
const metadata = { foo: "bar" };
 
async function importFile(inboxId, filePath, metadata) {
  const url = `https://api.airparser.com/inboxes/${inboxId}/upload`;
 
  const fileStream = fs.createReadStream(filePath);
 
  const form = new FormData();
  form.append("file", fileStream);
  form.append("meta", JSON.stringify(metadata));
 
  try {
    const response = await fetch(url, {
      method: "POST",
      body: form,
      headers: {
        "X-API-Key": APIKEY,
      },
    });
 
    const docId = await response.json();
    console.log(response.status);
    console.log("Document id:", docId);
  } catch (e) {
    console.error("Error:", e.message);
  }
}
 
importFile(inboxId, filePath, metadata);

Get a document

GET /docs/<document_id>/extended

This endpoint allows to retrieve the parsed data as JSON but we highly recommend using webhooks for real-time data sending instead.

List documents

GET /inboxes/<inbox_id>/docs

Optional parameters:

page (number)
from (string): 'from' date. Format: YYYY-MM-DD
to (string): 'to' date. Format: YYYY-MM-DD
q (string): search query
statuses (array of strings): Document statuses. Accepted values: importing, parsed, fail, new, quota, parsing, exception.

Inboxes

List inboxes

GET /inboxes

Delete an inbox

DELETE /inboxes/<inbox_id>

Extraction Schema

Create/edit an extraction schema

Updates or creates an extraction schema for a specific inbox. The schema defines how documents should be parsed and what data should be extracted.

POST /inboxes/<inbox_id>/schema

Request body:

fields: Array of field definitions

Response:

Returns boolean - true if the schema was successfully updated, throws an error otherwise.

Field Types

The schema supports four types of fields:

1. Scalar Field

Used for single values like strings, numbers, or booleans.

{
  "type": "scalar",
  "data": {
    "name": "total_amount",
    "description": "The total amount from the invoice",
    "type": "decimal",
    "default_value": "0.00"
  }
}

Scalar field types:

`string`: Text values
`integer`: Whole numbers
`decimal`: Decimal numbers
`boolean`: True/false values

2. List Field

Used for arrays of objects with consistent structure.

{
  "type": "list",
  "data": {
    "name": "line_items",
    "description": "List of items in the invoice",
    "attributes": [
      {
        "name": "product_name",
        "description": "Name of the product",
        "type": "string",
        "default_value": ""
      },
      {
        "name": "quantity",
        "description": "Quantity ordered",
        "type": "integer",
        "default_value": "0"
      }
    ]
  }
}

3. Object Field

Similar to list but for single objects.

{
  "type": "object",
  "data": {
    "name": "shipping_address",
    "description": "Shipping address details",
    "attributes": [
      {
        "name": "street",
        "description": "Street address",
        "type": "string",
        "default_value": ""
      },
      {
        "name": "city",
        "description": "City name",
        "type": "string",
        "default_value": ""
      }
    ]
  }
}

4. Enum Field

Used for fields with a predefined set of possible values.

{
  "type": "enum",
  "data": {
    "name": "status",
    "description": "Order status",
    "values": ["pending", "processing", "shipped", "delivered"]
  }
}

Complete Example

{
  "fields": [
    {
      "type": "scalar",
      "data": {
        "name": "invoice_number",
        "description": "Invoice reference number",
        "type": "string",
        "default_value": ""
      }
    },
    {
      "type": "list",
      "data": {
        "name": "items",
        "description": "List of items in the invoice",
        "attributes": [
          {
            "name": "description",
            "description": "Item description",
            "type": "string",
            "default_value": ""
          },
          {
            "name": "amount",
            "description": "Item amount",
            "type": "decimal",
            "default_value": "0.00"
          }
        ]
      }
    },
    {
      "type": "enum",
      "data": {
        "name": "payment_status",
        "description": "Current payment status",
        "values": ["paid", "pending", "overdue"]
      }
    }
  ]
}

Validation Rules

Field names must be 1-100 characters long and contain only lowercase letters, numbers, and underscores
Field names must be unique within the schema
Descriptions must not exceed 3000 characters
Default values must not exceed 400 characters
Enum values must be unique and 1-100 characters long
List and Object attributes must have unique names within their scope
All text fields are automatically trimmed

Error Responses

The API will return an error if:

The fields array is empty
Any field has an invalid type
Any field name is invalid or duplicate
Any description or default value exceeds length limits
Any enum has duplicate values or invalid value lengths

Clone an extraction schema between inboxes

POST /inboxes/<inbox_id>/schema-clone

Parameters:

inbox_id (path parameter): The source inbox from which the extraction schema will be cloned.

Request body:

destination_inbox_id: The target inbox where the extraction schema will be copied.

Response:

Returns: boolean – true if the schema was successfully cloned, otherwise false.