1. Overview
  2. Public API
  3. 👨‍💻 Public API

👨‍💻 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.

Was this article helpful?