Skip to content

Clients

Explore here
Copy as markdownView as markdown

Clients

The people and companies you bill. Contact details come back masked unless the credential holds contacts:read.

All sectionsAuthentication

clients

List

GET/v1/clients

List clients, newest first (contact details masked unless contacts:read).

Scope
clients:read
Effect
Read only
MCP tool
list_clients
Retries
Safe to repeat

Parameters

List parameters
NameInTypeNotes
limitoptionalqueryintegermin 1 · max 50
cursoroptionalquerystringup to 256 chars
archivedoptionalqueryboolean—

Returns

data: Client[]. Pass meta.cursor back as cursor for the next page.

Example requestSample
curl -X GET "https://api.billingmart.com/v1/clients" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

clients

Create

POST/v1/clients

Create a client (contacts unverified until the customer verifies them).

Scope
clients:write
Effect
Writes a draft or record
MCP tool
create_client
Retries
Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

Request body

JSON. Money is an integer count of minor units beside its currency; quantities are thousandths.

Create request body
FieldTypeNotes
displayNamerequiredstringup to 200 chars
companyNameoptionalstringup to 200 chars
preferredLanguageoptionalstringup to 8 chars
preferredCurrencyoptionalCurrency—
notesoptionalstringup to 4000 chars
businessIdoptionalid—
contacts[]optionalobject[]up to 10 items
contacts[].kindrequiredenumOne of email, phone
contacts[].valuerequiredstringup to 320 chars
forceoptionalboolean—

Returns

data: object

Example requestSample
curl -X POST "https://api.billingmart.com/v1/clients" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"displayName":"<displayName>"}'

clients

Find

GET/v1/clients/find

Find clients by name prefix.

Scope
clients:read
Effect
Read only
MCP tool
find_client
Retries
Safe to repeat

Parameters

Find parameters
NameInTypeNotes
qrequiredquerystringup to 100 chars
limitoptionalqueryintegermin 1 · max 50
cursoroptionalquerystringup to 256 chars

Returns

data: Client[]. Pass meta.cursor back as cursor for the next page.

Example requestSample
curl -X GET "https://api.billingmart.com/v1/clients/find" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

clients

Get

GET/v1/clients/{clientId}

One client.

Scope
clients:read
Effect
Read only
MCP tool
get_client
Retries
Safe to repeat

Parameters

Get parameters
NameInTypeNotes
clientIdrequiredpathid—

Returns

data: Client

Example requestSample
curl -X GET "https://api.billingmart.com/v1/clients/{clientId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

clients

Update

PATCH/v1/clients/{clientId}

Update a client’s editable fields. `null` removes an optional one.

Scope
clients:write
Effect
Writes a draft or record
MCP tool
update_client
Retries
No Idempotency-Key on this route

Parameters

Update parameters
NameInTypeNotes
clientIdrequiredpathid—

Request body

JSON. Money is an integer count of minor units beside its currency; quantities are thousandths.

Update request body
FieldTypeNotes
displayNameoptionalstringup to 200 chars
companyNameoptionalstring | null—
preferredLanguageoptionalstring | null—
preferredCurrencyoptionalCurrency | null—
notesoptionalstring | null—

Returns

data: Client

Example requestSample
curl -X PATCH "https://api.billingmart.com/v1/clients/{clientId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

clients

Archive

POST/v1/clients/{clientId}/archive

Archive or unarchive a client. An archived client cannot be invoiced; nothing is deleted, and a merged client stays archived. Archiving pauses the client’s active schedules and answers meta.dependents: its open invoices (still payable), draft invoices, draft estimates and the schedules it paused.

Scope
clients:write
Effect
Writes a draft or record
MCP tool
archive_client
Retries
Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

Parameters

Archive parameters
NameInTypeNotes
clientIdrequiredpathid—

Request body

JSON. Money is an integer count of minor units beside its currency; quantities are thousandths.

Archive request body
FieldTypeNotes
archivedoptionalboolean—

Returns

data: object

Example requestSample
curl -X POST "https://api.billingmart.com/v1/clients/{clientId}/archive" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

clients

Add contact

POST/v1/clients/{clientId}/contacts

Add an UNVERIFIED email or phone to a client. Needs contacts:read as well, because the value is a contact detail this connection then holds. The customer verifies it; nothing is sent here. Without contacts:read, ask a person to type it instead: POST /v1/actions/addClientContact.

Scope
clients:write
Effect
Writes a draft or record
MCP tool
add_client_contact
Retries
Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

Parameters

Add contact parameters
NameInTypeNotes
clientIdrequiredpathid—

Request body

JSON. Money is an integer count of minor units beside its currency; quantities are thousandths.

Add contact request body
FieldTypeNotes
kindrequiredenumOne of email, phone
valuerequiredstringat least 3 chars · up to 320 chars
labeloptionalstringup to 60 chars

Returns

data: object

Errors this route can answer besides the shared ones: ALREADY_EXISTS.

Example requestSample
curl -X POST "https://api.billingmart.com/v1/clients/{clientId}/contacts" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"kind":"email","value":"<value>"}'

Object

Client

A customer of a business. emailKey and phoneKey are the hashed, namespaced contact keys that make cross-tenant 'all my bills' fall out of verification. A client reaches a record only through a VERIFIED contact — invariant 6 — so an unverified contact here resolves to nothing.

Client fields
FieldTypeNotes
idrequiredId—
tenantrequiredTenantRef—
displayNamerequiredstringUntrusted textA client can name themselves an instruction; every MCP response wraps this in an explicit data envelope.
companyNameoptionalstringUntrusted text—
contactsrequiredContact[]—
emailKeyoptionalContactKeyem_<sha256(lowercased email)> of the primary VERIFIED email, when there is one. Absent until verification.
phoneKeyoptionalContactKeyph_<sha256(E.164)> of the primary VERIFIED phone, when there is one.
billingAddressoptionalAddress—
preferredLanguageoptionalLanguage—
preferredCurrencyoptionalCurrency—
notesoptionalstringUntrusted textINTERNAL. Never crosses to the public pay link.
defaultTaxCategoryoptionalTaxCategoryCodeThe tax category a new record of this payee starts from: it is suggested first, free of AI credits, and a person still confirms.
statsoptionalClientStats—
archivedoptionalboolean—
mergedIntooptionalIdSet by mergeClients on the archived duplicate: the client it was merged into. Server-only.
searchoptionalClientSearchServer-maintained index fields: normalised name and company for prefix search, and the contact keys for dedup lookups. Never client-writable.
createdAtrequiredIsoTimestamp—
updatedAtoptionalIsoTimestamp—
createdByoptionalId—
lastWriteActoroptionalWriteActor—
Next section

Invoices

Drafts, lines, deposits, progress billing and reminders. Every write here produces or edits a draft; sending is an action, approved by a person or the owner’s capped rule.

Continue to Invoices →

Try it against your sandbox

Create a bmk_test_ key in the console. It can only reach your sandbox workspace.

Start freeAll sections

We use Google Analytics on our website by default to understand visits. Choose Decline to turn it off; you can change this at any time on the Cookies page. We never send Google your name, email or account. Cookie policy