> ## Documentation Index
> Fetch the complete documentation index at: https://docs.billbooks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first API call: create a client, then send them an invoice

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

<Note>
  You'll need an API key first. See [Authentication](/authentication) if you don't have one yet.
</Note>

## 1. Create a client

```bash theme={null}
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": "billing@acmedesign.example"
  }'
```

Every successful response has the same shape:

```json theme={null}
{
  "success": true,
  "data": {
    "id": 4821,
    "name": "Acme Design Co.",
    "email": "billing@acmedesign.example",
    "status": "active"
  }
}
```

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

## 2. Create an invoice for that client

```bash theme={null}
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](/guides/manage-your-client-list) for updating, filtering, and paginating clients
* [Build your item catalog](/guides/build-your-item-catalog) so you can reference `item_id` instead of typing out descriptions every time
* [Rate Limits](/rate-limits) before you script anything that fires many requests in a loop