FinzBooksDevelopers
Sign in

Quickstart

Mint a token, point your favourite HTTP client at /api/public/v1, make your first call. Five minutes end-to-end.

1. Mint a token

Go to Console → API Tokens and click New token. Pick a scope preset (“Full access” is fine for testing) and copy the raw value — the server only stores its hash, so this is the only chance to copy it.

For partner apps that need to act on behalf of other users, use the OAuth 2.0 flow instead.

2. Make your first call

Confirm the token works by calling GET /whoami — it echoes back the org, user, and scopes the server resolved.

curl -X GET 'http://localhost:8000/api/public/v1/whoami' \
  -H 'Authorization: Bearer aibk_pat_…' \
  -H 'Content-Type: application/json'

You should see:

{
  "code": 0,
  "message": "success",
  "token": {
    "token_id": "5a9f1c…",
    "org_id": "org_abc",
    "user_id": "usr_xyz",
    "scopes": ["AIBooks.fullaccess.all"],
    "tier": "DEFAULT"
  }
}

3. Try a real resource

List your invoices:

curl -X GET 'http://localhost:8000/api/public/v1/invoices?per_page=10' \
  -H 'Authorization: Bearer aibk_pat_…'

Create a contact:

curl -X POST 'http://localhost:8000/api/public/v1/contacts' \
  -H 'Authorization: Bearer aibk_pat_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact_name": "Acme Corp",
    "gst_treatment": "REGISTERED",
    "gst_no": "27AABCC1234D1Z5"
  }'

4. Discover invoice number series (before posting one)

Orgs can run multiple invoice series per branch (domestic / export / RCM, …). Before creating an invoice, list what's configured so you can pick a series_name:

curl -X GET 'http://localhost:8000/api/public/v1/invoices/series' \
  -H 'Authorization: Bearer aibk_pat_…'

# Returns:
# {
#   "series": [
#     { "seriesName": "default", "label": "Default", "prefix": "INV-", "isDefault": true,  "periodId": "..." },
#     { "seriesName": "export",  "label": "Export",  "prefix": "EXP-", "isDefault": false, "periodId": "..." }
#   ],
#   "branchId": "branch_abc"
# }

Then pass the chosen seriesName when you create the invoice — the API auto-generates the next number from that sequence. Full rules (custom-number override, branch scoping) live in the Invoices reference.

Next steps

  • Browse every endpoint in the reference.
  • Set up webhooks to receive real-time event notifications.
  • Read about idempotency before retrying failed POSTs.