# Customers

`GET /accounting/customers`

Group: Accounting › Customers · Operation ID: `customers`

List customers with structured filters. GET data-set exposing filter[field][op]= (eq/ne/gt/gte/lt/lte/in/notIn/between/like), sort=-lastModifiedDate,customerName, sparse fields=, and page[size]/page[cursor] cursor pagination. Returns the collection header of each customer; the full record, with addresses and external identifiers, comes from GET accounting/customers/:id or POST accounting/customers/search. Name and e-mail matching belong in search. Every request must carry the Api-Version header.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=customers)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | `"v1"` | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |

## Query surface

- `id` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `customerType` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `businessType` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `customerSegment` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `defaultCurrency` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `taxExempt` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `paymentTermLabel` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `lastModifiedDate` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- Orderable: id, customerName, customerType, businessType, customerSegment, defaultCurrency, taxExempt, paymentTermLabel, exemptionNumber, invoiceEmail, lastModifiedDate
- Selectable: id, customerNumber, customerName, customerType, businessType, customerSegment, entityName, defaultCurrency, taxExempt, paymentTermLabel, exemptionNumber, invoiceEmail, lastModifiedDate

## Response

`200` Success

Under `data`, an array of customersRow:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | Stable, platform-assigned id (a UUID) of the customer — the public identifier used by GET accounting/customers/:id. Filter e.g. filter[id][in]=<id1>,<id2>. |
| `customerNumber` | string or null | no | System-generated customer number, unique per tenant. Absent until one has been assigned. Returned but NOT filterable or orderable — a business document identifier is sensitive content and must not travel in a URL; match on it through POST accounting/customers/search. |
| `customerName` | string | no | Customer display name, as it appears on invoices and official documents. Orderable but NOT filterable by design — name matching belongs in POST accounting/customers/search, so it never travels in a URL. |
| `customerType` | string | no | Customer type. One of 'default', 'partner', 'endCustomer'. Filter target: filter[customerType][eq]=partner. |
| `businessType` | string | no | Whether the customer is a registered company or an individual. One of 'company', 'individual'. Filter target: filter[businessType][eq]=company. |
| `customerSegment` | string or null | no | Market segment classification. One of 'SMB', 'MidMarket', 'Enterprise'. Filter target: filter[customerSegment][in]=MidMarket,Enterprise. |
| `entityName` | string or null | no | Name of the legal entity that owns this customer, as denormalised onto the customer record. Returned but NOT filterable or orderable — it identifies the counterparty's owning entity and must not travel in a URL; match on it through POST accounting/customers/search, which filters on the entity's id. |
| `defaultCurrency` | string or null | no | Default transaction currency as a 3-letter ISO 4217 code, e.g. USD, EUR. Filter target: filter[defaultCurrency][in]=USD,EUR. |
| `taxExempt` | boolean or null | no | True when the customer is exempt from tax on all transactions. Filter target: filter[taxExempt][eq]=true. |
| `paymentTermLabel` | string or null | no | Label of the payment term applied to this customer's invoices, denormalised from the linked payment term. Filter target: filter[paymentTermLabel][eq]=Net%2030. |
| `exemptionNumber` | string or null | no | Government-issued tax-exemption certificate number, when the customer is exempt. Orderable but NOT filterable — a certificate number must not travel in a URL; match on it through POST accounting/customers/search. |
| `invoiceEmail` | string or null | no | Email address that receives invoices and billing statements. Orderable but NOT filterable — it is personal data and must not travel in a URL; match on it through POST accounting/customers/search. |
| `lastModifiedDate` | string (date-time) or null | no | Instant the customer record last changed, as ISO 8601 UTC (YYYY-MM-DDTHH:mm:ss.sssZ). Poll on this to sync incrementally rather than re-reading the whole collection. Absent from this data-set because the engine cannot yet bridge DateTime to a data-set field type; use POST accounting/customers/search instead. |

## Statuses

- `400` — Invalid request or business failure
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error