• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Search customers

POST /v2/customers/search

Searches the customer profiles associated with a Square account using one or more supported query filters.

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

Request Body

Example code
Name Description
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.
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. If the specified limit is invalid, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 100.

For more information, see Pagination.

Min 1 Max 100
query
CustomerQuery

The filtering and sorting criteria for the search request. If a query is not specified, Square returns all customer profiles ordered alphabetically by given_name and family_name.

Response Fields
Name Description
errors
Error [ ]

Any errors that occurred during the request.
customers
Customer [ ]

The customer profiles that match the search query. If any search condition is not met, the result is an empty object ({}).
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.

Examples

Example:
You are viewing an old version of the API
POST /v2/customers/search
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -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
  }'
Response JSON 
{
  "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": "A9641GZW2H7Z56YYSD41Q12HDW",
      "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-9238",
      "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"
}