Customer.io Customers API
Look up customer profiles, search for customers, and retrieve customer attributes and activity data.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/customer-io-customers-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
version: 1.0.0
title: Customer.io App Customers API
description: 'Our App API provides ways to trigger messages and retrieve information about people, campaigns, broadcasts, and more.
# Overview
The App API provides methods to send newsletters, transactional messages, and API-triggered broadcasts. You can create newsletters from scratch and update transactional messages and API-triggered broadcasts.
For transactional messages and API-triggered broadcasts, your payload acts as a message "trigger" and can contain `data` that you reference in your messages using liquid—`{{trigger.<data>}}`.
The other endpoints help you retrieve information about people, segments, campaigns, broadcasts, etc; it also lets you update campaign actions, messages, newsletter variants, etc. Aside from the [API-triggered broadcast](#triggerBroadcast) (1 per 10 seconds) and [Transactional](#sendEmail) (100 per second) endpoints, requests are limited to 10 per second.
# Use our Postman collection
We''ve generated a Postman collection to help you get started with our APIs.
If you fork this collection, you might want to disable the *Watch original collection* option. We automatically update our Postman collection whenever we release changes to our documentation, even if we don''t change our APIs—which happens daily! Rather than being flooded with Postman notifications, you can check out our [Release Notes](/release-notes/) for updates to our APIs.
**NOTE**: Postman endpoints default to our US APIs. If you''re in our European (EU) region, you''ll need to add `-eu` to the server variables (`track_api_url` and `app_api_url`).
[<img src="https://run.pstmn.io/button.svg" alt="Run In Postman" style="width: 128px; height: 32px;">](https://god.gw.postman.com/run-collection/23697545-2931c004-e63d-4cdc-bf4b-e685ba6da42d?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D23697545-2931c004-e63d-4cdc-bf4b-e685ba6da42d%26entityType%3Dcollection%26workspaceId%3Db886877f-fc09-475f-84fe-6221a98f4d18#?env%5BCustomer.io%20API%20Environment%5D=W3sia2V5IjoidHJhY2tfYXBpX3VybCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiJ0cmFjay5jdXN0b21lci5pbyIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBwX2FwaV91cmwiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiYXBpLmN1c3RvbWVyLmlvIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJzaXRlX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBpX2tleSIsInR5cGUiOiJzZWNyZXQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYmVhcmVyIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYnJvYWRjYXN0X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiaW1wb3J0X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiZW1haWxfYWRkcmVzcyIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InN1cHByZXNzaW9uX3R5cGUiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJjb2xsZWN0aW9uX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoic25pcHBldF9uYW1lIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoid2ViaG9va19pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InNlbmRlcl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImV4cG9ydF9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6Im1lc3NhZ2VfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJzZWdtZW50X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoibmV3c2xldHRlcl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImNvbnRlbnRfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJjYW1wYWlnbl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImFjdGlvbl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImN1c3RvbWVyX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidHJhbnNhY3Rpb25hbF9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRyaWdnZXJfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJmb3JtX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiaWRlbnRpZmllciIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImRldmljZV9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImRlbGl2ZXJ5X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9XQ==)
# Server addresses: US and EU
Customer.io hosts services in the United States (US) and European Union. Select the appropriate server address for your region.
| Region | Server Address |
| :-- | :-- |
| US | https://api.customer.io |
| EU | https://api-eu.customer.io |
# Authentication
All requests to the Customer.io App API use an [App API Key](#App-API-Key).
To authenticate, provide your key as a Bearer token in a HTTP Authorization header. You can create and manage your API keys—including keys with different scopes—in [your account settings page](https://fly.customer.io/settings/api_credentials?keyType=app). Each operation on this page references the authorization header it requires.
# Rate Limits
Most endpoints on this page are limited to 10 requests per second. The exceptions are:
* The [transactional email](#operation/sendEmail) endpoint is limited to 100 requests per second.
* The [API-triggered broadcast endpoint](#operation/triggerBroadcast) is limited to 1 request every 10 seconds.
**Rate limits are subject to change. We may adjust these thresholds to ensure stable performance for all customers.**
'
servers:
- url: https://api.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
tags:
- name: Customers
x-displayName: Profiles
description: 'Find profiles (referred to as "customers" in our APIs), their attributes, the segments they belong to, etc. Use the [track API](/api/track/#tag/Track-Customers) to add profiles to your workspace and assign their attributes.
'
paths:
/v1/customers:
servers:
- url: https://api.customer.io
description: This API uses bearer authorization, requiring a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
get:
parameters:
- name: email
description: The email address you want to search for.
in: query
required: true
schema:
type: string
format: email
summary: Get customers by email
operationId: getPeopleEmail
security:
- Bearer-Auth: []
description: 'Return a list of people in your workspace matching an email address.
If the email contains special characters like `+`, make sure you [percent-encode](/integrations/api/customerio-apis/#url-encoding) them in the query parameter. For example, use `jane%2Bnotifications%40example.com` instead of `jane+notifications@example.com`. Unencoded special characters can return empty results without an error.
'
tags:
- Customers
responses:
'200':
description: Returns an array of `results`; each result represents a person.
content:
application/json:
schema:
type: object
properties:
results:
type: array
description: A list of customers matching the email address in your query.
items:
type: object
required:
- cio_id
- id
- email
properties:
email:
type:
- string
- 'null'
format: email
description: A person's email address, if set.
example: hugh.mann@example.com
id:
type:
- string
- 'null'
description: A person's unique ID, if set.
example: 2
cio_id:
x-scalar-ignore: true
type: string
description: A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers.
example: a3000001
'401':
description: Unauthorized request. Make sure that you provided the right credentials.
'429':
description: Your request is over the 10-per-second limit.
x-codeSamples:
- lang: Shell + Curl
source: "curl --request GET \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --url 'https://api.customer.io/v1/customers?email=SOME_STRING_VALUE'"
- lang: Node + Native
source: "const http = require(\"https\");\n\nconst options = {\n \"method\": \"GET\",\n \"hostname\": \"api.customer.io\",\n \"port\": null,\n \"path\": \"/v1/customers?email=SOME_STRING_VALUE\",\n \"headers\": {}\n};\n\nconst req = http.request(options, function (res) {\n const chunks = [];\n\n res.on(\"data\", function (chunk) {\n chunks.push(chunk);\n });\n\n res.on(\"end\", function () {\n const body = Buffer.concat(chunks);\n console.log(body.toString());\n });\n});\n\nreq.end();"
- lang: Ruby + Native
source: 'require ''uri''
require ''net/http''
require ''openssl''
url = URI("https://api.customer.io/v1/customers?email=SOME_STRING_VALUE")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body'
- lang: Python + Python3
source: 'import http.client
conn = http.client.HTTPSConnection("api.customer.io")
conn.request("GET", "/v1/customers?email=SOME_STRING_VALUE")
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))'
- lang: Go + Native
source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.customer.io/v1/customers?email=SOME_STRING_VALUE\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
post:
parameters:
- name: start
in: query
required: false
description: 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.
schema:
type: string
- name: limit
in: query
required: false
description: The maximum number of results you want to retrieve per page.
schema:
type: integer
default: 50
maximum: 1000
summary: Search for customers
operationId: getPeopleFilter
security:
- Bearer-Auth: []
description: '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`](#tag/Exports) API instead.
'
tags:
- Customers
requestBody:
content:
application/json:
schema:
type: object
required:
- filter
properties:
filter:
x-scalar-ignore: true
title: Audience Filter
description: Use `and`, `or`, and `not` to combine segment and attribute conditions. The top-level object accepts one property; nest groups for complex filters.
oneOf:
- x-scalar-ignore: true
title: and
type: object
properties:
and:
type: array
description: Match *all* conditions to return results.
items:
type: object
properties:
or:
type: array
description: Returns results matching *any* conditions.
items:
x-scalar-ignore: true
anyOf:
- title: segment
description: Filter for people who belong to a segment.
type: object
properties:
segment:
x-scalar-ignore: true
title: segment
type: object
description: Provide the `id` of a segment containing people you want to search for.
properties:
id:
type: integer
description: The ID of the segment you want to return people from.
example: 4
- title: audience
type: object
description: filter for people who have an attribute or an attribute value.
properties:
attribute:
x-scalar-ignore: true
title: attribute
description: Filter your audience by attribute.
type: object
required:
- field
- operator
properties:
field:
type: string
description: The name of the attribute you want to filter against.
example: first_name
operator:
type: string
description: Determine how to evaluate criteria against the field—`exists` returns results if a person in the audience has the attribute; `eq` returns results if the audience has the attribute and the attribute has the `value` you specify.
enum:
- eq
- exists
value:
type: string
description: The value you want to match for this attribute. You must include a value if you use the `eq` operator.
example:
field: unsubscribed
operator: eq
value: true
not:
description: Returns results if a condition is false. While and/or support an array of items, `not` supports a single filter object.
oneOf:
- title: and
type: object
properties:
and:
type: array
description: Match *all* conditions to return results.
items:
x-scalar-ignore: true
anyOf:
- title: segment
description: Filter for people who belong to a segment.
type: object
properties:
segment:
x-scalar-ignore: true
title: segment
type: object
description: Provide the `id` of a segment containing people you want to search for.
properties:
id:
type: integer
description: The ID of the segment you want to return people from.
example: 4
- title: audience
type: object
description: filter for people who have an attribute or an attribute value.
properties:
attribute:
x-scalar-ignore: true
title: attribute
description: Filter your audience by attribute.
type: object
required:
- field
- operator
properties:
field:
type: string
description: The name of the attribute you want to filter against.
example: first_name
operator:
type: string
description: Determine how to evaluate criteria against the field—`exists` returns results if a person in the audience has the attribute; `eq` returns results if the audience has the attribute and the attribute has the `value` you specify.
enum:
- eq
- exists
value:
type: string
description: The value you want to match for this attribute. You must include a value if you use the `eq` operator.
example:
field: unsubscribed
operator: eq
value: true
- title: or
type: object
properties:
or:
type: array
description: Match *any* condition to return results.
items:
x-scalar-ignore: true
anyOf:
- title: segment
description: Filter for people who belong to a segment.
type: object
properties:
segment:
x-scalar-ignore: true
title: segment
type: object
description: Provide the `id` of a segment containing people you want to search for.
properties:
id:
type: integer
description: The ID of the segment you want to return people from.
example: 4
- title: audience
type: object
description: filter for people who have an attribute or an attribute value.
properties:
attribute:
x-scalar-ignore: true
title: attribute
description: Filter your audience by attribute.
type: object
required:
- field
- operator
properties:
field:
type: string
description: The name of the attribute you want to filter against.
example: first_name
operator:
type: string
description: Determine how to evaluate criteria against the field—`exists` returns results if a person in the audience has the attribute; `eq` returns results if the audience has the attribute and the attribute has the `value` you specify.
enum:
- eq
- exists
value:
type: string
description: The value you want to match for this attribute. You must include a value if you use the `eq` operator.
example:
field: unsubscribed
operator: eq
value: true
- title: segment
type: object
properties:
segment:
x-scalar-ignore: true
title: segment
type: object
description: Provide the `id` of a segment containing people you want to search for.
properties:
id:
type: integer
description: The ID of the segment you want to return people from.
example: 4
- title: attribute
type: object
properties:
attribute:
x-scalar-ignore: true
title: attribute
description: Filter your audience by attribute.
type: object
required:
- field
- operator
properties:
field:
type: string
description: The name of the attribute you want to filter against.
example: first_name
operator:
type: string
description: Determine how to evaluate criteria against the field—`exists` returns results if a person in the audience has the attribute; `eq` returns results if the audience has the attribute and the attribute has the `value` you specify.
enum:
- eq
- exists
value:
type: string
description: The value you want to match for this attribute. You must include a value if you use the `eq` operator.
example:
field: unsubscribed
operator: eq
value: true
segment:
x-scalar-ignore: true
title: segment
type: object
description: Provide the `id` of a segment containing people you want to search for.
properties:
id:
type: integer
description: The ID of the segment you want to return people from.
example: 4
attribute:
x-scalar-ignore: true
title: attribute
description: Filter your audience by attribute.
type: object
required:
- field
- operator
properties:
field:
type: string
description: The name of the attribute you want to filter against.
example: first_name
operator:
type: string
description: Determine how to evaluate criteria against the field—`exists` returns results if a person in the audience has the attribute; `eq` returns results if the audience has the attribute and the attribute has the `value` you specify.
enum:
- eq
- exists
value:
type: string
description: The value you want to match for this attribute. You must include a value if you use the `eq` operator.
example:
field: unsubscribed
operator: eq
value: true
- x-scalar-ignore: true
title: or
type: object
properties:
or:
type: array
description: Match *any* condition to return results.
items:
type: object
properties:
and:
type: array
description: Returns results matching *all* conditions.
items:
x-scalar-ignore: true
anyOf:
- title: segment
description: Filter for people who belong to a segment.
type: object
properties:
segment:
x-scalar-ignore: true
title: segment
type: object
description: Provide the `id` of a segment containing people you want to search for.
properties:
id:
type: integer
description: The ID of the segment you want to return people from.
example: 4
- title: audience
type: object
description: filter for people who have an attribute or an attribute value.
properties:
attribute:
x-scalar-ignore: true
title: attribute
description: Filter your audience by attribute.
type: object
required:
- field
- operator
properties:
field:
type: string
description: The name of the attribute you want to filter against.
example: first_name
operator:
type: string
description: Determine how to evaluate criteria against the field—`exists` returns results if a person in the audience has the attribute; `eq` returns results if the audience has the attribute and the attribute has the `value` you specify.
enum:
- eq
- exists
value:
type: string
description: The value you want to match for this attribute. You must include a value if you use the `eq` operator.
example:
field: unsubscribed
operator: eq
value: true
not:
# --- truncated at 32 KB (180 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/customer-io/refs/heads/main/openapi/customer-io-customers-api-openapi.yml