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