Search customers
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.
| Name | Description |
|---|---|
cursor
|
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. |
limit
|
A limit on the number of results to be returned in a single page. The limit is advisory. The implementation might return more or fewer results. If the supplied limit is negative, zero, or higher than the maximum limit of 100, it is ignored. |
query
|
Query customers based on the given conditions and sort order.
Calling |
Response Fields
| Name | Description |
|---|---|
errors
|
Any errors that occurred during the request. |
customers
|
An array of |
cursor
|
A pagination cursor that can be used during subsequent calls
to For more information, see Pagination. |
Examples
- cURL
- Ruby
- Python
- C#
- Java
- PHP
- Node.js
curl https://connect.squareup.com/v2/customers/search \
-X POST \
-H 'Square-Version: 2021-05-13' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"query": {
"filter": {
"email_address": {
"fuzzy": "example.com"
},
"creation_source": {
"values": [
"THIRD_PARTY"
],
"rule": "INCLUDE"
},
"created_at": {
"start_at": "2018-01-01T00:00:00-00:00",
"end_at": "2018-02-01T00:00:00-00:00"
},
"group_ids": {
"all": [
"545AXB44B4XXWMVQ4W8SBT3HHF"
]
}
},
"sort": {
"field": "CREATED_AT",
"order": "ASC"
}
},
"limit": 2
}'{
"customers": [
{
"id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
"created_at": "2018-01-23T20:21:54.859Z",
"updated_at": "2020-04-20T10:02:43.083Z",
"given_name": "James",
"family_name": "Bond",
"email_address": "james.bond@example.com",
"address": {
"address_line_1": "505 Electric Ave",
"address_line_2": "Suite 600",
"locality": "New York",
"administrative_district_level_1": "NY",
"postal_code": "10003",
"country": "US"
},
"phone_number": "1-212-555-4250",
"reference_id": "YOUR_REFERENCE_ID_2",
"preferences": {
"email_unsubscribed": false
},
"creation_source": "DIRECTORY",
"group_ids": [
"545AXB44B4XXWMVQ4W8SBT3HHF"
],
"segment_ids": [
"1KB9JE5EGJXCW.REACHABLE"
],
"version": 7
},
{
"id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
"created_at": "2018-01-30T14:10:54.859Z",
"updated_at": "2018-03-08T18:25:21.342Z",
"given_name": "Amelia",
"family_name": "Earhart",
"email_address": "amelia.earhart@example.com",
"address": {
"address_line_1": "500 Electric Ave",
"address_line_2": "Suite 600",
"locality": "New York",
"administrative_district_level_1": "NY",
"postal_code": "10003",
"country": "US"
},
"phone_number": "1-212-555-4240",
"reference_id": "YOUR_REFERENCE_ID_1",
"note": "a customer",
"preferences": {
"email_unsubscribed": false
},
"creation_source": "THIRD_PARTY",
"group_ids": [
"545AXB44B4XXWMVQ4W8SBT3HHF"
],
"segment_ids": [
"1KB9JE5EGJXCW.REACHABLE"
],
"version": 1
}
],
"cursor": "9dpS093Uy12AzeE"
}