Customer cards. Reads work while the account is dormant.
Search#
GET /api/billing/v1/customers?q=לוי
X-Api-Key: bk_…q is a substring match over name, email and ח.פ./ת.ז. Without q you get every card. Active customers come first, then alphabetical by name.
{
"customers": [
{ "id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f", "name": "נועה לוי", "unique_id": "301234567",
"email": "[email protected]", "phone": null, "cell": null, "address": null, "city": "חיפה", "zip": null,
"active": 1, "created_at": "2026-09-29T09:00:00.000Z" }
]
}Rows are database rows with snake_case names and carry every column of the customer card (payment terms, bank details, retainer settings, internal note and so on), not only the fields shown above. Treat the response as sensitive.
Create#
POST /api/billing/v1/customers
X-Api-Key: bk_…
Content-Type: application/json{ "name": "נועה לוי", "email": "[email protected]", "uniqueId": "301234567", "city": "חיפה" }Response 200: {"id": "9c1d2e3f-…"}.
Accepted fields: name (required), email, phone, cell, uniqueId, address, city, zip. The Invoice4U field names Name, Email, Phone, Cell, UniqueID, Address, City, Zip are accepted as aliases (Invoice4U CreateCustomer parity); when both are sent the native name wins. Everything except name is optional and stored as given.
There is no update or delete endpoint; edit cards in the dashboard. Creating a customer does not deduplicate: posting the same person twice creates two cards.
Using a customer on a document#
Pass customerId in document to link the document to the card. The name, ID, email and address printed on the document are the snapshot fields (customerName, customerUniqueId, …) you send with the document, so a later edit of the card never changes an issued document.
Webhooks#
A customer created through this endpoint does not fire customer.created; that event is emitted for cards saved in the dashboard. See webhooks.
Errors#
400 body is not JSON · 401 bad key · 422 {"error":"customer name is required"} (or a write failure) · 429 rate limited. See errors.