Getting started

From nothing to your first API call against real books in about ten minutes.

Pick the right credential

Both are sent the same way, Authorization: Bearer <token>, to the same API. Everything below works with either; this guide follows the OAuth path because that is the one with steps.

1. Create a developer account

Sign up — it is free, and the account comes with a business of its own. That business is your test business: connect your app to it while you build, so you never need a customer's data to develop.

2. Set up the test business

Give it a chart of accounts by finishing the short setup wizard (pick any industry template). Then add some sample data — by hand in the app, or with the API itself once you have a token (step 5):

export HFB=https://hasslefreebooks.com/api/v1   AUTH="Authorization: Bearer $ACCESS_TOKEN"   JSON="Content-Type: application/json"

# a customer and a vendor bill
curl -s -X POST $HFB/contacts -H "$AUTH" -H "$JSON" \
     -d '{"display_name":"Sample Customer","type":"customer","email":"ap@customer.example"}'      # -> data.contact.id
curl -s -X POST $HFB/bills -H "$AUTH" -H "$JSON" \
     -d '{"vendor_name":"Sample Supplier","amount":"420.00","bill_date":"2026-10-01","due_date":"2026-10-31"}'

# an invoice to that customer, posted to the ledger
curl -s -X POST $HFB/invoices -H "$AUTH" -H "$JSON" -d '{"contact_id":CONTACT_ID,"invoice_date":"2026-10-01",
     "due_date":"2026-10-31","subtotal":"300.00","total":"300.00",
     "lines":[{"description":"Consulting","quantity":2,"unit_price":150}]}'                     # -> data.invoice.id
curl -s -X POST $HFB/invoices/INVOICE_ID/finalize -H "$AUTH"

3. Register an app

In My apps › Register an app give it a name, choose where it runs, add a redirect URI (for local work, http://localhost:3000/callback is fine) and pick scopes. You get a client ID (hfbc_…) and, for a server app, a client secret (hfbs_…, shown once). The app is live immediately.

4. Connect your test business

On the app's page, Try it builds a working authorization link — with state and a PKCE pair — and the matching token request. Open the link, choose your test business, press Allow, and you land on your redirect URI with ?code=…&state=…&iss=…. Your app does the same thing in code; Authentication shows it step by step.

5. Exchange the code and call the API

curl -s https://hasslefreebooks.com/oauth/token -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code -d code="$CODE" \
  -d redirect_uri=http://localhost:3000/callback -d code_verifier="$VERIFIER"

{"access_token":"hfbat_…","token_type":"Bearer","expires_in":3600,"refresh_token":"hfbrt_…",
 "scope":"read write","entity_id":42,"entity_name":"My Test Business"}

curl -s https://hasslefreebooks.com/api/v1/me       -H "Authorization: Bearer $ACCESS_TOKEN"
curl -s https://hasslefreebooks.com/api/v1/invoices -H "Authorization: Bearer $ACCESS_TOKEN"

Every response has the same envelope:

{"ok": true,  "request_id": "f4d4ad9f…", "data": { … }, "meta": {"timestamp": "2026-10-30T12:00:00+00:00"}}
{"ok": false, "request_id": "f4d4ad9f…", "error": {"code": "VALIDATION_ERROR", "message": "…", "details": {}}, "meta": { … }}

Next

• Use an SDK — PHP, JavaScript/TypeScript and Python, with token refresh and webhook verification built in.
• Browse every endpoint in the API reference (OpenAPI 3: /api/v1/openapi).
• Get told when things happen: Webhooks.
• Before real customers connect: Going live.