Customers

Credential: a company's API key or OAuth token.

Retrieves all customers for your company, sorted by customer number.

Pass ?search= to find customers by what was typed, the way the Customers list in LedgerBee does: ?search=jens hansen&limit=20. Pass ?customerNumber= for an exact-match lookup of a single customer by its human-readable number (useful when you only know the number shown on an invoice, not the UUID), and ?vatNumber=, ?email= or ?isActive= to narrow by those exactly.

The unfiltered list is cached for 5 seconds; a search or a filter always reads fresh data, so a just-created or just-updated customer is immediately visible through it.

Searching

search is split on spaces, and every word must appear, ignoring upper and lower case, in at least one of the customer's name, customerNumber, vatNumber, email, externalSystemId and phone, or in the name of its customer group. A word matches anywhere in a value, so 5678 finds the VAT number DK12345678, and %, _ and [ match those characters. phone is matched with its spaces and dashes removed, so 12345678 finds the phone number +45 12 34 56 78, and so does 12 34 56 78. Only the first ten different words count. Results keep customer-number order; they are not ranked by how well they match.

A search with at least one word answers one page, as if limit were sent, so a short search on a large customer list cannot return most of it at once. An empty search, or one of only spaces, is no search. A client that searches as the user types should send the search about 250 ms after the last keystroke rather than on every one.

Pagination

The list is returned in full, as an array, unless you send cursor, page or limit. Sending any of them switches the response to a paginated object (data, total, page, limit, totalPages, nextCursor, hasMore); page and limit take their defaults when omitted. A paginated read is never cached.

To walk the whole list, send limit and then pass each response's nextCursor back as cursor, with the same filters, until hasMore is false. Paging by page is deprecated, and page cannot be sent with cursor (400 PAGINATION_CURSOR_WITH_PAGE). A cursor replayed with other filters is refused with 400 PAGINATION_INVALID_CURSOR. From 2026-12-31, a page past the first of a list with more than 10,000 items is refused with 400 PAGINATION_OFFSET_TOO_DEEP.

On this list, a search with at least one word also switches the response to the paginated object.

Required Scope

• customers-read

Credential: a company's API key or OAuth token.

Creates a customer in your company. The response contains the new id and the auto-assigned customerNumber — fetch the full record via GET /v1/customers/{customerId} if you need it.

• customerType defaults to BUSINESS when omitted.
• externalSystemId lets you store your own system's identifier for deduplication. It must be unique within your company — reusing one returns 409 EXTERNAL_SYSTEM_ID_ALREADY_EXISTS. Empty or whitespace-only values are treated as unset.

Required Scope

• customers-write

Credential: a company's API key or OAuth token.

Retrieves a customer by its unique identifier. Returns 404 when the customer does not exist (or belongs to another company).

Required Scope

• customers-read

Credential: a company's API key or OAuth token.

Deletes a customer, following the same rules as deleting one in LedgerBee.

• A customer with no bookings, invoices or subscriptions is deleted, together with its metadata. The response says result: DELETED.
• A customer with any of those is not deleted. It is deactivated instead, so its history stays intact: it remains readable through GET /v1/customers/{customerId} with isActive: false, and keeps its metadata. The response says result: DEACTIVATED.

Either way, the customer's sub-customers are detached from it and become self-billing (parentCustomerId: null, billingRelationship: SELF).

A parent customer is refused with 400 and the code CUSTOMER_CANNOT_DELETE_PARENT_CHILD_NO_DELIVERY when a sub-customer billed through it (billingRelationship: PARENT_PAYS) has an active subscription and no way to receive its own documents. details.childCustomerId names that sub-customer. Give it an email address (or, where your company sends e-invoices, a number it can receive them on), then delete again.

Returns 404 with the code CUSTOMER_NOT_FOUND when the customer does not exist in your company.

Deletes in one company run one at a time, so calls sent in parallel wait for each other. A delete that waits more than 30 seconds is refused with 409 and the code CUSTOMER_DELETE_BUSY. Nothing is deleted, so send it again.

Required Scope

• customers-write

Credential: a company's API key or OAuth token.

Partially updates a customer — only the fields you send are changed; send null to clear a clearable field. Returns the full updated customer.

externalSystemId follows the same rules as on create: unique within your company (409 EXTERNAL_SYSTEM_ID_ALREADY_EXISTS on conflict), empty values treated as unset.

Required Scope

• customers-write

Credential: a company's API key or OAuth token.

Retrieves the contact persons registered on a customer. The customer's default contact is returned first, then the rest alphabetically.

Required Scope

• customers-read

Credential: a company's API key or OAuth token.

Retrieves the departments of a customer — sub-units with their own address, EAN number (for e-invoicing), and purchase-order number, typically used to route invoices within larger organizations.

The default department is returned first, then the rest alphabetically.

Required Scope

• customers-read

Credential: a company's API key or OAuth token.

Retrieves all customer groups for your company, sorted by group number. Groups carry a discount percentage and the ledger account customers in the group post to — assign a customer to a group via the customerGroupId field when creating or updating the customer.

Results are cached for 5 seconds.

Required Scope

• customers-read — the full group configuration, or
• checkout — the partner checkout surface requires a customerGroupId on every session, so a checkout-scoped key can discover the groups without a customer-data grant. With ONLY the checkout scope, each entry is slimmed to id, number and name — the tenant's accounting configuration (ledger account wiring, metadata) stays behind customers-read.