# Search Customer

`POST /accounting/customers/search`

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

Search customers by id, customer number, name, legal entity or customer type, and page through the matches. POST so the filters — `name` above all — travel in the JSON body rather than the URL. Read-only. Returns the full customer record for each match, including bill-to / sold-to addresses and external identifiers; matching nothing is an empty items array with HTTP 200, not a 404. Every request must carry the Api-Version header.

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

## 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`. |

## Request body

Required, `application/json`: searchCustomerInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | no | Search filters, nested as one object so they map onto the POST body. All are optional and are ANDed; omitting every one of them matches all customers. Omit the whole object to do exactly that. |
| `filters.id` | string | no | Exact match on a customer's id (a UUID). This is how a single known customer is fetched. |
| `filters.customerNumber` | string | no | Exact match on the system-generated customer number, e.g. CUST-001234. |
| `filters.name` | string | no | Case-insensitive SUBSTRING match on the customer display name. In the body precisely because a name must never travel in a URL. |
| `filters.entityId` | string | no | Restrict to customers owned by this legal entity, given as the entity id (a UUID). An id that matches no entity yields an empty page, not an error. |
| `filters.customerType` | string | no | Restrict to customers of this type. One of 'default', 'partner', 'endCustomer'; any other value yields an empty page. |
| `filters.externalIdentifier` | object | no | Match one identifier owned by another system. Both members are required: a fieldName on its own would match every value stored under that key. Not unique across customers — several may share one value — so this returns the ordinary items array, not a single record. |
| `filters.externalIdentifier.fieldName` | string | yes | Configured key of the external identifier — a stable camelCase slug such as 'netsuiteSoNumber', not the human-readable label. Must match an active CustomerExternalIdentifierConfiguration or the call fails with UNKNOWN_EXTERNAL_IDENTIFIER. |
| `filters.externalIdentifier.value` | string | yes | The identifier as the source system holds it. Matched exactly, case-sensitively. |
| `page` | object | no | Pagination controls. Omit for the first page. |
| `page.cursor` | string | no | Opaque forward cursor from a previous response's pagination.nextCursor; omit for the first page. Do not construct manually. |
| `page.size` | number | no | Maximum number of customers to return. Defaults to 50, capped at 200; the server may return fewer, but never more. |

Example:

```json
{
  "filters": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "customerNumber": "<customerNumber>",
    "name": "<name>",
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "customerType": "<customerType>",
    "externalIdentifier": {
      "fieldName": "<fieldName>",
      "value": "<value>"
    }
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}
```

## Response

`200` Success

Under `data` (searchCustomerOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | Matching customers for this page, newest first. Empty when nothing matches. |
| `items[].id` | string | yes | Id of the customer (a UUID) — the public identifier of this record. |
| `items[].name` | string | yes | Customer display name, as it appears on invoices and official documents. |
| `items[].customerNumber` | string | yes | System-generated customer number, unique per tenant. Absent until one has been assigned. |
| `items[].customerType` | string | no | Customer type. One of 'default', 'partner', 'endCustomer'. |
| `items[].partnerType` | string | no | Partner type, set when customerType is 'partner'. One of 'reseller', 'thirdPartyPayer'. |
| `items[].businessType` | string | no | Whether the customer is a registered company or an individual. One of 'company', 'individual'. |
| `items[].entityId` | string | yes | Id of the legal entity that owns this customer (a UUID). A customer belongs to exactly one entity. |
| `items[].entityName` | string | no | Name of the owning legal entity. |
| `items[].lastModifiedDate` | string (date-time) | yes | 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. |
| `items[].invoiceEmail` | string | no | Email address that receives invoices and billing statements. |
| `items[].mainEmail` | string | no | Primary business contact email for general correspondence. |
| `items[].taxExempt` | boolean | no | True when the customer is exempt from tax on all transactions. |
| `items[].defaultCurrency` | string | no | Default transaction currency as a 3-letter ISO 4217 code (e.g. USD, EUR, GBP), when set. |
| `items[].segment` | string | no | Market segment classification. One of 'SMB', 'MidMarket', 'Enterprise'. |
| `items[].paymentTermLabel` | string | no | Label of the payment term applied to this customer's invoices, denormalised from the linked payment term. |
| `items[].exemptionNumber` | string | no | Government-issued tax-exemption certificate number, when the customer is exempt. |
| `items[].addresses` | array of object | no | The customer's addresses: bill-to (where invoices are sent) then sold-to (used for tax determination). Every address of a type is returned, not only the default one, so a type may contribute several entries. Each entry names its own type and whether it is that type's default, so read the list rather than assuming positions. |
| `items[].addresses[].type` | string | yes | Which address this is. One of 'billTo', 'soldTo'. |
| `items[].addresses[].isDefault` | boolean | yes | Whether this is the customer's default address of that type. |
| `items[].addresses[].addressId` | string | no | Id of the address record (a UUID). |
| `items[].addresses[].attention` | string | no | Person or department correspondence at this address is directed to. |
| `items[].addresses[].line1` | string | no | Street address line 1: number, street name, or PO box. |
| `items[].addresses[].line2` | string | no | Apartment, suite, unit, building, floor, etc. |
| `items[].addresses[].city` | string | no | City or locality. |
| `items[].addresses[].stateProvince` | string | no | State, province, or region. |
| `items[].addresses[].country` | string | no | Country, as a name or ISO 3166-1 code. |
| `items[].addresses[].zipCode` | string | no | Postal or ZIP code. |
| `items[].taxExemptCode` | string | no | Code behind the tax exemption, as the authority categorises it. |
| `items[].salesChannel` | string | no | Channel the customer was won through. A SalesChannel member. |
| `items[].additionalContactEmail` | string | no | Further contact addresses, beyond the invoice and main contacts. |
| `items[].mainContactName` | string | no | Name of the customer's main contact person. |
| `items[].preferredLanguage` | string | no | Language the customer prefers correspondence in. A PreferredLanguage member. |
| `items[].crmCustomerId` | string | no | The customer's identifier in the CRM system it was sourced from. |
| `items[].businessIdentificationNumber` | string | no | Government-issued business registration number. |
| `items[].invoiceConsolidation` | string | no | How invoices are consolidated for this customer. An InvoiceConsolidation member. |
| `items[].invoiceDeliveryMode` | string | no | How invoices reach the customer. An InvoiceDeliveryMode member. |
| `items[].isExemptFromCreditCardFee` | boolean | no | Whether the customer is exempt from credit-card surcharges. |
| `items[].billableTravelExpenseInvoiceDetail` | string | no | Whether billable travel and expense items appear itemised or consolidated. An InvoiceDetail member. |
| `items[].status` | string | no | Lifecycle status of the customer record. A CustomerStatus member. |
| `items[].paymentTerm` | string | no | Code of the payment term applied to this customer's invoices; `paymentTermLabel` carries its display name. |
| `items[].taxRegistrations` | array of object | no | Tax registrations on file for this customer, across jurisdictions and tax types. Empty when the customer has none. |
| `items[].taxRegistrations[].country` | string | yes | ISO 3166-1 country code the registration applies in. |
| `items[].taxRegistrations[].taxNumber` | string | yes | Official tax identification number issued by the tax authority. |
| `items[].taxRegistrations[].type` | string | yes | Kind of tax identification number. One of 'tax', 'salesTax', 'VAT', 'GST', 'EIN', 'TIN'. |
| `items[].taxRegistrations[].effectiveDate` | string | no | Date the registration becomes valid for tax calculations (YYYY-MM-DD). |
| `items[].taxRegistrations[].isActive` | boolean | no | Whether the registration is currently used for tax calculations. |
| `items[].taxRegistrations[].note` | string | no | Free-text internal note recorded against the registration. |
| `items[].taxRegistrations[].validationStatus` | string | no | Validation state assigned by the tax engine, not by the caller. |
| `items[].taxRegistrations[].validationMessages` | string | no | Detail behind the validation state, when the engine recorded any. |
| `items[].payment` | object | no | The customer's payment-provider link, when one is registered: the provider and the customer / default-payment-method identifiers in that provider's system. Absent when the customer has none. |
| `items[].payment.provider` | string | no | Payment provider name, e.g. 'Stripe'. |
| `items[].payment.externalCustomerId` | string | no | The customer's identifier in the payment provider's system. |
| `items[].payment.externalPaymentMethodId` | string | no | The customer's default payment-method identifier in the provider's system. |
| `items[].externalIdentifiers` | array of object | no | External identifiers owned by other systems. At most one entry per fieldName. Absent when the customer has none; an omitted field and [] are equivalent. |
| `items[].externalIdentifiers[].fieldName` | string | yes | Configured key of the external identifier — a stable camelCase slug such as 'netsuiteSoNumber', not the human-readable label. Must match an active CustomerExternalIdentifierConfiguration. |
| `items[].externalIdentifiers[].value` | string | yes | The identifier as the source system holds it. |
| `items[].externalIdentifiers[].externalUrl` | string | no | Absolute http(s) link to the object in the originating system, when one is stored. |
| `pagination` | object | yes | Pagination cursor for this page. |
| `pagination.nextCursor` | string | no | Opaque cursor to pass as page.cursor for the next page; absent on the last page (mirrors the list/v1 data-set pagination.nextCursor). |
| `pagination.hasMore` | boolean | yes | True when more matches remain beyond this page (mirrors the list/v1 data-set pagination.hasMore). |

## Errors

| Code | Status |
| --- | --- |
| `UNKNOWN_EXTERNAL_IDENTIFIER` | 400 |

## Statuses

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