Skip to content
How to use
Cloud Cohort to Activation
.md

Cloud Cohort to Activation

The full journey from a file in your own cloud storage to a delivered audience, in three asynchronous steps:

  1. Create a cohort from a file in your AWS S3 or Google Cloud Storage, and poll it until it completes.
  2. Create an audience on that cohort, and poll it until it completes.
  3. Activate the audience to your endpoint connection.

Every step follows the same create-then-poll pattern (see The Async Model); each create returns an id immediately and the matching get endpoint carries the lifecycle status.

Prerequisites

  • A bearer token (Authentication).
  • A CSV, GZIP or Parquet file of identifiers in your own S3 or GCS bucket, readable by Intuizi’s processing account - your Account Manager can help set up the bucket access. No cloud credentials ever travel through this API.
  • An endpoint connection for the activation step.

Step 1 - Create the cohort

Point the create at your file, say which column holds the identifiers and what they are. The full field contract is in API Reference - Cohorts.

curl -X POST "https://console.intuizi.com/api/v2/analyses/cohorts/create" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Loyalty program members",
    "file_uri": "s3://my-bucket/exports/devices.csv",
    "file_format": "csv",
    "identifier_type": "maid",
    "identifier_column": "maid"
  }'

For a Google Cloud Storage file, use a gs:// URI instead - everything else is identical:

{ "file_uri": "gs://my-bucket/exports/devices.csv" }

The response returns the new cohort in status 2 Initiating. Poll GET /api/v2/analyses/cohorts/{id} until the status reaches 4 Completed, or 5 Not Available if the import failed:

curl "https://console.intuizi.com/api/v2/analyses/cohorts/42" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"
{ "data": { "id": 42, "status": { "id": 4, "name": "Completed" }, "total_eids": 184233 } }

total_eids is the number of resolved devices the import matched.

Instead of polling, a registered webhook pushes cohort.completed to your server the moment the import completes - and the same applies to the audience and activation steps below via audience.completed and activation.completed, or audience.failed and activation.failed when one of them stops at 107 Additional Info or a 4xx state. A failed import ends at 5 Not Available and sends cohort.failed. Keep a poll of Get Cohort only as the fallback for a delivery that exhausts its retries.

Step 2 - Create an audience on the cohort

A cohort-backed audience is a datasets entry of type Cohorts carrying the completed cohort_id - no dates, location or signal providers (see Create an Audience):

curl -X POST "https://console.intuizi.com/api/v2/analyses/audiences/create" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Loyalty members audience",
    "datasets": [{ "type": "Cohorts", "cohort_id": 42 }]
  }'

You can also combine the cohort with a second dataset and an operator - for example AND a POI dataset to keep only the loyalty members seen at your locations.

Poll GET /api/v2/analyses/audiences/{id} until the audience reaches its completed lifecycle status (see Status Codes), then read its results_count.

Step 3 - Activate the audience

Activate the completed audience to one of your endpoint connections - the full walkthrough is Activate an Audience, and Deliver to a Partner Endpoint covers the partner-specific inputs:

Fetch your connection (and its pricing models) from Get Endpoint Connections first, then:

curl -X POST "https://console.intuizi.com/api/v2/analyses/activations/create" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "description": "Loyalty members - delivery",
    "audience_id": 4711,
    "endpoint_connection_id": 12,
    "pricing_model_id": 3
  }'

Poll GET /api/v2/analyses/activations/{id} until the activation completes and your endpoint receives the audience.

Next steps

  • Field-level contracts: Cohorts, Audiences, Activations.
  • Refreshing the file later? Create a new cohort from the updated file and build a new audience on it - cohort imports are point-in-time snapshots.
Build a Lookalike ModelSubmit POI Data