API Reference

Base URL

Content Type

Requests that send a body (POST, PATCH) must include:

Responses are always JSON.

Idempotency

Send an Idempotency-Key header (up to 255 characters) on any POST, PATCH, or PUT. Use a fresh UUID per logical operation and reuse it on retries.

• A replayed key returns the first response, status and body, with the header Idempotent-Replayed: true. Error responses are replayed too.
• Reusing a key while the first request is still running returns 409. Retry after a moment.
• Reusing a key with a different method or path returns 422.
• Keys are scoped to the authorizing user, not to the company, so keep them unique across every company you serve. They expire after 24 hours.

Errors

The API uses standard HTTP status codes. Errors include a JSON body with details.

Guard failures (auth, locked periods, upstream errors) use one envelope; a few older responses carry only error, so read that field first. error and message carry the same sentence, error_code is stable for branching, and error_data carries structured detail when there is any.

{
  "error": "Banking is closed for Mar 2026.",
  "message": "Banking is closed for Mar 2026.",
  "error_code": "period_locked",
  "error_data": { "lock_date": "2026-03-31" }
}

Validation failures (422) on expenses and products use the envelope above with error_code: "validation_error" and a field-keyed errors map. Invoice create, update, void, and record payment predate it and return a bare errors array of sentences; send and remind return the single-sentence error form.

{
  "errors": [
    "Customer can't be blank",
    "At least one line item is required"
  ]
}

Pagination

Invoices, bills, expenses, and products accept page (default 1) and per_page (1 to 200, default 50) and return a pagination object next to the results.

GET /api/v1/invoices?page=2&per_page=100

{
  "invoices": [ ... ],
  "pagination": {
    "page": 2,
    "per_page": 100,
    "total_count": 340,
    "total_pages": 4
  }
}

Dimensions returns the full set in one response. Invoices and bills still honor the older limit parameter (1 to 50, default 25) when neither page nor per_page is sent; new integrations should not rely on it.

Rate Limiting