Back to Guides

API Quickstart

Build custom integrations with AccountsOS

RESTful API

Standard REST endpoints with JSON responses

API Key Auth

Simple Bearer token authentication

Rate Limited

1000 requests per hour per key

Authentication

Getting Your API Key

  1. Log in to your AccountsOS dashboard
  2. Navigate to Settings → API
  3. Click Generate API Key
  4. Copy and securely store your key

Keep your API key secret

Never expose your API key in client-side code, public repositories, or shared documents. Regenerate immediately if compromised.

Using Your API Key

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Example Requests

curlList recent transactions
curl -X GET "https://accounts-os.com/api/transactions?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
JavaScriptUsing fetch API
const response = await fetch('https://accounts-os.com/api/transactions?limit=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data.transactions);
ResponseJSON response format
{
  "transactions": [
    {
      "id": "txn_abc123",
      "date": "2025-01-06",
      "description": "AWS Monthly",
      "amount": -45.99,
      "currency": "GBP",
      "category": {
        "id": "cat_software",
        "name": "Software & Subscriptions"
      },
      "confidence": 0.95,
      "bank_account_id": "ba_main"
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Available Endpoints

GET
/api/transactions

List transactions with optional filters

fromtocategorylimitoffset
GET
/api/transactions/:id

Get a single transaction by ID

PATCH
/api/transactions/:id

Update transaction category or notes

category_idnotes
GET
/api/documents

List uploaded documents

typestatuslimitoffset
POST
/api/documents/upload

Upload a new document

filetype
GET
/api/deadlines

Get upcoming filing deadlines

typedays
GET
/api/reports/profit-loss

Generate P&L report

fromto
GET
/api/reports/balance-sheet

Generate balance sheet

as_of
GET
/api/reports/vat

Generate VAT summary

period
GET
/api/contacts

List contacts (clients/suppliers)

typesearchlimit

Rate Limits

Limits

  • 1,000 requests per hour
  • 100 requests per minute burst
  • 10 MB max request body

Response Headers

X-RateLimit-Limit: 1000

X-RateLimit-Remaining: 998

X-RateLimit-Reset: 1704582000

If you hit rate limits, you'll receive a 429 Too Many Requests response. Wait until the reset time before retrying.

Error Handling

All errors return a JSON response with an error object:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or expired",
    "status": 401
  }
}

Common Error Codes

400bad_requestInvalid parameters
401unauthorizedInvalid API key
403forbiddenAccess denied
404not_foundResource not found
429rate_limitedToo many requests
500server_errorInternal error

Ready to Build?

Get your API key and start building your integration.

Get API KeyView All Guides