You are viewing an old version of the API
Search customers

Searches the customer profiles associated with a Square account

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

Required permissions CUSTOMERS_READ

Request Body

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.

See the Pagination guide for more information.

limit
integer

A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored.

query
Customer​Query

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

Response Fields

Name Description
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.

See the Pagination guide for more information.

customers
Customer [ ]

An array of Customer objects that match a query.

errors
Error [ ]

Any errors that occurred during the request.

Examples

You are viewing an old version of the API
POST /v2/customers/search
cURL
  • cURL
  • Ruby
  • Python
curl https://connect.squareup.com/v2/customers/search \
  -X POST \
  -H 'Square-Version: 2019-11-20' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d '{
    "query": {
      "filter": {
        "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"
        }
      },
      "sort": {
        "field": "CREATED_AT",
        "order": "ASC"
      }
    },
    "limit": 2
  }'
Response JSON
{
  "customers": [
    {
      "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "created_at": "2018-01-23T20:21:54.859Z",
      "updated_at": "2018-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",
      "creation_source": "THIRD_PARTY"
    },
    {
      "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "created_at": "2018-01-30T14:10:54.859Z",
      "updated_at": "2018-03-08T18:25:54.859Z",
      "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",
      "creation_source": "THIRD_PARTY"
    }
  ],
  "cursor": "9dpS093Uy12AzeE"
}

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?