Sign in

v1

latestOpenAPI 3.0.0Apache 2.02026-07-142008071.1 MB
Customers

SearchCustomers

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.

post/v2/customers/search

Request body

cursorstring

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.

limitinteger

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.

Example request

{
  "request_body": {
    "limit": 2,
    "query": {
      "filter": {
        "created_at": {
          "end_at": "2018-02-01T00:00:00-00:00",
          "start_at": "2018-01-01T00:00:00-00:00"
        },
        "creation_source": {
          "rule": "INCLUDE",
          "values": [
            "THIRD_PARTY"
          ]
        },
        "email_address": {
          "fuzzy": "example.com"
        },
        "group_ids": {
          "all": [
            "545AXB44B4XXWMVQ4W8SBT3HHF"
          ]
        }
      },
      "sort": {
        "field": "CREATED_AT",
        "order": "ASC"
      }
    }
  }
}

Response

Success

cursorstring

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.

Example response

{
  "cursor": "9dpS093Uy12AzeE",
  "customers": [
    {
      "address": {
        "address_line_1": "505 Electric Ave",
        "address_line_2": "Suite 600",
        "administrative_district_level_1": "NY",
        "country": "US",
        "locality": "New York",
        "postal_code": "10003"
      },
      "created_at": "2018-01-23T20:21:54.859Z",
      "creation_source": "DIRECTORY",
      "email_address": "james.bond@example.com",
      "family_name": "Bond",
      "given_name": "James",
      "group_ids": [
        "545AXB44B4XXWMVQ4W8SBT3HHF"
      ],
      "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "phone_number": "1-212-555-4250",
      "preferences": {
        "email_unsubscribed": false
      },
      "reference_id": "YOUR_REFERENCE_ID_2",
      "segment_ids": [
        "1KB9JE5EGJXCW.REACHABLE"
      ],
      "updated_at": "2020-04-20T10:02:43.083Z",
      "version": 7
    },
    {
      "address": {
        "address_line_1": "500 Electric Ave",
        "address_line_2": "Suite 600",
        "administrative_district_level_1": "NY",
        "country": "US",
        "locality": "New York",
        "postal_code": "10003"
      },
      "created_at": "2018-01-30T14:10:54.859Z",
      "creation_source": "THIRD_PARTY",
      "email_address": "amelia.earhart@example.com",
      "family_name": "Earhart",
      "given_name": "Amelia",
      "group_ids": [
        "545AXB44B4XXWMVQ4W8SBT3HHF"
      ],
      "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "note": "a customer",
      "phone_number": "1-212-555-4240",
      "preferences": {
        "email_unsubscribed": false
      },
      "reference_id": "YOUR_REFERENCE_ID_1",
      "segment_ids": [
        "1KB9JE5EGJXCW.REACHABLE"
      ],
      "updated_at": "2018-03-08T18:25:21.342Z",
      "version": 1
    }
  ]
}