Skip to main content
POST /api/v2/buyer/advertisers/{advertiserId}/test-cohorts Creates a test cohort — a flexible audience definition (geo, segment, zip code, or custom) that fills one arm of an incrementality test. Incrementality tests compare a TREATMENT cohort against a matched CONTROL.

​
Request

curl -X POST https://api.interchange.io/api/v2/buyer/advertisers/12345/test-cohorts \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "West Coast Treatment Group",
    "description": "Users in CA, OR, WA receiving full ad exposure",
    "cohortType": "geographic",
    "role": "TREATMENT",
    "definition": {
      "type": "geo_region",
      "regions": ["US-CA", "US-OR", "US-WA"]
    },
    "estimatedSize": 50000
  }'

​
Parameters

FieldTypeRequiredNotes
advertiserIdstringYesPath parameter — the owning advertiser
namestringYesCohort label (max 255)
cohortTypestringYesFree-form classification (e.g. geographic, demographic, behavioral)
definitionobjectYesTargeting definition. type is required (zip_code, user_segment, geo_region, custom); additional fields vary by type
descriptionstringNoFree-text description (max 1000)
roleenumNoTREATMENT, CONTROL, OBSERVATION (default TREATMENT)
estimatedSizeintegerNoSize estimate for power analysis

​
Response

{
  "id": "42",
  "advertiserId": "12345",
  "name": "West Coast Treatment Group",
  "description": "Users in CA, OR, WA receiving full ad exposure",
  "cohortType": "geographic",
  "role": "TREATMENT",
  "definition": { "type": "geo_region", "regions": ["US-CA", "US-OR", "US-WA"] },
  "estimatedSize": 50000,
  "isActive": true,
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-01-15T10:30:00Z"
}
The returned id is the cohortId you pass to Get, Update, and Delete.

​
Errors

  • 400 VALIDATION_ERROR — missing name, cohortType, or definition.type, or invalid role.
  • 404 NOT_FOUND — advertiserId does not exist or is not visible to the authenticated customer.
See Errors for the full error contract.

Measurement tasks

All measurement operations

Measurement overview

Pipeline, belief state, and concepts

List test cohorts

See defined cohorts