Create a new cohort definition

(new)

Beta

Twilio Cohorts is currently available as a Private Beta product and the information contained in this document is subject to change. You acknowledge and agree that your use of Twilio Cohorts is subject to the terms of the Services in Private Beta. This means that some features are not yet implemented and others may be changed before the product is declared as Generally Available. Private Beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.

(warning)

Not a HIPAA Eligible Service or PCI Compliant

Twilio Cohorts is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI.

POST/preview/Cohorts

Base url: https://audiences.twilio.com (base url)

Creates a new cohort definition.

Required Fields

displayName: Human-readable name
storeType: Type of profile store
storeId: Profile store identifier
criteria: CEL query expression for matching profiles

Optional Fields

description: Free-text description
labels: Key-value labels for organizing and filtering cohorts

Rate Limiting

Rate-limited to 50 requests per minute per account.

Request

Authentication

Basic Auth

Headers

Property nameTypeRequiredDescription

Idempotency-Keystring

Optional

Client-provided idempotency key for safe request retries.

When provided, the server ensures that duplicate requests with the same key produce the same result without executing the operation multiple times.

Requirements:

Must be a non-empty string (max 128 characters)
Keys are retained for at least 24 hours
Scope: Account + Region combination
If a different payload is sent with the same key, returns 422 Unprocessable Content

If a request is replayed with the same idempotency key, the response will include the header Idempotent-Replayed: true.

Min length: 1Max length: 128

Request body

Encoding type:application/json

Schema

Property nameTypeRequiredDescriptionChild properties

displayNamestring

required

Human-readable name for the cohort

Example: Active US AdultsMin length: 1Max length: 255

descriptionstring

Optional

Optional description of the cohort

Example: US-based adults aged 18 and older who have an email addressMax length: 1000

storeTypeenum<string>

required

Type of profile store

Example: TWILIOPossible values:

TWILIO

storeIdstring

required

Unique identifier for the profile store

Example: mem_store_01h9d8r0vte3hz8tykdj329t7rPattern: ^mem_store_[a-zA-Z0-9]{26}$Min length: 36Max length: 36

criteriastring

required

A Boolean CEL (Common Expression Language) expression used to filter and select profiles.

Example: profile.trait.Contact.age >= 18 && profile.trait.Contact.country == "US" && has(profile.address.email)Max length: 2000

labelsobject

Optional

Labels for organizing and categorizing resources as key-value pairs.

Maximum of 10 key-value pairs
Maximum size of a label key is 128 characters
Maximum size of a label value is 256 characters
Keys and values must be non-empty and URL-safe: only unreserved characters (A-Z, a-z, 0-9, -, ., _, ~) are allowed. Labels are echoed back in the labels query parameter of the list endpoints, so anything you can store here can also be filtered on.
Keys cannot use the reserved twilio__ prefix

Example: {"environment":"production","campaign":"q1-2026"}Max properties: 10

Show labels properties

Responses

201400401403422429500

Created - Cohort definition created successfully

SchemaExample

Property nameTypeRequiredDescriptionChild properties

idstring

read-only

Optional

Unique identifier for the cohort following TTID format. Format: cmp_cohort_{uuidv7-encoded}

Example: cmp_cohort_01h9d8r0vte3hz8tykdj329t7rPattern: ^cmp_cohort_[a-zA-Z0-9]{26}$Max length: 100

displayNamestring

Optional

Human-readable name for the cohort

Example: Active US AdultsMin length: 1Max length: 255

descriptionstring

Optional

Optional description of the cohort

Example: US-based adults aged 18 and older who have an email addressMax length: 1000

storeIdstring

Optional

Unique identifier for the profile store

Example: mem_store_01h9d8r0vte3hz8tykdj329t7rPattern: ^mem_store_[a-zA-Z0-9]{26}$Min length: 36Max length: 36

storeTypeenum<string>

Optional

Type of profile store

Example: TWILIOPossible values:

TWILIO

criteriastring

Optional

A Boolean CEL (Common Expression Language) expression used to filter and select profiles.

Example: profile.trait.Contact.age >= 18 && profile.trait.Contact.country == "US" && has(profile.address.email)Max length: 2000

labelsobject

Optional

Labels for organizing and categorizing resources as key-value pairs.

Maximum of 10 key-value pairs
Maximum size of a label key is 128 characters
Maximum size of a label value is 256 characters
Keys and values must be non-empty and URL-safe: only unreserved characters (A-Z, a-z, 0-9, -, ., _, ~) are allowed. Labels are echoed back in the labels query parameter of the list endpoints, so anything you can store here can also be filtered on.
Keys cannot use the reserved twilio__ prefix

Example: {"environment":"production","campaign":"q1-2026"}Max properties: 10

Show labels properties

createdAtstring<date-time>

read-only

Optional

Timestamp when the cohort was created

Example: 2026-01-15T10:00:00Z

updatedAtstring<date-time>

read-only

Optional

Timestamp when the cohort was last updated

Example: 2026-01-15T10:00:00Z

Create a new cohort definition

1CREATE_COHORT_REQUEST_OBJ=$(cat << EOF
2{
3  "displayName": "Active US Adults",
4  "storeType": "TWILIO",
5  "storeId": "mem_store_01h9d8r0vte3hz8tykdj329t7r",
6  "criteria": "profile.trait.Contact.age >= 18 && profile.trait.Contact.country == \"US\" && has(profile.address.email)"
7}
8EOF
9)
10curl -X POST "https://audiences.twilio.com/preview/Cohorts" \
11--json "$CREATE_COHORT_REQUEST_OBJ" \
12-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response

1{
2  "id": "cmp_cohort_01h9d8r0vte3hz8tykdj329t7r",
3  "displayName": "Active US Adults",
4  "description": "US-based adults aged 18 and older who have an email address",
5  "storeType": "TWILIO",
6  "storeId": "mem_store_01h9d8r0vte3hz8tykdj329t7r",
7  "criteria": "profile.trait.Contact.age >= 18 && profile.trait.Contact.country == \"US\" && has(profile.address.email)",
8  "labels": {
9    "environment": "production",
10    "campaign": "q1-2026"
11  },
12  "createdAt": "2026-01-15T10:00:00Z",
13  "updatedAt": "2026-01-15T10:00:00Z"
14}