Quickstart

This walks through the smallest real workflow the API supports: adding a client, then creating and sending an invoice to them.

You’ll need an API key first. See Authentication if you don’t have one yet.

1. Create a client

curl -X POST https://app.billbooks.com/api/public-api/v1/clients \
  -H "Authorization: Bearer bb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Design Co.",
    "email": "[email protected]"
  }'

Every successful response has the same shape:

{
  "success": true,
  "data": {
    "id": 4821,
    "name": "Acme Design Co.",
    "email": "[email protected]",
    "status": "active"
  }
}

Note the id, you’ll need it for the next step.

2. Create an invoice for that client

curl -X POST https://app.billbooks.com/api/public-api/v1/invoices \
  -H "Authorization: Bearer bb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 4821,
    "date": "2026-08-18",
    "no": "INV-1042",
    "status": "sent",
    "items": [
      {
        "description": "Homepage redesign, phase 1",
        "qty": 1,
        "rate": 1500
      }
    ]
  }'

A few things worth knowing about that request:

no is your invoice number, it’s on you to keep it unique per organization. Reuse an existing one and you’ll get a 409 Conflict.
Each line item needs either an item_id (from your item catalog) or a plain description, at least one of the two.
qty must be greater than 0, rate must be 0 or more.
Setting "status": "sent" sends the invoice immediately. Use "draft" (the default if you omit status) to create it without sending.

What’s next

Manage your client list for updating, filtering, and paginating clients
Build your item catalog so you can reference item_id instead of typing out descriptions every time
Rate Limits before you script anything that fires many requests in a loop

Get Started

How-to guides

1. Create a client

2. Create an invoice for that client

What’s next

​1. Create a client

​2. Create an invoice for that client

​What’s next

1. Create a client

2. Create an invoice for that client

What’s next