--- title: "Search for customers" method: POST path: "/v1/customers" tags: ["Customers"] --- # Search for customers `POST /v1/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`](/integrations/api/app/tag/exports/) API instead. ## Query parameters - `start` string - `limit` integer ## Request body - object - `filter` union, required — Use `and`, `or`, and `not` to combine segment and attribute conditions. The top-level object accepts one property; nest groups for complex filters. - object - `and` object[] — Match *all* conditions to return results. - `or` SimpleAudienceFilter[] — Returns results matching *any* conditions. - union - object — Filter for people who belong to a segment. - … - object — filter for people who have an attribute or an attribute value. - … - `not` union — Returns results if a condition is false. While and/or support an array of items, `not` supports a single filter object. - object - `and` SimpleAudienceFilter[] — Match *all* conditions to return results. - … - object - `or` SimpleAudienceFilter[] — Match *any* condition to return results. - … - object - `segment` SegmentAudienceFilter — Provide the `id` of a segment containing people you want to search for. - … - object - `attribute` AttributeAudienceFilter — Filter your audience by attribute. - … - `segment` SegmentAudienceFilter — Provide the `id` of a segment containing people you want to search for. - `id` integer — The ID of the segment you want to return people from. - `attribute` AttributeAudienceFilter — Filter your audience by attribute. - `field` string, required — The name of the attribute you want to filter against. - `operator` 'eq' | 'exists', required — 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. - `value` string — The value you want to match for this attribute. You must include a value if you use the `eq` operator. - object - `or` object[] — Match *any* condition to return results. - `and` SimpleAudienceFilter[] — Returns results matching *all* conditions. - union - object — Filter for people who belong to a segment. - … - object — filter for people who have an attribute or an attribute value. - … - `not` union — Returns results if a condition is false. While and/or support an array of items, `not` supports a single filter object. - object - `and` SimpleAudienceFilter[] — Match *all* conditions to return results. - … - object - `or` SimpleAudienceFilter[] — Match *any* condition to return results. - … - object - `segment` SegmentAudienceFilter — Provide the `id` of a segment containing people you want to search for. - … - object - `attribute` AttributeAudienceFilter — Filter your audience by attribute. - … - `segment` SegmentAudienceFilter — Provide the `id` of a segment containing people you want to search for. - `id` integer — The ID of the segment you want to return people from. - `attribute` AttributeAudienceFilter — Filter your audience by attribute. - `field` string, required — The name of the attribute you want to filter against. - `operator` 'eq' | 'exists', required — 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. - `value` string — The value you want to match for this attribute. You must include a value if you use the `eq` operator. - object - `and` ComplexAudienceFilter[] — Match *all* conditions to return results. - `and` SimpleAudienceFilter[] — Returns results matching *all* conditions. - union - object — Filter for people who belong to a segment. - … - object — filter for people who have an attribute or an attribute value. - … - `or` SimpleAudienceFilter[] — Returns results matching *any* conditions. - union - object — Filter for people who belong to a segment. - … - object — filter for people who have an attribute or an attribute value. - … - `not` union — Returns results if a condition is false. While and/or support an array of items, `not` supports a single filter object. - object - `and` SimpleAudienceFilter[] — Match *all* conditions to return results. - … - object - `or` SimpleAudienceFilter[] — Match *any* condition to return results. - … - object - `segment` SegmentAudienceFilter — Provide the `id` of a segment containing people you want to search for. - … - object - `attribute` AttributeAudienceFilter — Filter your audience by attribute. - … - `segment` SegmentAudienceFilter — Provide the `id` of a segment containing people you want to search for. - `id` integer — The ID of the segment you want to return people from. - `attribute` AttributeAudienceFilter — Filter your audience by attribute. - `field` string, required — The name of the attribute you want to filter against. - `operator` 'eq' | 'exists', required — 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. - `value` string — The value you want to match for this attribute. You must include a value if you use the `eq` operator. - object - `or` ComplexAudienceFilter[] — Match *any* condition to return results. - `and` SimpleAudienceFilter[] — Returns results matching *all* conditions. - union - object — Filter for people who belong to a segment. - … - object — filter for people who have an attribute or an attribute value. - … - `or` SimpleAudienceFilter[] — Returns results matching *any* conditions. - union - object — Filter for people who belong to a segment. - … - object — filter for people who have an attribute or an attribute value. - … - `not` union — Returns results if a condition is false. While and/or support an array of items, `not` supports a single filter object. - object - `and` SimpleAudienceFilter[] — Match *all* conditions to return results. - … - object - `or` SimpleAudienceFilter[] — Match *any* condition to return results. - … - object - `segment` SegmentAudienceFilter — Provide the `id` of a segment containing people you want to search for. - … - object - `attribute` AttributeAudienceFilter — Filter your audience by attribute. - … - `segment` SegmentAudienceFilter — Provide the `id` of a segment containing people you want to search for. - `id` integer — The ID of the segment you want to return people from. - `attribute` AttributeAudienceFilter — Filter your audience by attribute. - `field` string, required — The name of the attribute you want to filter against. - `operator` 'eq' | 'exists', required — 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. - `value` string — The value you want to match for this attribute. You must include a value if you use the `eq` operator. - object - `segment` SegmentAudienceFilter — Provide the `id` of a segment containing people you want to search for. - `id` integer — The ID of the segment you want to return people from. - object - `attribute` AttributeAudienceFilter — Filter your audience by attribute. - `field` string, required — The name of the attribute you want to filter against. - `operator` 'eq' | 'exists', required — 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. - `value` string — The value you want to match for this attribute. You must include a value if you use the `eq` operator. - object — Filter for people who belong to a segment. - `segment` SegmentAudienceFilter — Provide the `id` of a segment containing people you want to search for. - `id` integer — The ID of the segment you want to return people from. - object — filter for people who have an attribute or an attribute value. - `attribute` AttributeAudienceFilter — Filter your audience by attribute. - `field` string, required — The name of the attribute you want to filter against. - `operator` 'eq' | 'exists', required — 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. - `value` string — The value you want to match for this attribute. You must include a value if you use the `eq` operator. ## Response `200` Returns an array of customers matching your filters. - object - `identifiers` object[] — An array of objects, where each object represents a customer. Each object contains identifiers for a customer. - `email` string, email, nullable, required — A person's email address, if set. - `id` string, nullable, required — A person's unique ID, if set. - `cio_id` string, required — A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers. - `ids` string[] — In general, you should use the `identifiers` array. This array contains identifiers for people captured in your filter. However, as of June 2021, some workspaces let you add people without an `id`. Entries without an `id` are empty strings in this array, where the `identifiers` array contains more complete information for each person captured in the filter. - `next` string — The `start` value for the next page of results. ## Other responses - `401` — Unauthorized request. Make sure that you provided the right credentials. - `429` — Your request is over the 10-per-second limit. --- [API](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference.md) · [All operations](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/customer/customer-io-journeys-api-reference/revisions/4b391af7cb06/schema)