Use the Square Customers API to search for customers using one or more supported query filters.
Customers API

Search for Customer Profiles

The Customers API provides the RetrieveCustomer, ListCustomers, and SearchCustomers endpoints that developers can use to find and view detailed information about customer profiles stored in a Square seller account. This topic describes how to call SearchCustomers to search for customer profiles using one or more supported query filters.

To return search results, the seller account must have at least one customer profile. For information about how to create customer profiles using the Customers API, see Keep Customer Records.

Use the Customers API to search for customers Permalink Get a link to this section

Use the SearchCustomers endpoint in the Customers API to search for customer profiles stored in the Customer Directory for a seller account. When calling this endpoint, you can define search query filters to match one or more of the following Customer attributes:

  • phone_number. The phone number for the customer profile, which was collected by the seller or imported into the Customer Directory.

  • email_address. The email address for the customer profile, which was collected by the seller or imported into the Customer Directory.

  • creation_source. The source that created the customer profile.

  • created_at. The timestamp of when the customer profile was created.

  • updated_at. The timestamp of when the customer profile was last updated.

  • group_ids. The customer groups to which the customer profile belongs.

  • reference_id. An ID used to cross-reference the customer to an entity in an external system.

A SearchCustomers request can contain multiple query filters in any combination, which are combined as AND statements. The search results include customer profiles that match all specified query conditions. To search for customers that meet at least one of the specified query conditions, send multiple single-filter searches and then join the result sets.

Note

The SearchCustomers endpoint does not currently support searching by custom attributes nor does it return custom attributes in the results. However, you can use the RetrieveCustomerCustomAttribute or ListCustomerCustomAttributes endpoint to retrieve or list custom attributes for a specified customer profile. For more information, see Create and Manage Customer Custom Attributes.

Exact and fuzzy search Permalink Get a link to this section

With search by email addresses, phone numbers, and reference IDs, the API lets you search for targeted customer profiles with an exact or fuzzy match of the specified customer attributes against a query expression. With an exact search, a query expression is compared literally against the targeted customer attribute value. With a fuzzy match, the query expression is tokenized and each resulting token is compared against targeted attribute values. Customer profiles are returned if their targeted attribute values match all the tokens in any order.

Search result sorting Permalink Get a link to this section

You can choose to sort search results using the created_at attribute or using the default sort order. By default, customer profiles are sorted alphanumerically by concatenating given_name and family_name. If these names are not set, a string comparison is performed using one of the following attributes in the following order: company_name, email_address, and phone_number.

Newly created and updated profiles Permalink Get a link to this section

Under normal operating conditions, newly created or updated customer profiles become available in SearchCustomers and ListCustomers endpoints in less than 30 seconds after they are created or updated. Some updates can take up to 1 minute to propagate. Occasionally, extraordinary network conditions (such as, incidents or outages) can slow the propagation even further. Under such circumstances, newly created or updated profiles might not be included in your search result. When this happens, wait a short time and then retry your search request.

Search result pagination Permalink Get a link to this section

The default SearchCustomers page size is 100 records, but you can use the limit query filter to specify a smaller page size. If your search results include more than the default or specified limit, the endpoint paginates the results and returns a cursor that you can use to retrieve the next page of results. For more information, see Pagination. Note that the SearchCustomers endpoint treats the search limit as advisory and might return more or fewer results.

Search by creation source Permalink Get a link to this section

You can use the Square Seller Dashboard, a Square Point of Sale application, or the Customers API to create customer profiles in a seller account. Customer profiles created using the Seller Dashboard or a Square Point of Sale application have the Customer creation_source attribute set to the value of DIRECTORY. Profiles created using an application calling the Customers API have the creation_source attribute set to the value of THIRD_PARTY. When duplicate customer profiles are merged manually or automatically into a new and updated profile, the new customer profile's creation_source is set to MERGE.

To search customer profiles by creation source, submit a request with the creation_source filter specified in the request body. The following example shows how to search for customer profiles created by the Square Directory service, namely, through the Seller Dashboard or a Square Point of Sale application:

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "creation_source": {
          "values": [
            "DIRECTORY"
          ]
        }
      }
    }
  }'

To search for customer profiles created by third-party applications, change the creation_source filter in the previous example to use THIRD_PARTY in place of DIRECTORY:

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "creation_source": {
          "values": [
            "THIRD_PARTY"
          ]
        }
      }
    }
  }'

To search for customer profiles created by the Directory service or a third-party application, use the following filter in the request body:

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "creation_source": {
          "values": [
            "DIRECTORY",
            "THIRD_PARTY"
          ]
        }
      }
    }
  }'

Search by creation or update time Permalink Get a link to this section

You can call the SearchCustomers endpoint with the created_at or updated_at filter to search for customer profiles based on their creation time or the last-update time, respectively. Such filters are useful to synchronize customer data by polling. For example, you can issue a search by update time request in a given time interval and then determine subsequent actions to take on the updated customer in the search result.

The created_at and updated_at filters are identical in structure. They both require that you specify a start_at and end_at time to specify a time interval in which the targeted customer profiles were created or updated. For example, the following created_at filter defines the time interval when targeted customer profiles were created:

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "created_at": {
          "end_at": "2020-04-30T00:00:00.001Z",
          "start_at": "2020-03-30T00:00:00.001Z"
        }
      }
    }
  }'

The timestamp format must be RFC-3339 compliant.

To search for a customer profile created or updated at a specific point of time, set the start_at value slightly smaller than the end_at value. The following updated_at filter shows an example of how to specify a specific time when a customer profile was updated:

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "created_at": {
          "end_at": "2020-04-15T00:19:28.6Z",
          "start_at": "2020-04-15T00:19:28Z"
        }
      }
    }
  }'

Search by email address Permalink Get a link to this section

You can search customer profiles by email addresses with an exact or fuzzy filter. In any particular search, you can use either an exact filter or a fuzzy filter, but not both.

Exact search by email address Permalink Get a link to this section

To search for customer profiles by email address with an exact match, use the email_address filter as shown in the following search request example:

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "email_address": {
          "exact": "johndoe@hotmail.com"
        }
      }
    }
  }'

This returns all customer profiles whose email_address attribute holds the value of "johndoe@hotmail.com".

If you make an error in your query expression (for example, enter "johndoe@hotmail.com" as "johndoe@hotmail.co"), none of the previous results are returned. As shown in the following example, this behavior differs from the fuzzy search.

Fuzzy search by email address Permalink Get a link to this section

To search for customer profiles by email address with a fuzzy match, use the email_address filter as shown in the following search request example:

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "email_address": {
          "fuzzy": "john.doe"
        }
      }
    }
  }'

The query expression of john.doe is first tokenized into two tokens of john and doe. The customer profile containing the email address of johndoe@hotmail.com matches both tokens and is therefore returned in the search result.

A fuzzy search also serves as a partial search. For example, if you typed johndoe@hotmail.co by mistake in the fuzzy query filter, you still get customer profiles containing the email address johndoe@hotmail.com.

A fuzzy search provides you with great flexibility. For example, you can obtain the customer profiles containing johndoe@hotmail.com even with the following fuzzy filter:

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "email_address": {
          "fuzzy": "doe.john #com"
        }
      }
    }
  }'

Tokenization of the query expression of doe.john #com turns it into a three-token (john, doe, and com) query. The fuzzy search then selects customers profiles whose email addresses are john*doe@*.com or doe*john@*.com, where * stands for any valid email-address characters that can include, for example, ., _, or even a middle of name like joe.

Fuzzy search by email addresses can be a powerful option when used in a simple partial match or more advanced type-ahead user interfaces or embedded search experiences.

Search by phone number Permalink Get a link to this section

As with search by email address, you can search for customer profiles by phone number with an exact or fuzzy query filter. For a particular search, you can use either an exact filter or a fuzzy filter, but not both.

Searches by phone number are applicable only to customers whose phone numbers are stored in or imported into the seller's Customer Directory.

Exact search by phone number Permalink Get a link to this section

To conduct an exact search by phone number for customer profiles, you must specify in the search query a phone number in the E.164 format. The E.164 phone number format starts with a + (plus sign), followed by a country code and then a subscriber number. Spaces, dashes, or periods can be present in the phone number.

For example, a US phone number can use the following formats for the domestic version:

  • +12345678901

  • +1 234.567.8901

  • +1 (234) 567-8901

In these examples, the leading 1 after + is the national version of the North American country code. The international version is 001.

As an example, the following request shows an exact search by phone number for the US customer whose phone number is (234) 567-8901:

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "phone_number": {
          "exact": "+1 (234) 567-8901"
        }
      }
    }
  }'

The request can also take any other E.164 standard form.

If your seller account is outside the US, you might need to use international versions of an E.164-compliant phone number. In such cases, you can replace the phone number in the previous request body with any of the following formats:

  • +0012345678901

  • +001 234.567.8901

  • +001 (234) 567-8901

The leading numbers 001 after the + (plus sign) is the international version of the North American country code.

As part of the exact search operation, a match is performed after non-numeric characters other than the + (plus sign). For example, ., (, ), or - are removed from the provided query expression and the stored phone_number attribute value of the Customer object. Furthermore, the stored phone numbers are converted to the E.164 standard form of the national version (for example, +12345678901) and international version (such as, +0012345678901) so that you can use either the national or international version when specifying the query.

The following table shows more examples to summarize the behaviors of the exact search filter by phone_number:

Search queryMatched phone numbersUnmatched phone numbers
+1415-123-4567415.123.4567
415-123-4567
4151234567
(415) 123-4567
1(415)123-4567
+1(415)123-4567
123-4567
415-123.4568
+1(415)123.4567Save as aboveSame as above
+61 2 9876 543202 9876 5432
61 2 9876 5432
+61 2 9876 5432
61 (02) 9876 5432
9876 5432
(01) 09 75 83 51None. The query is not
of the E.164 form
33 01 09 75 83 51
01 09 75 83 51
+33 1 09 75 83 51
33 1 09 75 83 51

Fuzzy search by phone number Permalink Get a link to this section

Fuzzy search by phone number works in a similar way to fuzzy search by email addresses. A phone number is tokenized by removing non-numeric characters other than the leading + (plus sign). Matched customer profiles are those whose phone_number attribute has tokens that match all the provided tokens in the search query at least once in any order of tokens.

To use the fuzzy search by phone number, you can specify part of a customer's phone number. For example:

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "phone_number": {
          "fuzzy": "(234) 567-8901"
        }
      }
    }
  }'

As another example, if you use the following fuzzy search filter:

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "phone_number": {
          "fuzzy": "(234)567"
        }
      }
    }
  }'

You get all the US customers whose phone numbers use the following formats:

  • (234) 567-NNNN, (234) N56-7NNN, (234) NN5-67NN, (234) NNN-567N, (234) NNN-N567

  • (n23) 456-7NNN, (n23) 4N5-67NN, (n23) 4NN-567N, (n23) 4NN-N567

  • (nN2) 345-67NN, (nN2) 34N-567N, (nN2) 34N-N567

  • (nNN) 234-567N, (nNN) N23-4567, (nNN) 234-N567

  • (nNN) 567-234N, (nNN) N56-7243, (nNN) 567-N234

  • (nN5) 672-34NN, (nN5) 67N-234N, (nN5) 67N-N234

  • (n56) 723-4NNN, (n56) 7N2-34NN, (n56) 7NN-234N, (n56) 7NN-N234

  • (567) 234-NNNN, (567) N23-4NNN, (567) NN23-4NN, (567) NNN-234N, (567) NNN-N234

where "n" stands for any number between 1 and 9 and "N" stands for a number between 0 and 9. This example shows that the fuzzy phone_number filter matches a query expression with the stored phone_number attribute token by token, irrespective of the token order.

Fuzzy search by phone numbers can be powerful. As an example, you can use a fuzzy filter in a search to return likely candidates for a user to select as the user enters the phone number digit by digit, provided that you have defined metrics for the likeliness.

Search by reference ID Permalink Get a link to this section

When a Square customer profile is associated with an external entity in another system, the association is captured by the reference_id attribute of the Square Customer object.

Given the ID of an external entity, you can use the Square Customers API search by reference ID to determine the associated customer profiles in a Square seller's Customer Directory. To do so, you specify a reference_id filter when calling the SearchCustomers endpoint.

As with search by email address and by phone number, the reference_id search filter lets you query customer profiles with an exact or fuzzy match of the query expression against the reference_id attribute value.

Exact search by reference ID Permalink Get a link to this section

To search Square customer profiles by reference ID with an exact match, use a search-by-reference-Id filter as illustrated in the following example search request:

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "reference_id": {
          "exact": "ZGYZ-ABZG-97YX-XJ16"
        }
      }
    }
  }'

The response returns the Square customer profiles whose reference_id attribute value is exactly ZGYZ-ABZG-97YX-XJ16.

Fuzzy search by reference ID Permalink Get a link to this section

To perform a fuzzy search by reference IDs, use a fuzzy search filter as shown in the following example search filter:

Search Customers
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "reference_id": {
          "fuzzy": "ZGYZ-97YX"
        }
      }
    }
  }'

This filter returns the customer profiles whose reference_id attribute contains the ZGYZ and 97YX tokens at least once each and in any order.

As a string value, a reference ID is tokenized by removing non-alphanumeric characters. A customer profile is selected if each provided token is matched at least once against the profile's reference_id attribute, irrespective of the order of the tokens.

Fuzzy search by reference IDs can be powerful to help manage customer profiles. For example, with the help of a structured, multi-part identifier schema, you can use the fuzzy search to aid discovery of customer profiles in a structured way by matching part of a reference ID (for example, a prefix or suffix) or by querying reference IDs containing multiple tokens.

Search queryMatched reference_idsUnmatched reference_ids
XJ15XJ15-ABZG-97YX-ZGYZ,
ZGYZ-ABZG-97YX-XJ15
ZGYZ-ABZG-97YX-XJ16
NYC MNYC_M_35_JOHNSON
NYC27MURRAY
NYC-F-27_WILSON
SFO_M_35_THOMAS

Related topics Permalink Get a link to this section

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.