<- Customers API

Customers API

All versions ->

Search customers

POST

 /v2/customers/search

Searches the customer profiles associated with a Square account using a supported query filter.

Calling SearchCustomers without any explicit query filter returns all customer profiles ordered alphabetically based on given_name and family_name.

Under normal operating conditions, newly created or updated customer profiles become available for the search operation in well under 30 seconds. Occasionally, propagation of the new or updated profiles can take closer to one minute or longer, especially during network incidents and outages.

Permissions:CUSTOMERS_READ

Guide

Search for Customer Profiles

Try in API Explorer
Link to section

Request body

Example code

Link to section

cursor

string

Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query.

For more information, see Pagination.

Link to section

limit

integer(64-bit)

The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. The limit is ignored if it is less than the minimum or greater than the maximum value. The default value is 100.

For more information, see Pagination.

Min
1
Max
100
Link to section

query

Query customers based on the given conditions and sort order. Calling SearchCustomers without an explicit query parameter returns all customers ordered alphabetically based on given_name and family_name.

Link to section

Response fields

Link to section

errors

Any errors that occurred during the request.

Link to section

customers

An array of Customer objects that match a query.

Link to section

cursor

string

A pagination cursor that can be used during subsequent calls to SearchCustomers to retrieve the next set of results associated with the original query. Pagination cursors are only present when a request succeeds and additional results are available.

For more information, see Pagination.