# 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](/concepts/async-model)); each create returns an id
immediately and the matching get endpoint carries the lifecycle status.

## Prerequisites

- A bearer token ([Authentication](/getting-started/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](/concepts/endpoint-connections) 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](/api/v2/cohorts/#post-apiv2analysescohortscreate).

```bash
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:

```json
{ "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}`](/api/v2/cohorts/#get-apiv2analysescohortsid)
until the status reaches `4` Completed, or `5` Not Available if the import
failed:

```bash
curl "https://console.intuizi.com/api/v2/analyses/cohorts/42" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"
```

```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](/concepts/webhooks) 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](/guides/create-an-audience)):

```bash
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}`](/api/v2/audiences/#get-apiv2analysesaudiencesid)
until the audience reaches its completed lifecycle status (see
[Status Codes](/concepts/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](/guides/activate-an-audience), and
[Deliver to a Partner Endpoint](/guides/deliver-to-a-partner-endpoint) covers the
partner-specific inputs:

Fetch your connection (and its pricing models) from
[Get Endpoint Connections](/api/v2/common/#get-apiv2analysesreferencecommonendpoint-connections)
first, then:

```bash
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}`](/api/v2/activations/#get-apiv2analysesactivationsid)
until the activation completes and your endpoint receives the audience.

## Next steps

- Field-level contracts: [Cohorts](/api/v2/cohorts),
  [Audiences]({{< relref "/api/v2/audiences" >}}),
  [Activations]({{< relref "/api/v2/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.