Search customers

Operation ID: searchCustomer

Group: Accounting › Customers

Open in the interactive reference

POST /accounting/customers/search

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches customers.

Parameters

Name In Type Required Description
Api-Version header string · 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 The filters to apply. A customer must match every filter you send. Omit to return all customers.
filters.id string no Limits results to the customer with this id.
filters.customerNumber string no Limits results to the customer with this customer number. The match is exact. Example: 'CUS-789012'.
filters.name string no Limits results to customers whose name contains this text. The match is case-insensitive.
filters.entityId string no Limits results to customers of this legal entity.
filters.customerType string no Limits results to customers of this type. Accepted values: 'default', 'partner', 'endCustomer'. Any other value matches no customer.
filters.externalIdentifier object no Limits results to customers that have this external identifier. Several customers can share one value.
filters.externalIdentifier.fieldName string yes The configured field name of the identifier. A name that is not configured fails with UNKNOWN_EXTERNAL_IDENTIFIER. Example: 'netsuiteCustomerId'.
filters.externalIdentifier.value string yes The identifier in the other system. The match is exact.
page object no Pagination controls. Omit for the first page.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit on the first request.
page.size number no The number of customers per page, between 1 and 200. Defaults to 50. A value above 200 is treated as 200, not rejected. 
{
  "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<object> yes The customers on this page, most recently created first. An empty array when nothing matches.
items[].id string yes The unique identifier for the customer.
items[].name string yes The name of the customer, as it appears on invoices.
items[].customerNumber string yes The customer number. Example: 'CUS-789012'.
items[].customerType string no The customer type. Possible values: 'default' (a direct customer), 'partner' (a reseller or third-party payer that is invoiced for its end customers), 'endCustomer' (a customer that buys through a partner).
items[].partnerType string no The partner type of a customer whose customerType is 'partner'. Possible values: 'reseller', 'thirdPartyPayer'.
items[].businessType string no The business type of the customer. Possible values: 'company', 'individual'.
items[].entityId string yes The legal entity that invoices this customer.
items[].entityName string no The name of the legal entity that invoices this customer.
items[].lastModifiedDate date-time yes The date and time the customer record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].invoiceEmail string no The email address invoices are sent to.
items[].mainEmail string no The email address of the customer's main contact.
items[].taxExempt boolean no Whether the customer is exempt from tax.
items[].defaultCurrency string no The default currency for the customer's transactions, as a 3-letter ISO 4217 code.
items[].segment string no The market segment of the customer. Possible values: 'SMB', 'MidMarket', 'Enterprise'. Absent when businessType is 'individual'.
items[].paymentTermLabel string no The display name of the payment term applied to the customer's invoices. See label on GET accounting/payment-terms.
items[].exemptionNumber string no The tax-exemption certificate number. Absent when taxExempt is false.
items[].addresses array<object> no The customer's addresses, bill-to entries first, then sold-to. Each entry names its type and whether it is that type's default. An empty array when the customer has no address.
items[].addresses[].type string yes The address type. Possible values: 'billTo', 'soldTo'.
items[].addresses[].isDefault boolean yes Whether this is the customer's default address of its type.
items[].addresses[].addressId string no The unique identifier for the address.
items[].addresses[].attention string no The person or department that mail to this address is for.
items[].addresses[].line1 string no The first address line: street number and name, or PO box.
items[].addresses[].line2 string no The second address line: apartment, suite, unit, building, or floor.
items[].addresses[].city string no The city or locality.
items[].addresses[].stateProvince string no The state, province, or region.
items[].addresses[].country string no The country, as a name or ISO 3166-1 code.
items[].addresses[].zipCode string no The postal or ZIP code.
items[].taxExemptCode string no The tax-exemption reason code.
items[].salesChannel string no The sales channel for this customer. Possible values: 'salesAssisted' (sold through a salesperson), 'selfServe'.
items[].additionalContactEmail string no Another email address for the customer, besides invoiceEmail and mainEmail.
items[].mainContactName string no The name of the customer's main contact.
items[].preferredLanguage string no The customer's preferred language. Possible values: 'english'.
items[].crmCustomerId string no The customer's identifier in an external CRM system.
items[].businessIdentificationNumber string no The customer's business registration number.
items[].invoiceConsolidation string no How the customer's invoices are consolidated. Possible values: 'customer', 'purchaseOrderNumber', 'salesArrangement'.
items[].invoiceDeliveryMode string no How invoices are delivered to the customer. Possible values: 'manual', 'automated'.
items[].isExemptFromCreditCardFee boolean no Whether the customer is exempt from credit-card fees.
items[].billableTravelExpenseInvoiceDetail string no How billable travel and expense items appear on invoices. Possible values: 'detailed', 'consolidated'.
items[].status string no The status of the customer. Possible values: 'active', 'inactive'.
items[].paymentTerm string no The code of the payment term applied to the customer's invoices. See code on GET accounting/payment-terms. paymentTermLabel is its display name.
items[].taxRegistrations array<object> no The customer's tax registrations. An empty array when the customer has none.
items[].taxRegistrations[].country string yes The country the registration applies in, as an ISO 3166-1 code.
items[].taxRegistrations[].taxNumber string yes The tax identification number issued by the tax authority.
items[].taxRegistrations[].type string yes The kind of tax registration. Possible values: 'tax', 'salesTax', 'VAT', 'GST', 'EIN', 'TIN'.
items[].taxRegistrations[].effectiveDate string no The date the registration takes effect. Format YYYY-MM-DD.
items[].taxRegistrations[].isActive boolean no Whether the registration is active. Only one active registration is allowed per country and tax type.
items[].taxRegistrations[].note string no An internal note on the registration.
items[].taxRegistrations[].validationStatus string no The validation state the tax engine assigned.
items[].taxRegistrations[].validationMessages string no Detail behind the validation state, when the tax engine recorded any.
items[].payment object no The customer's link to a payment provider. Absent when no provider is linked.
items[].payment.provider string no The name of the payment provider. Example: '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 in the payment provider's system.
items[].externalIdentifiers array<object> no The customer's identifiers in other systems, one per configured field name. An empty array when the customer has none.
items[].externalIdentifiers[].fieldName string yes The configured field name of the identifier. Example: 'netsuiteCustomerId'.
items[].externalIdentifiers[].value string yes The identifier in the other system.
items[].externalIdentifiers[].externalUrl string no A link to the record in the other system.
pagination object yes Cursors for the next page.
pagination.nextCursor string no The cursor for the next page. Pass it as page.cursor. Absent on the last page.
pagination.hasMore boolean yes Whether more customers remain beyond this page. 
{
  "data": {
    "items": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "<name>",
        "customerNumber": "<customerNumber>",
        "customerType": "<customerType>",
        "partnerType": "<partnerType>",
        "businessType": "<businessType>",
        "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "entityName": "<entityName>",
        "lastModifiedDate": "2026-01-15T09:30:00.000Z",
        "invoiceEmail": "<invoiceEmail>",
        "mainEmail": "<mainEmail>",
        "taxExempt": true,
        "defaultCurrency": "<defaultCurrency>",
        "segment": "<segment>",
        "paymentTermLabel": "<paymentTermLabel>",
        "exemptionNumber": "<exemptionNumber>",
        "addresses": [
          {
            "type": "<type>",
            "isDefault": true,
            "addressId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "attention": "<attention>",
            "line1": "<line1>",
            "line2": "<line2>",
            "city": "<city>",
            "stateProvince": "<stateProvince>",
            "country": "<country>",
            "zipCode": "<zipCode>"
          }
        ],
        "taxExemptCode": "<taxExemptCode>",
        "salesChannel": "<salesChannel>",
        "additionalContactEmail": "<additionalContactEmail>",
        "mainContactName": "<mainContactName>",
        "preferredLanguage": "<preferredLanguage>",
        "crmCustomerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "businessIdentificationNumber": "<businessIdentificationNumber>",
        "invoiceConsolidation": "<invoiceConsolidation>",
        "invoiceDeliveryMode": "<invoiceDeliveryMode>",
        "isExemptFromCreditCardFee": true,
        "billableTravelExpenseInvoiceDetail": "<billableTravelExpenseInvoiceDetail>",
        "status": "<status>",
        "paymentTerm": "<paymentTerm>",
        "taxRegistrations": [
          {
            "country": "<country>",
            "taxNumber": "<taxNumber>",
            "type": "<type>",
            "effectiveDate": "<effectiveDate>",
            "isActive": true,
            "note": "<note>",
            "validationStatus": "<validationStatus>",
            "validationMessages": "<validationMessages>"
          }
        ],
        "payment": {
          "provider": "<provider>",
          "externalCustomerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "externalPaymentMethodId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        },
        "externalIdentifiers": [
          {
            "fieldName": "<fieldName>",
            "value": "<value>",
            "externalUrl": "<externalUrl>"
          }
        ]
      }
    ],
    "pagination": {
      "nextCursor": "<nextCursor>",
      "hasMore": true
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code Status
UNKNOWN_EXTERNAL_IDENTIFIER 400

Statuses