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

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:

{
  "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