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.
Servers
- https://connect.squareup.com
Request headers
| Name | Type | Required | Description |
|---|---|---|---|
Content-Type |
String | Yes |
The media type of the request body.
Default value: "application/json" |
Request body fields
| Name | Type | Required | Description |
|---|---|---|---|
query |
Object | No |
Represents a query (including filtering criteria, sorting criteria, or both) used to search for customer profiles. |
query.filter |
Object | No |
Represents a set of |
query.filter.email_address |
Object | No |
A filter to select customers based on exact or fuzzy matching of customer attributes against a specified query. Depending on the customer attributes, the filter can be case-sensitive. This filter can be exact or fuzzy, but it cannot be both. |
query.filter.email_address.exact |
String | No |
Use the exact filter to select customers whose attributes match exactly the specified query. |
query.filter.email_address.fuzzy |
String | No |
Use the fuzzy filter to select customers whose attributes match the specified query in a fuzzy manner. When the fuzzy option is used, search queries are tokenized, and then each query token must be matched somewhere in the searched attribute. For single token queries, this is effectively the same behavior as a partial match operation. |
query.filter.created_at |
Object | No |
Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled. |
query.filter.created_at.start_at |
String | No |
A datetime value in RFC 3339 format indicating when the time range starts. |
query.filter.created_at.end_at |
String | No |
A datetime value in RFC 3339 format indicating when the time range ends. |
query.filter.creation_source |
Object | No |
The creation source filter. If one or more creation sources are set, customer profiles are included in, or excluded from, the result if they match at least one of the filter criteria. |
query.filter.creation_source.values[] |
Array | No |
The list of creation sources used as filtering criteria. |
query.filter.creation_source.rule |
String | No |
Indicates whether a customer profile matching the filter criteria should be included in the result or excluded from the result. Default: |
query.filter.group_ids |
Object | No |
A filter to select resources based on an exact field value. For any given value, the value can only be in one property. Depending on the field, either all properties can be set or only a subset will be available. Refer to the documentation of the field. |
query.filter.group_ids.any[] |
Array | No |
A list of terms where at least one of them must be present on the field of the resource. |
query.filter.group_ids.all[] |
Array | No |
A list of terms that must be present on the field of the resource. |
query.filter.group_ids.none[] |
Array | No |
A list of terms that must not be present on the field the resource |
query.filter.phone_number |
Object | No |
A filter to select customers based on exact or fuzzy matching of customer attributes against a specified query. Depending on the customer attributes, the filter can be case-sensitive. This filter can be exact or fuzzy, but it cannot be both. |
query.filter.phone_number.exact |
String | No |
Use the exact filter to select customers whose attributes match exactly the specified query. |
query.filter.phone_number.fuzzy |
String | No |
Use the fuzzy filter to select customers whose attributes match the specified query in a fuzzy manner. When the fuzzy option is used, search queries are tokenized, and then each query token must be matched somewhere in the searched attribute. For single token queries, this is effectively the same behavior as a partial match operation. |
query.filter.reference_id |
Object | No |
A filter to select customers based on exact or fuzzy matching of customer attributes against a specified query. Depending on the customer attributes, the filter can be case-sensitive. This filter can be exact or fuzzy, but it cannot be both. |
query.filter.reference_id.exact |
String | No |
Use the exact filter to select customers whose attributes match exactly the specified query. |
query.filter.reference_id.fuzzy |
String | No |
Use the fuzzy filter to select customers whose attributes match the specified query in a fuzzy manner. When the fuzzy option is used, search queries are tokenized, and then each query token must be matched somewhere in the searched attribute. For single token queries, this is effectively the same behavior as a partial match operation. |
query.filter.updated_at |
Object | No |
Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled. |
query.filter.updated_at.start_at |
String | No |
A datetime value in RFC 3339 format indicating when the time range starts. |
query.filter.updated_at.end_at |
String | No |
A datetime value in RFC 3339 format indicating when the time range ends. |
query.sort |
Object | No |
Specifies how searched customers profiles are sorted, including the sort key and sort order. |
query.sort.field |
String | No |
Use one or more customer attributes as the sort key to sort searched customer profiles.
For example, use the creation date ( Default: |
query.sort.order |
String | No |
Indicates the order in which results should be sorted based on the sort field value. Strings use standard alphabetic comparison to determine order. Strings representing numbers are sorted as strings. Default: |
limit |
Integer | No |
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. |
cursor |
String | No |
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. |
How to start integrating
- Add HTTP Task to your workflow definition.
- Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
- Click Test request to test run your request to the API and see the API's response.