Source: https://billingmart.com/developers/api/clients

# Clients

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

[All sections](https://billingmart.com/developers/api) [Authentication](https://billingmart.com/developers/authentication)

**On this page**

- GET List
- POST Create
- GET Find
- GET Get
- PATCH Update
- POST Archive
- POST Add contact
- OBJ Client

On this page

- GET List
- POST Create
- GET Find
- GET Get
- PATCH Update
- POST Archive
- POST Add contact
- OBJ Client

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
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `limit`optional | query | `integer` | min 1 · max 50 |
| `cursor`optional | query | `string` | up to 256 chars |
| `archived`optional | query | `boolean` | — |

### Returns

`data`: [`Client[]`](https://billingmart.com/developers/api/clients#object-Client) . Pass `meta.cursor` back as `cursor` for the next page.

Example request Sample

```
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
| Field | Type | Notes |
| --- | --- | --- |
| `displayName`required | `string` | up to 200 chars |
| `companyName`optional | `string` | up to 200 chars |
| `preferredLanguage`optional | `string` | up to 8 chars |
| `preferredCurrency`optional | `Currency` | — |
| `notes`optional | `string` | up to 4000 chars |
| `businessId`optional | `id` | — |
| `contacts[]`optional | `object[]` | up to 10 items |
| `contacts[].kind`required | `enum` | One of `email`, `phone` |
| `contacts[].value`required | `string` | up to 320 chars |
| `force`optional | `boolean` | — |

### Returns

`data`: `object`

Example request Sample

```
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
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `q`required | query | `string` | up to 100 chars |
| `limit`optional | query | `integer` | min 1 · max 50 |
| `cursor`optional | query | `string` | up to 256 chars |

### Returns

`data`: [`Client[]`](https://billingmart.com/developers/api/clients#object-Client) . Pass `meta.cursor` back as `cursor` for the next page.

Example request Sample

```
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
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `clientId`required | path | `id` | — |

### Returns

`data`: [`Client`](https://billingmart.com/developers/api/clients#object-Client)

Example request Sample

```
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
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `clientId`required | path | `id` | — |

### Request body

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

Update request body
| Field | Type | Notes |
| --- | --- | --- |
| `displayName`optional | `string` | up to 200 chars |
| `companyName`optional | `string \| null` | — |
| `preferredLanguage`optional | `string \| null` | — |
| `preferredCurrency`optional | `Currency \| null` | — |
| `notes`optional | `string \| null` | — |

### Returns

`data`: [`Client`](https://billingmart.com/developers/api/clients#object-Client)

Example request Sample

```
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
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `clientId`required | path | `id` | — |

### Request body

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

Archive request body
| Field | Type | Notes |
| --- | --- | --- |
| `archived`optional | `boolean` | — |

### Returns

`data`: `object`

Example request Sample

```
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
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `clientId`required | path | `id` | — |

### Request body

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

Add contact request body
| Field | Type | Notes |
| --- | --- | --- |
| `kind`required | `enum` | One of `email`, `phone` |
| `value`required | `string` | at least 3 chars · up to 320 chars |
| `label`optional | `string` | up to 60 chars |

### Returns

`data`: `object`

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

Example request Sample

```
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
| Field | Type | Notes |
| --- | --- | --- |
| `id`required | `Id` | — |
| `tenant`required | `TenantRef` | — |
| `displayName`required | `string` | Untrusted text A client can name themselves an instruction; every MCP response wraps this in an explicit data envelope. |
| `companyName`optional | `string` | Untrusted text — |
| `contacts`required | `Contact[]` | — |
| `emailKey`optional | `ContactKey` | `em_<sha256(lowercased email)>` of the primary VERIFIED email, when there is one. Absent until verification. |
| `phoneKey`optional | `ContactKey` | `ph_<sha256(E.164)>` of the primary VERIFIED phone, when there is one. |
| `billingAddress`optional | `Address` | — |
| `preferredLanguage`optional | `Language` | — |
| `preferredCurrency`optional | `Currency` | — |
| `notes`optional | `string` | Untrusted text INTERNAL. Never crosses to the public pay link. |
| `defaultTaxCategory`optional | `TaxCategoryCode` | The tax category a new record of this payee starts from: it is suggested first, free of AI credits, and a person still confirms. |
| `stats`optional | `ClientStats` | — |
| `archived`optional | `boolean` | — |
| `mergedInto`optional | `Id` | Set by mergeClients on the archived duplicate: the client it was merged into. Server-only. |
| `search`optional | `ClientSearch` | Server-maintained index fields: normalised name and company for prefix search, and the contact keys for dedup lookups. Never client-writable. |
| `createdAt`required | `IsoTimestamp` | — |
| `updatedAt`optional | `IsoTimestamp` | — |
| `createdBy`optional | `Id` | — |
| `lastWriteActor`optional | `WriteActor` | — |

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 →](https://billingmart.com/developers/api/invoices)

## Try it against your sandbox

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

[Start free](https://app.billingmart.com/sign-up) [All sections](https://billingmart.com/developers/api)

---

This is the Markdown copy of https://billingmart.com/developers/api/clients. Live plans, prices and limits are published as JSON at https://billingmart.com/plans.json and https://billingmart.com/agent-info.json.