Your first call in five minutes.

1. Get a key.

In the app: More → API keys → Create a key. Only an owner or admin can create one. The key is shown once — store it in your secret manager before you leave the screen.

A key is pinned to one organisation's books and carries its own role, chosen at creation and never above accountant. Its effective authority on any request is the lesser of that role and its creator's current role, so demoting or removing the creator narrows or ends the key immediately. Every key expires — a year at the longest — and there is no non-expiring option.

To replace a key without downtime, use Rotate. It mints the replacement while the original still works, so whatever holds the old key keeps running; revoke the old one once its last-used time shows the switch has happened.

2. Build against a sandbox.

Sandbox books are a separate, empty organisation with their own ledger — created from More → API keys → Create sandbox books. They are free and do not use a seat.

Keys minted in a sandbox begin smly_test_; keys on real books begin smly_live_. The mode is part of the credential, so you can tell at a glance which books a key in a config file points at. Presenting a test key against live books fails authentication outright — the separation is enforced before any request reaches the ledger, not by remembering to check.

Two things behave differently in a sandbox, and both are deliberate: invoice emails are recorded but never sent, and bank connections are refused. Everything else — posting, numbering, reports, the change feed — is the same code path as production. There is no way to promote sandbox data into real books; when you are ready, create the real records through the API.

3. Authentication.

Send the key in the Authorization header with the Token scheme — not Bearer, which is reserved for the apps' own session tokens.

Authorization: Token smly_live_k3J9x2Qw8vLpR5tYnB7c…

A wrong, revoked or expired key answers 401 in the standard error envelope, so the first failure you ever see is recognisable:

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid token.",
    "detail": {}
  }
}

A valid key on an endpoint outside the published surface is refused with the code not_part_of_public_api — everything a key may call is in the reference, and nothing else works.

4. First read: the chart of accounts.

Every books integration starts by learning the account structure, and it works on a brand-new trial org because the chart is seeded at signup.

curl https://app.summely.com/api/v1/accounts \
  -H "Authorization: Token smly_live_k3J9x2Qw…"

{
  "next": "https://app.summely.com/api/v1/accounts?cursor=cD0xMTAw",
  "previous": null,
  "results": [
    {
      "id": "8b1e5c1e-4b7a-4f4e-9d2a-1c2b3d4e5f60",
      "number": "1100",
      "name": "Accounts Receivable",
      "type": "asset",
      "detail_type": "accounts_receivable",
      "currency": "USD",
      "is_active": true,
      "balance": "0.0000",
      "version": 1
    }
  ]
}

Lists are cursor-paginated, 50 rows at a time: follow next until it is null. Note the shape of balance — every amount in every response is a decimal string, at the ledger's four-decimal storage scale.

5. First write: a customer.

The Idempotency-Key header is a habit worth forming on your very first write, not an appendix. If the connection drops and you resend with the same key within 24 hours, the server replays the stored response instead of creating a second record.

curl -X POST https://app.summely.com/api/v1/customers \
  -H "Authorization: Token smly_live_k3J9x2Qw…" \
  -H "Idempotency-Key: 018f3a52-create-fern-frond" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Fern & Frond Landscaping",
    "email": "accounts@fernfrond.example",
    "payment_terms": "net_30"
  }'

{
  "id": "3f9d2c74-9d2a-4c1e-8f60-b21c7a4e5d10",
  "display_name": "Fern & Frond Landscaping",
  "email": "accounts@fernfrond.example",
  "payment_terms": "net_30",
  "balance": "0.0000",
  "open_invoice_count": 0,
  "version": 1
}

6. Where next.

The worked flow shows the calls composing into books: customer, invoice, payment, and the balanced ledger entries they produce. To explore live against your own trial org, the interactive reference lets you call every endpoint from the browser — that is the place for trying; the full reference is the place for reading.