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
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
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 for why that’s deliberate.
Create a client
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
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
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.
What’s next
