Getting started

Create an API token and make your first Backfill API call.

The Backfill HTTP API lives on the API host under /v1:

https://api.backfill.io/v1

Every endpoint requires a bearer token. This page takes you from zero to a successful request.

1. Create an API token

Tokens are created in the Backfill dashboard, not via the API:

1. Open Settings → API keys (admin role required).
2. Create a key and select its scopes — finance:read is enough for this walkthrough; see Authentication for the full scope table.
3. Copy the token now. It is prefixed bf_live_ and stored hashed. The token is not recoverable after creation.

Note: A token created in one company can only read and write that company’s data.

2. Make your first request

curl https://api.backfill.io/v1/accounts \
  -H "Authorization: Bearer bf_live_..."

A successful response:

{
  "object": "list",
  "data": [
    {
      "id": "0d1f6c9a-…",
      "object": "account",
      "data": {
        "name": "Cash",
        "account_type": "asset",
        "account_code": "1000"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total_count": 42,
    "has_more": false
  }
}

Every record has a Backfill-assigned UUID id, an object type, and the resource fields under data. Lists carry pagination. See Pagination for paging, sorting, and filter conventions.

3. Create a record

Mutating POST requests accept an Idempotency-Key header so a retried request never creates a duplicate:

curl https://api.backfill.io/v1/customers \
  -H "Authorization: Bearer bf_live_..." \
  -H "Idempotency-Key: cust-import-0001" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Inc."}'

This needs a token with finance:write. The response is the created record in the same {id, object, data} envelope.

When a request fails, the error envelope tells you why — a machine-readable code, a human message, and a request_id to quote in support requests. See Errors for the full code catalog and retry guidance.

4. Reference accounts and related records by ID

Related records are always referenced by their Backfill UUID (customer_id, account_id, etc).

In particular, general ledger accounts must be referenced by account_id — the human-readable account_code is display-only metadata and optional on accounts, so lookups by code are not supported.

Next steps

• Browse the full API reference — every operation with request and response schemas and curl examples (openapi.json for the raw spec).
• Skim the per-resource pages under Resources for field semantics.
• Read Authentication for scopes, token lifecycle, and idempotency details, and Versioning for the compatibility policy.
• Documents that post to the ledger (invoices, expenses, payments, …) expose lifecycle actions — submit, approve, void, mark_paid — alongside CRUD; they are listed per resource in the reference.