> ## 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.

# Manage your client list

> Listing, filtering, creating, updating, and deleting clients

Clients are the scope every invoice and estimate hangs off. This guide covers the four operations you'll actually use day to day.

## List and filter clients

```bash theme={null}
curl "https://app.billbooks.com/api/public-api/v1/clients?filter[status]=active&filter[q]=acme" \
  -H "Authorization: Bearer bb_live_your_key_here"
```

Two filters are available:

* `filter[status]`: passed straight through to Billbooks' own client model, values like `active`, `inactive`, or `overdue` are accepted, but the API doesn't independently validate the value against a fixed list.
* `filter[q]`: free-text search across name, city, phone, and country.

## Get a single client

```bash theme={null}
curl "https://app.billbooks.com/api/public-api/v1/clients?id=4821" \
  -H "Authorization: Bearer bb_live_your_key_here"
```

Omit `id` (or pass `0`) and you get the paginated list above. Pass a positive `id` and you get that one client. Ask for a client that belongs to a different organization than your key's and you get `404`, identical to asking for one that doesn't exist at all, see [Errors](/errors) for why that's deliberate.

## 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.",
    "contact_name": "Jordan Lee",
    "contact_email": "jordan@acmedesign.example",
    "email": "billing@acmedesign.example",
    "city": "Austin",
    "country_id": 233
  }'
```

`currency` and `language` both default to your organization's own settings if you leave them out, you only need to set them for a client who bills in something different.

## Update a client

```bash theme={null}
curl -X PUT https://app.billbooks.com/api/public-api/v1/clients \
  -H "Authorization: Bearer bb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 4821,
    "contact_phone": "+1-512-555-0142"
  }'
```

Updates are a genuine partial patch, only the fields you submit get changed. One detail worth knowing: `contact_name`, `contact_email`, and `contact_phone` are treated as a group. If you submit any one of the three, the primary contact record is updated using whatever you sent for those present and the existing values for the ones you left out, it isn't three independent fields under the hood.

`status` is update-only (there's no such field on create): truthy marks the client active, falsy marks it inactive.

## Delete a client

```bash theme={null}
curl -X DELETE "https://app.billbooks.com/api/public-api/v1/clients?id=4821" \
  -H "Authorization: Bearer bb_live_your_key_here"
```

<Warning>
  Deletion is a hard delete, there's no undo. It's blocked with `409 Conflict` if the client has any recorded invoice or estimate, but if the client has never been billed, this removes them (and their contact rows) permanently.
</Warning>

## What's next

* [Create and send an invoice](/guides/create-and-send-an-invoice) once you have a client to bill
* [Create and manage estimates](/guides/create-and-manage-estimates) for pre-invoice quotes