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

API Endpoints

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.

List inboxes

GET /inboxes

Delete an inbox

DELETE /inboxes/<inbox_id>