CloseBooks — AI Accounting for CPA Firms

Authentication

The CloseBooks API uses API keys to authenticate requests. All API calls must include your API key in the Authorization header as a Bearer token.

You can manage your API keys from the CloseBooks Connect dashboard. Keys are prefixed with sk_live_ for production and sk_test_ for test environments. Test mode data is isolated from production.

Keep your API keys secret. Do not share them in publicly accessible areas such as GitHub, client-side code, or build logs. Rotate keys immediately if you suspect they've been compromised.

Example request

curl

curl -X GET https://api.closebooks.io/v1/companies/cmp_4xT9mK2p/financials \
  -H "Authorization: Bearer sk_live_4xT9ABCDEFGHJKLMNmK2p" \
  -H "Content-Type: application/json"

TypeScript SDK

TypeScript

import CloseBooksClient from '@closebooks/sdk'

const client = new CloseBooksClient({
  apiKey: process.env.CLOSEBOOKS_API_KEY,
})

const financials = await client.companies.getFinancials('cmp_4xT9mK2p', {
  period: '2026-03',
})

HTTP response codes

200 OKRequest succeeded.

201 CreatedResource created successfully.

400 Bad RequestInvalid request parameters.

401 UnauthorizedMissing or invalid API key.

403 ForbiddenInsufficient scope for this operation.

404 Not FoundResource does not exist.

429 Too Many RequestsRate limit exceeded. Retry after the duration in the Retry-After header.

500 Internal Server ErrorSomething went wrong on our side.

Endpoints

The base URL for all API requests is https://api.closebooks.io/v1. All requests and responses are JSON. Dates are ISO 8601 strings in UTC. Monetary values are floating-point numbers in USD.

ℹ️

All endpoints require a company ID path parameter. You can find your company IDs on the CloseBooks dashboard under Settings → Integrations.

GET/v1/companies/{id}/financials

Retrieve aggregated financial metrics for a company for a given accounting period. Returns P&L data, balance sheet highlights, and close status.

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The company identifier (e.g. cmp_4xT9mK2p).

Query Parameters

Parameter	Type	Required	Description
period	string	Optional	Accounting period in YYYY-MM format. Defaults to the most recently closed month.

Request

curl

curl -X GET https://api.closebooks.io/v1/companies/cmp_4xT9mK2p/financials?period=2026-03 \
  -H "Authorization: Bearer sk_live_4xT9ABCDEFGHJKLMNmK2p"

Response

200 OK

{
  "company_id": "cmp_4xT9mK2p",
  "period": "2026-03",
  "revenue": 284500.00,
  "cost_of_goods_sold": 91200.00,
  "gross_profit": 193300.00,
  "gross_margin": 0.679,
  "operating_expenses": 87400.00,
  "ebitda": 105900.00,
  "ebitda_margin": 0.372,
  "net_income": 98200.00,
  "cash_on_hand": 412800.00,
  "accounts_receivable": 67300.00,
  "accounts_payable": 22100.00,
  "close_status": "completed",
  "as_of": "2026-03-31T23:59:59Z"
}

GET/v1/companies/{id}/transactions

List all transactions for a company with filtering, pagination, and cursor-based navigation. Returns up to 100 records per page.

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The company identifier.

Query Parameters

Parameter	Type	Required	Description
start_date	string	Optional	Filter to transactions on or after this date (YYYY-MM-DD).
end_date	string	Optional	Filter to transactions on or before this date (YYYY-MM-DD).
category	string	Optional	Filter by category name (exact match).
account	string	Optional	Filter by account ID.
status	string	Optional	Filter by status: posted \| pending_review \| excluded.
limit	integer	Optional	Number of results per page (1–100, default 20).
cursor	string	Optional	Pagination cursor from previous response.

Request

curl

curl -X GET "https://api.closebooks.io/v1/companies/cmp_4xT9mK2p/transactions?limit=3&start_date=2026-03-01&end_date=2026-03-31" \
  -H "Authorization: Bearer sk_live_4xT9ABCDEFGHJKLMNmK2p"

Response

200 OK

{
  "data": [
    {
      "id": "txn_9kR3pQ7wX2mN",
      "date": "2026-03-31",
      "amount": -14200.00,
      "description": "Stripe Payout",
      "category": "Revenue",
      "account": "acc_operating_checking",
      "status": "posted"
    },
    {
      "id": "txn_2wP8mK4nV9qL",
      "date": "2026-03-28",
      "amount": -4250.00,
      "description": "AWS Infrastructure",
      "category": "Software & Subscriptions",
      "account": "acc_operating_checking",
      "status": "posted"
    },
    {
      "id": "txn_5tN1xB6hQ3rW",
      "date": "2026-03-25",
      "amount": -28000.00,
      "description": "Payroll — March",
      "category": "Payroll",
      "account": "acc_payroll",
      "status": "posted"
    }
  ],
  "pagination": {
    "total": 248,
    "page": 1,
    "limit": 3,
    "next_cursor": "cur_5tN1xB6hQ3rW"
  }
}

POST/v1/companies/{id}/transactions

Create a new transaction. Requires the write:transactions scope. Transactions created via API are marked pending_review until confirmed by a bookkeeper.

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The company identifier.

Body Parameters

Parameter	Type	Required	Description
date	string	Required	Transaction date in YYYY-MM-DD format.
amount	number	Required	Transaction amount in USD. Negative for expenses, positive for income.
description	string	Required	Human-readable description (max 255 characters).
category	string	Optional	Category name. Defaults to Uncategorized.
account	string	Optional	Account ID. Defaults to the company's primary checking account.
memo	string	Optional	Additional notes or invoice reference (max 500 characters).
tags	string[]	Optional	Array of string tags for custom classification.

Request

curl

curl -X POST https://api.closebooks.io/v1/companies/cmp_4xT9mK2p/transactions \
  -H "Authorization: Bearer sk_live_4xT9ABCDEFGHJKLMNmK2p" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-04-05",
    "amount": -4250.00,
    "description": "AWS Infrastructure — March",
    "category": "Software & Subscriptions",
    "account": "acc_operating_checking",
    "memo": "Invoice #INV-2026-0312",
    "tags": ["infrastructure", "recurring"]
  }'

Response

201 Created

{
  "id": "txn_9kR3pQ7wX2mN",
  "company_id": "cmp_4xT9mK2p",
  "date": "2026-04-05",
  "amount": -4250.00,
  "description": "AWS Infrastructure — March",
  "category": "Software & Subscriptions",
  "account": "acc_operating_checking",
  "memo": "Invoice #INV-2026-0312",
  "tags": ["infrastructure", "recurring"],
  "status": "pending_review",
  "created_at": "2026-04-05T14:32:10Z",
  "created_by": "api_key:key_01"
}

GET/v1/companies/{id}/health-score

Retrieve the computed financial health score for a company. Scores are recalculated daily after close. Returns a 0–100 score, letter grade, component breakdown, and benchmark percentile.

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The company identifier.

Request

curl

curl -X GET https://api.closebooks.io/v1/companies/cmp_4xT9mK2p/health-score \
  -H "Authorization: Bearer sk_live_4xT9ABCDEFGHJKLMNmK2p"

Response

200 OK

{
  "company_id": "cmp_4xT9mK2p",
  "score": 82,
  "grade": "B+",
  "computed_at": "2026-04-05T00:00:00Z",
  "components": {
    "cash_runway_months": 14.5,
    "gross_margin": 67.9,
    "burn_rate_trend": "stable",
    "accounts_receivable_days": 28,
    "debt_to_equity": 0.31
  },
  "flags": [
    {
      "type": "warning",
      "message": "A/R days trending up — 28 vs 22 last quarter",
      "severity": "medium"
    }
  ],
  "benchmark_percentile": 71,
  "industry": "SaaS"
}

Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in CloseBooks. Configure webhook endpoints from the Connect dashboard or via the Webhooks API.

Supported events

transaction.createdA new transaction has been imported or created via API.

close.completedA monthly bookkeeping close has been finalized.

exception.flaggedRadar has flagged an anomaly or exception requiring review.

document.receivedA new document has been uploaded to Vault.

Payload structure

Webhook payload

{
  "id": "evt_4kT9pQ7wX2mN",
  "type": "transaction.created",
  "created": "2026-04-05T14:32:10Z",
  "data": {
    "object": {
      "id": "txn_9kR3pQ7wX2mN",
      "company_id": "cmp_4xT9mK2p",
      "date": "2026-04-05",
      "amount": -4250.00,
      "description": "AWS Infrastructure — March",
      "category": "Software & Subscriptions",
      "status": "pending_review"
    }
  },
  "livemode": true,
  "api_version": "2026-01-01"
}

Verifying signatures

CloseBooks signs all webhook payloads with your webhook secret using HMAC-SHA256. The signature is in the X-CloseBooks-Signature header. Always verify this before processing events.

Verification

import crypto from 'crypto'

export function verifyWebhook(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSig)
  )
}

SDKs

Official SDKs are available for TypeScript/JavaScript and Python. They wrap all endpoints with full type safety and handle authentication, retries, and pagination automatically.

TypeScript / Node.js

npm

npm install @closebooks/sdk

Usage

import CloseBooksClient from '@closebooks/sdk'

const cb = new CloseBooksClient({ apiKey: process.env.CLOSEBOOKS_API_KEY })

// Get financials for a company
const financials = await cb.companies.getFinancials('cmp_4xT9mK2p')
console.log(financials.gross_margin) // 0.679

// List transactions with filters
const txns = await cb.companies.listTransactions('cmp_4xT9mK2p', {
  startDate: '2026-03-01',
  endDate:   '2026-03-31',
  category:  'Software & Subscriptions',
  limit:     50,
})

// Compute health score
const health = await cb.companies.getHealthScore('cmp_4xT9mK2p')
console.log(`Score: ${health.score} (${health.grade})`)

Python

pip

pip install closebooks-python

Usage

import closebooks

cb = closebooks.Client(api_key=os.environ["CLOSEBOOKS_API_KEY"])

# Get financials
financials = cb.companies.get_financials("cmp_4xT9mK2p", period="2026-03")
print(financials["gross_margin"])  # 0.679

# List transactions
txns = cb.companies.list_transactions(
    "cmp_4xT9mK2p",
    start_date="2026-03-01",
    end_date="2026-03-31",
)

Rate Limits

API requests are rate-limited per API key. Limits reset at midnight UTC daily.

Free1,000 requests/dayBurst: 10 req/sec

Growth10,000 requests/dayBurst: 50 req/sec

EnterpriseUnlimitedBurst: Custom

When you exceed the rate limit, you receive a 429 Too Many Requests response. The Retry-After header will indicate how many seconds to wait before retrying.

Changelog

v1.42026-04-01

•Added benchmark_percentile field to /health-score response.
•POST /transactions now accepts tags array.
•Improved latency for GET /financials by 40%.

v1.32026-02-15

•Added document.received webhook event.
•GET /transactions now supports cursor pagination.
•Deprecated offset-based pagination (removed in v1.4).

v1.22026-01-01

•Initial public release of CloseBooks Connect API.
•Available endpoints: /financials, /transactions, /health-score.
•Webhook support for transaction.created and close.completed.

Ready to start building?

Get your API key for free and make your first call in minutes.

Get API Key — Free View Pricing