Customers API

Retrieve Customer Profiles

With customer profiles stored in a Square account, you have several options to find them and view detailed customer information using the Customers API. These options involve calling the ListCustomers, RetrieveCustomer, or SearchCustomers endpoint.

In this topic, you learn how to call the Customers API to retrieve customer profiles.

To retrieve and search for customer profiles, you need to have at least one customer profile in a targeted Square seller account. To use the API to create and manage customer profiles, see Keep Records of Customer Profiles.

Retrieve a customer profile by ID Permalink Get a link to this section

The RetrieveCustomer endpoint lets you get and view the details of a customer profile of a given ID. For example:

Retrieve Customer
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareup.com/v2/customers/{customer_id} \
  -H 'Square-Version: 2021-07-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

If successful, the operation returns a 200 response containing a single customer profile of the specified ID, as shown in the following response payload example:

{
  "customer": {
    "id": "TNQC0TYTWMRSFFQ157KK4V7MVR",
    "created_at": "2020-04-27T17:28:50.073Z",
    "updated_at": "2020-05-27T04:43:53Z",
    "given_name": "John",
    "family_name": "Doe",
    "company_name": "Company",
    "email_address": "john.doe@mail.com",
    "address": {
      "address_line_1": "123 Main Street",
      "locality": "City",
      "postal_code": "12345",
      "country": "US"
    },
    "phone_number": "12065551212",
    "birthday": "0000-01-01T00:00:00-00:00",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "THIRD_PARTY",
    "segment_ids": [
      "499XKDADA7682.REACHABLE"
    ],
    "version": 0
  }
}

If the customer profile does not exist in the directory, the Customers API returns a 404 NOT_FOUND error.

Retrieve a list of customer profiles Permalink Get a link to this section

When the customer ID is not known, you can call ListCustomers to retrieve all the customer profiles:

List Customers
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareup.com/v2/customers \
  -H 'Square-Version: 2021-07-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The successful result contains a list of customer profiles, which you can examine one by one to select one of your choice. Obviously, this way is practical only if the Square account has a small number of customers. When there is a large number of customer profiles, the operation returns them page by page. The page size is a preset limit, which has a default value of 100.

In a paged response, you get a token as the cursor attribute value, in addition to the customers list, as shown in the following example response:

{
  "customers": [
    ...
  ],
  "cursor": "2TTnuq0yRYDdBRSFF2XuFkgO1Bclt4ZHNI7YrFNeyZ6rL1WZXkdnLn10H8fBIwFKdKW1Af6ifRa"
}

To retrieve the next page of customer profiles, use the cursor returned in the response in your next request. For example, for a cURL request, you would append the query expression of ?cursor=2TTnuq0yRYDdBRSFF2XuFkgO1Bclt4ZHNI7YrFNeyZ6rL1WZXkdnLn10H8fBIwFKdKW1Af6ifRa to the URL of the next ListCustomers request. To retrieve all the customer profiles, repeat these steps, using the new cursor value for each new request, until no cursor is returned.

The ListCustomers endpoint is powerful in that it can be exhaustive, but might not be as practical especially when a Square account has a large customer base. A more efficient approach to retrieve customers without knowing their IDs is to use the SearchCustomers endpoint with one or more supported query filters. For more information, see Search for Customer Profiles.