Customer.io
v1.0.0
OpenAPI 3.1.0

Search for customers

US region

Client Libraries
Shell Curl

Search for customers

​

Provide a filter to search for people in your workspace. Your filter can filter people by segment (using the Segment ID) and attribute values; when you filter by attributes, you can use eq (matching an attribute value) or exists (matching when a person has the attribute). Use the and array, or array, and not object to create a complex filter. The not selector is an object that takes a single filter.

Returns arrays of identifiers and ids. In general, you should rely on the newer identifiers array, which contains more complete information about each person captured by the filter in your request, than the ids array, which only contains id values.

You can return up to 1000 people per request. If you want to return a larger set of people in a single request, you may want to use the /exports API instead.

Query Parameters
  • start
    Type: string

    The token for the page of results you want to return. Responses contain a next property. Use this property as the start value to return the next page of results.

  • limit
    Type: integer
    max:  
    1000

    The maximum number of results you want to retrieve per page.

Body
application/json
  • filter
    required

    Use and, or, and not to combine segment and attribute conditions. The top-level object accepts one property; nest groups for complex filters.

    Use and, or, and not to combine segment and attribute conditions. The top-level object accepts one property; nest groups for complex filters.

    • and
      Type: array object[]

      Match all conditions to return results.

Responses
  • application/json
  • 401

    Unauthorized request. Make sure that you provided the right credentials.

  • application/json
Request Example for post/v1/customers
curl 'https://api.customer.io/v1/customers?start=&limit=50' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "filter": {
    "and": [
      {
        "attribute": {
          "field": "email",
          "operator": "eq",
          "value": "{{customer.email}}"
        }
      },
      {
        "not": {
          "attribute": {
            "field": "source",
            "operator": "eq",
            "value": "website_newsletter"
          }
        }
      }
    ]
  }
}'

{
  "identifiers": [
    {
      "id": 1,
      "email": "person@example.com",
      "cio_id": 3000001
    },
    {
      "id": 2,
      "email": "second.person@exapmle.com",
      "cio_id": 3000002
    }
  ],
  "ids": [
    1,
    2
  ],
  "next": "MDox"
}

Returns an array of customers matching your filters.