CentraBills API

Quick start

1. Get an API key. In CentraBills, go to Settings → API and create a key. Only a Super Admin of the organisation can issue keys. The key is shown once — store it somewhere safe.
2. Upload a document. Send a POST /v1/documents request with your file. You'll get a 202 Accepted response containing the document's id.
3. Poll for results. Call GET /v1/documents/{id} until status is no longer pending. Once it is extracted, the response includes the full extraction object.

Authentication

Every request must carry your API key as a bearer token:

Authorization: Bearer YOUR_API_KEY

API keys have the following properties:

• Organisation-scoped. A key belongs to exactly one organisation; documents you upload land in that organisation's account, and you can only read that organisation's documents.
• Write-only scope. Keys carry the documents:write ability, covering document upload and status polling.
• 18-month expiry. Keys expire 18 months after they are issued. Expired keys receive 401 Unauthorized.
• Revocable. A Super Admin can revoke a key at any time from Settings → API. Revocation takes effect immediately.

Upload a document

POST https://api.centrabills.com/v1/documents

Uploads a single invoice or receipt as multipart/form-data and queues it for extraction. Returns 202 Accepted — extraction happens asynchronously, so poll the returned document to get results.

Parameters

Example request

curl

curl -X POST https://api.centrabills.com/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -F "[email protected]" \
  -F "company=Acme Ltd" \
  -F "reference=INV-2041"

PHP (Guzzle)

$client = new \GuzzleHttp\Client();

$response = $client->post('https://api.centrabills.com/v1/documents', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
    'multipart' => [
        ['name' => 'file', 'contents' => fopen('invoice.pdf', 'r'), 'filename' => 'invoice.pdf'],
        ['name' => 'company', 'contents' => 'Acme Ltd'],
        ['name' => 'reference', 'contents' => 'INV-2041'],
    ],
]);

$document = json_decode($response->getBody(), true)['data'];

JavaScript (fetch)

const form = new FormData();
form.append('file', fileInput.files[0]);
form.append('company', 'Acme Ltd');
form.append('reference', 'INV-2041');

const response = await fetch('https://api.centrabills.com/v1/documents', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Accept': 'application/json',
    },
    body: form,
});

const { data } = await response.json();

Example response 202 Accepted

{
    "data": {
        "id": 123,
        "status": "pending",
        "filename": "invoice.pdf",
        "received_at": "2026-07-03T09:30:00+00:00",
        "links": {
            "self": "https://api.centrabills.com/v1/documents/123"
        }
    }
}

Retrieve a document

GET https://api.centrabills.com/v1/documents/{id}

Returns a document's current status and, once extraction has completed successfully, its extracted data. Documents are only visible to the organisation the API key belongs to — unknown ids and documents belonging to other organisations both return 404 Not Found.

Parameters

Example request

curl

curl https://api.centrabills.com/v1/documents/123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

PHP (Guzzle)

$client = new \GuzzleHttp\Client();

$response = $client->get('https://api.centrabills.com/v1/documents/123', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
]);

$document = json_decode($response->getBody(), true)['data'];

JavaScript (fetch)

const response = await fetch('https://api.centrabills.com/v1/documents/123', {
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Accept': 'application/json',
    },
});

const { data } = await response.json();

Example response 200 OK, extracted

{
    "data": {
        "id": 123,
        "status": "extracted",
        "filename": "invoice.pdf",
        "received_at": "2026-07-03T09:30:00+00:00",
        "extraction": {
            "document_type": "invoice",
            "company_name": "Acme Ltd",
            "currency": "GBP",
            "subtotal": "100.00",
            "tax_amount": "20.00",
            "shipping": "5.00",
            "total": "125.00",
            "invoice_due_date": "2026-08-02",
            "extracted_at": "2026-07-03T09:31:12+00:00"
        },
        "links": {
            "self": "https://api.centrabills.com/v1/documents/123"
        }
    }
}

The extraction key is entirely absent until the document's status is extracted — while pending (and for unsupported or failed documents) the response contains only the top-level fields.

Status lifecycle

Every document starts as pending and settles into exactly one terminal state:

pending → extracted | unsupported | failed

Most documents are extracted within a couple of minutes. A polling interval of 15–30 seconds with a sensible timeout works well.

The extraction object

Present only when status is extracted. Monetary values are decimal strings (for example "100.00"), timestamps are ISO 8601, and dates are YYYY-MM-DD. Any field the extractor could not determine is null.

Errors

Errors are returned as JSON with a human-readable message. Validation errors additionally include an errors object keyed by field name.

Example error 422 Unprocessable Content

{
    "message": "The file field is required.",
    "errors": {
        "file": [
            "The file field is required."
        ]
    }
}

Rate limits

Each API key may make up to 60 requests per minute. Every response includes the standard rate-limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42

When the limit is exceeded, the API responds with 429 Too Many Requests, a JSON message, and a Retry-After header telling you how many seconds to wait before retrying.