👨‍💻 Public API

Postman Collection

You can quickly start testing the Airparser API by importing our Postman collection with the most important API endpoints.

To add it to Postman:

1. Download the JSON collection file from the Attachments section at the end of this article.

2. Open Postman, click File → Import.

3. Select the downloaded JSON file.

4. Set your variables such as api_key, inbox_id, doc_id, etc.

Once imported, you can immediately test the Airparser API endpoints from Postman.

API Base

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

Authentication

To access the API, use the API key available in your account:

Include the API key in the X-API-Key HTTP header.

If the request is not authenticated, the API returns HTTP 401 Unauthorized.

Example:

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

Documents

Parse a document

Airparser supports two upload modes: sync and async.

Use sync mode when you want to wait for parsing and receive the result in the same response.

Use async mode when you only need to upload the document and continue immediately. The document will be processed in the background, and the parsed result can then be retrieved later or delivered through your configured integrations such as webhooks, Zapier, Make, n8n, or Google Sheets.

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

Parse a document - Sync

API endpoint: POST /inboxes/<inbox_id>/upload-sync

Uploads a document, waits for parsing to complete, and returns the extracted data in the same response. The request waits up to about 60 seconds. If parsing takes longer, the response includes parsing_in_progress: true together with the document ID so you can retrieve the result later.

Parameters:

• file: binary file object

• meta (object, optional): custom payload data. It will be included in the parsed JSON as the __meta__ field.

Supported formats include EML, PDF, HTML, TXT, MD, DOCX, XLSX, CSV, JPG, PNG, and BMP.

Max file size: 20MB.

ZIP files are not supported in sync mode.

Returns: parsed document object.

{
  "doc_id": "64abc123def456...",
  "parsing_in_progress": false,
  "status": "parsed",
  "name": "invoice.pdf",
  "content_type": "application/pdf",
  "created_at": "2026-03-10T12:00:00.000Z",
  "processed_at": "2026-03-10T12:00:04.321Z",
  "json": {
    "invoice_number": "INV-001",
    "total": 150,
    "__meta__": { "external_id": 42 }
  }
}

If parsing is still in progress after the timeout:

{
  "doc_id": "64abc123def456...",
  "parsing_in_progress": true,
  "status": "importing",
  "name": null,
  "content_type": null,
  "created_at": null,
  "processed_at": null,
  "json": null
}

The status value in this timeout response depends on the current processing stage and may be importing, new, converting, parsing, or another non-terminal value.

CURL:

curl -X POST https://api.airparser.com/inboxes/<INBOX_ID>/upload-sync \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -F 'file=@./invoice.pdf' \
  -F 'meta={"external_id":42}'

Parse a document - Async

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

Uploads a document and returns immediately with a document ID. Parsing happens in the background.

Parameters:

• file: binary file object

• meta (object, optional): custom payload data. It will be included in the parsed JSON as the __meta__ field.

Supported formats include EML, PDF, HTML, TXT, MD, DOCX, XLSX, CSV, JPG, PNG, and BMP.

Max file size: 20MB.

ZIP files are supported in async mode.

Returns: document ID.

CURL:

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

Get a document

Airparser provides two ways to fetch a processed document.

Get the webhook-style parsed JSON

API endpoint: GET /docs/<document_id>

Returns the parsed document in a compact format similar to the payload delivered through webhooks.

{
  "_id": "67d0d4c4b6b2...",
  "name": "invoice.pdf",
  "content_type": "application/pdf",
  "status": "parsed",
  "created_at": "2026-03-10T12:00:00.000Z",
  "processed_at": "2026-03-10T12:00:04.321Z",
  "filename": "invoice.pdf",
  "credits": 1,
  "json": {
    "invoice_number": "INV-001",
    "total": 150,
    "__meta__": { "external_id": 42 }
  }
}

Get the extended document details

API endpoint: GET /docs/<document_id>/extended

Returns a richer response with additional document details.

Optional query parameter:

• source=parsed: force the response to use the original parsed output instead of post-processed data

Typical response fields include _id, inbox_id, owner_id, name, data_text, format, status, created_at, processed_at, secret, filename, content_type, credits, img_preview, pages, json, prevId, and nextId.

List documents

API endpoint: GET /inboxes/<inbox_id>/docs

Optional parameters:

• page: page number

• per_page: items per page, from 1 to 500, default 25

• from: from date in YYYY-MM-DD format

• to: to date in YYYY-MM-DD format

• q: search query

• status: array of document statuses

Accepted status values include: importing, new, converting, parsing, parsed, fail, fail_pp, skipped, skipped_pp, quota, and exception.

Inboxes

Create an inbox

API endpoint: POST /inboxes/create

Creates a new inbox.

Request body:

{
  "name": "Invoices",
  "llm_engine": "text"
}

Request fields:

• name: inbox name

• llm_engine: parsing engine. Allowed values: text, vision

List inboxes

API endpoint: GET /inboxes

Get one inbox

API endpoint: GET /inboxes/<inbox_id>

Returns the inbox details, including key parsing configuration and the current extraction schema.

Delete an inbox

API endpoint: DELETE /inboxes/<inbox_id>

Extraction Schema

Create or update 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.

API endpoint: POST /inboxes/<inbox_id>/schema

Request body:

• fields: array of field definitions

Response:

• Returns true if the schema was updated successfully

Field types

The schema supports four types of fields.

1. Scalar field

Used for single values such as 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 or false values

2. List field

Used for arrays of objects with consistent structure.

{
  "type": "list",
  "data": {
    "name": "line_items",
    "description": "List of invoice items",
    "attributes": [
      {
        "name": "description",
        "description": "Item description",
        "type": "string",
        "default_value": ""
      },
      {
        "name": "quantity",
        "description": "Quantity",
        "type": "integer",
        "default_value": "0"
      }
    ]
  }
}

3. Object field

Used for a single nested object.

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

Validation rules

• fields must be a non-empty array

• Field names must start with a lowercase letter and may contain only lowercase letters, numbers, and underscores

• Field names must be unique within the schema

• Maximum field name length: 100 characters

• Maximum description length: 3000 characters

• Maximum default value length: 400 characters

• Enum values must be unique and each value must be between 1 and 100 characters

• List and object attributes must have unique names within their scope

• Text values are trimmed automatically

Clone an extraction schema between inboxes

API endpoint: POST /inboxes/<inbox_id>/schema-clone

Request body:

• destination_inbox_id: the target inbox where the extraction schema will be copied

Response:

• Returns true if the schema was successfully cloned, otherwise false