Activations

Activate (export) a completed audience to an endpoint connection, then list, read and delete activations - and preview the frequency filter an activation would apply before you create it. Activation is asynchronous: the create call returns immediately with a new id, and you poll the get endpoint until its datastreams report their output.

All activation endpoints are authenticated and JSON-only. Send Authorization: Bearer <token> and Accept: application/json on every call (plus Content-Type: application/json on the POST create). Reads use the read rate bucket (120 requests/min per caller); create and delete use the write bucket (30 requests/min per caller).

Create Activation

POST /api/v2/analyses/activations/create

Creates an activation that exports a custom audience owned by your company to a company-scoped endpoint connection. The audience must be 104 Completed and hold at least 500 unique devices - the audience read’s is_activation_allowed field tells you eligibility up front. When it is false, eligibility.reasons[0].message tells you why (device floor, Affinity device coverage, retention) and the activation endpoint returns 422 with the same message. The export is queued asynchronously; poll GET /api/v2/analyses/activations/{id} for its status and datastream output.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min). Optional: Idempotency-Key header (see below).

Body

Activation limits

Besides the frequency filter, an activation can deliver only part of the audience, with the same limits as the Audience Manager. Each needs its flag:

• Score range (score_limit with min_score and max_score), for Lookalike Model audiences. Scores run from 0 to 1 in bands of 0.1, and both bounds are band upper bounds: min_score 0.7 with max_score 1.0 exports the scores above 0.6, the top four bands. Both bounds are required, each one of 0.1, 0.2 … 1.0.
• Spend (affinity_spend_limit with affinity_spend_min and / or affinity_spend_max) and transactions (affinity_txn_limit with affinity_txn_min and / or affinity_txn_max), for audiences made of one Transactions (AffinityTransactions) dataset. They compare each person’s total spend, in dollars, and number of transactions across the transactions the audience matched, as each data provider reports them - the same totals as the Audience Manager’s Limit by Spend / Transactions. Spend includes its minimum and excludes its maximum; transactions include both ends. Leave a bound out to keep that end open. With both limits on, a person must pass both.

These limit what an activation delivers from the built audience. They are not the Transactions dataset’s spend_min / spend_max / txn_min / txn_max on Create Audience, which decide who enters the audience when it is built.

As with freq_limit, nothing is applied or dropped silently: bounds sent without their flag, a flag set to true without its bounds, and a limit on an audience it does not apply to are rejected with 422, and so are a bound that is not a finite number and a range that can match no one (a spend maximum of 0, a transaction maximum of 0). With a flag set to false, its bounds are still validated, then not applied. These ranges have no preview; filters on the activation read echoes what was applied.

{
  "audience_id": 93,
  "endpoint_connection_id": 12,
  "pricing_model_id": 3,
  "affinity_spend_limit": true,
  "affinity_spend_min": 50,
  "affinity_spend_max": 250,
  "affinity_txn_limit": true,
  "affinity_txn_min": 2
}

Caller-supplied credentials

credentials is an optional, write-only and sensitive map of string keys to simple values (strings, numbers or booleans). It is never logged, never echoed, and never returned in any response.

• The export is delivered with the partner input values you send: audience_inputs, and per stream inputs and service_account. The credentials stored on the endpoint connection are never copied into the activation.
• If the connection has no stored credentials and the caller supplies none, the activation is rejected with 422.

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" \
  -H "Idempotency-Key: <UNIQUE_KEY>" \
  -d '{
    "audience_id": 88,
    "endpoint_connection_id": 12,
    "pricing_model_id": 3,
    "description": "Q1 retail export",
    "datastreams": [
      { "id": 7, "status": true }
    ]
  }'

import requests

res = requests.post(
    "https://console.intuizi.com/api/v2/analyses/activations/create",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Idempotency-Key": "<UNIQUE_KEY>",
    },
    json={
        "audience_id": 88,
        "endpoint_connection_id": 12,
        "pricing_model_id": 3,
        "description": "Q1 retail export",
        "datastreams": [{"id": 7, "status": True}],
    },
)
activation_id = res.json()["data"][0]["id"]

const res = await fetch(
  "https://console.intuizi.com/api/v2/analyses/activations/create",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <YOUR_TOKEN>",
      "Content-Type": "application/json",
      Accept: "application/json",
      "Idempotency-Key": "<UNIQUE_KEY>",
    },
    body: JSON.stringify({
      audience_id: 88,
      endpoint_connection_id: 12,
      pricing_model_id: 3,
      description: "Q1 retail export",
      datastreams: [{ id: 7, status: true }],
    }),
  }
);
const activationId = (await res.json()).data[0].id;

$res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
    ->withHeaders(['Idempotency-Key' => '<UNIQUE_KEY>'])
    ->post('https://console.intuizi.com/api/v2/analyses/activations/create', [
        'audience_id' => 88,
        'endpoint_connection_id' => 12,
        'pricing_model_id' => 3,
        'description' => 'Q1 retail export',
        'datastreams' => [['id' => 7, 'status' => true]],
    ]);
$activationId = $res->json('data.0.id');

Index Exchange

For an Index Exchange connection, audience_inputs is index-matched to the connection’s partner.inputs: IX Segment ID, IX Segment Name, IX CPM USD, IX Access.

• IX CPM USD is required: a number from 0.01 to 99.99 with at most two decimals. It is the segment’s marketplace CPM on Index Exchange (USD, a flat CPM taken out of the buyer’s bid). It is not the price per identifier that Intuizi charges.
• IX Access is public or private. Default: public.
• A missing or invalid CPM, an invalid IX Access or IX Segment ID, and a CTV audience are refused with 422. The 422 message is exactly one of:
  • Index Exchange: IX CPM USD is required - the segment's marketplace CPM in USD, e.g. 1.35 (rate card: Location 1.35, Apps 1.10, Transactions 1.55).
  • Index Exchange: IX CPM USD must be a number between 0.01 and 99.99 with at most two decimals.
  • Index Exchange: IX Access must be 'public' or 'private'.
  • Index Exchange: CTV audiences cannot be delivered from the console. IX matches CTV on TV device ids, which console exports do not produce. Use the IX segment loader (intuizi-tools).
  • Index Exchange: IX Segment ID must be 1-255 characters with no whitespace.
• An Index Exchange connection needs no credentials. Its requires_credentials flag is false in Get Endpoint Connections. Only an organization that Index Exchange is enabled for can use it: for any other organization the connection is 404.
• Create Schedule applies the same rules to its activation block and returns the same 422 texts. A scheduled activation refreshes one segment: once a cycle has registered its segment (taxonomy: "uploaded"), later cycles deliver to that segment_id.
• The pricing model read shows a delivery_label, for example Device ID (MAID) -> ie_data/deviceifa or IP address -> ie_data/deviceip.
• Get Activation and the activation.completed webhook return delivery.index_exchange, or null when the worker wrote no Index Exchange result. Keys: segment_id, segment_name, match_key, folder, files, rows, taxonomy, delivered_at, cpm_usd, rate_source, access_requested, publication.
• publication keys: state, ix_segment_numeric_id, applied_cpm, applied_access, checked_at, handoff. The state value pending_manual means the file is delivered, and the fee and the publication are still applied by hand on Index Exchange.

Response

The response never includes the endpoint JSON, credentials, result links or device identifiers. created_by, partner and pricing_model are always objects (empty {} when they cannot be resolved). filters echoes the frequency filter the export applies (freq_min / freq_max only apply when freq_limit is true) and the activation limits under the body’s names, and filter_hash the preview hash the activation was created with (null when none was sent).

{
  "status": "success",
  "code": 201,
  "message": "Resource created successfully.",
  "data": [
    {
      "id": 501,
      "description": "Q1 retail export",
      "status": { "id": 100, "name": "Initiating" },
      "audience": { "id": 88, "name": "Coffee Buyers NYC" },
      "created_by": { "name": "Jane Doe", "email": "jane.doe@acme.example" },
      "project": { "id": 4, "name": "Retail 2025" },
      "partner": { "name": "Acme DSP", "description": "Programmatic DSP" },
      "pricing_model": { "name": "CPM", "price": 2.5 },
      "datastreams": [],
      "delivery": { "index_exchange": null },
      "filters": {
        "freq_limit": false, "freq_min": null, "freq_max": null,
        "score_limit": false, "min_score": null, "max_score": null,
        "affinity_spend_limit": false, "affinity_spend_min": null, "affinity_spend_max": null,
        "affinity_txn_limit": false, "affinity_txn_min": null, "affinity_txn_max": null
      },
      "filter_hash": null,
      "created_at": "2025-02-01 12:00:00",
      "updated_at": "2025-02-01 12:00:00"
    }
  ]
}

Idempotency

The optional Idempotency-Key header makes a create safe to retry. The key is caller-generated: any unique string up to 255 characters (a UUID v4 is typical), one per logical create - reuse it only when retrying that same request. The first request with a given key runs normally and the successful (2xx) response is cached per caller. A retry with the same key and the same body replays the stored response verbatim with an Idempotency-Replayed: true header, so no duplicate activation is created. A retry with the same key but a different body returns 409 Conflict. See Idempotency for the full replay semantics and the eight endpoints that honor the header.

Preview Activation

GET /api/v2/analyses/activations/preview

Read-only dry run of the frequency filter an activation would apply to a Completed audience. It returns the exact device count the Audience Manager shows as Limit Audience for the same Freq. Range: the audience’s stored frequency histogram (distinct visit days -> devices) summed over the inclusive [freq_min, freq_max] range, which is the same predicate the export applies. Alongside the count you get the histogram, its valid bounds, the audience total, the read-only recency window, the audience eligibility and a canonical filter_hash. Nothing is created, queued, exported, scheduled or billed - call it once per candidate range.

The audience must be 104 Completed and built with a frequency analysis - Visitation Frequency, Apps Frequency or Web Frequency in the Audience Manager, or the matching analyses key on Create Audience. Any other audience - a day-part frequency analysis, a lookalike or cohort, an audience built without a frequency analysis - is refused; the filter is never approximated. For a worked agent session see Preview, then Activate.

Recency is not an input: the date window is fixed by the audience definition and echoed read-only as recency. The preview accepts exactly the three parameters below; any other parameter is rejected.

Auth: bearer token + Accept: application/json. Rate limit: read bucket (120 requests/min).

Query parameters

curl "https://console.intuizi.com/api/v2/analyses/activations/preview?audience_id=88&freq_min=2&freq_max=5" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

import requests

res = requests.get(
    "https://console.intuizi.com/api/v2/analyses/activations/preview",
    params={"audience_id": 88, "freq_min": 2, "freq_max": 5},
    headers={"Authorization": "Bearer <YOUR_TOKEN>", "Accept": "application/json"},
)
preview = res.json()["data"][0]
filtered_count, filter_hash = preview["filtered_count"], preview["filter_hash"]

const params = new URLSearchParams({ audience_id: 88, freq_min: 2, freq_max: 5 });
const res = await fetch(
  `https://console.intuizi.com/api/v2/analyses/activations/preview?${params}`,
  { headers: { Authorization: "Bearer <YOUR_TOKEN>", Accept: "application/json" } }
);
const preview = (await res.json()).data[0];
const { filtered_count, filter_hash } = preview;

$res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
    ->get('https://console.intuizi.com/api/v2/analyses/activations/preview', [
        'audience_id' => 88,
        'freq_min' => 2,
        'freq_max' => 5,
    ]);
$preview = $res->json('data.0');

Response

filtered_count is exact. source_count is the audience total shown on the audience itself (an approximate distinct count, about 2.3% standard error) and histogram_total is the exact sum of the histogram, so the two can differ slightly; a [1, frequency_bounds.max] range returns histogram_total. as_of is when the audience’s stored results were last updated.

To activate exactly what was previewed, send the same audience_id, freq_min and freq_max with freq_limit: true and the returned filter_hash to Create Activation; the activation read then echoes both.

{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": [
    {
      "audience": {
        "id": 88,
        "name": "Coffee Buyers NYC",
        "status": { "id": 104, "name": "Completed" },
        "is_activation_allowed": true,
        "eligibility": {
          "allowed": true,
          "reasons": [],
          "metrics": { "unique_eids": 5100, "unique_scids": null, "eid_scid_ratio": null, "is_affinity": false }
        }
      },
      "dataset_type": "POI",
      "analysis_type": "frequency",
      "recency": [
        { "dataset_type": "POI", "start_date": "06/01/2026", "end_date": "07/31/2026" }
      ],
      "source_count": 5100,
      "histogram_total": 5000,
      "filtered_count": 2000,
      "frequency_bounds": { "min": 1, "max": 5 },
      "histogram": [
        { "index": 1, "counts": 3000 },
        { "index": 2, "counts": 1200 },
        { "index": 3, "counts": 500 },
        { "index": 5, "counts": 300 }
      ],
      "applied_filters": { "freq_limit": true, "freq_min": 2, "freq_max": 5 },
      "filter_hash": "sha256:4f9d0c7e1b2a8d3f6e5c4b3a2918f7e6d5c4b3a291807f6e5d4c3b2a19180706",
      "method": "histogram_sum",
      "as_of": "2026-08-01 06:12:44",
      "limitations": [
        "filtered_count is the exact number of devices whose distinct visit-day count inside the audience date window falls within [freq_min, freq_max] (both inclusive) - the same figure the Audience Manager shows as Limit Audience for that Freq. Range, and the same predicate the export applies.",
        "source_count is the audience total shown on the audience itself (an approximate distinct count, about 2.3% standard error); histogram_total is the exact sum of the frequency histogram, so the two can differ slightly. A [1, max] range returns histogram_total."
      ]
    }
  ]
}

List Activations

GET /api/v2/analyses/activations/index

Lists the activations owned by your company, most recent first, paginated.

Auth: bearer token + Accept: application/json. Rate limit: read bucket (120 requests/min).

Query parameters

curl "https://console.intuizi.com/api/v2/analyses/activations/index?per_page=25" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

import requests

res = requests.get(
    "https://console.intuizi.com/api/v2/analyses/activations/index",
    headers={"Authorization": "Bearer <YOUR_TOKEN>", "Accept": "application/json"},
    params={"per_page": 25},
)
page = res.json()["data"]

const res = await fetch(
  "https://console.intuizi.com/api/v2/analyses/activations/index?per_page=25",
  { headers: { Authorization: "Bearer <YOUR_TOKEN>", Accept: "application/json" } }
);
const page = (await res.json()).data;

$res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
    ->get('https://console.intuizi.com/api/v2/analyses/activations/index', ['per_page' => 25]);
$page = $res->json('data');

Response

{
  "status": "success",
  "code": 200,
  "message": "Resources fetched successfully.",
  "data": {
    "items": [
      {
        "id": 501,
        "description": "Q1 retail export",
        "status": { "id": 104, "name": "Completed" },
        "audience": { "id": 88, "name": "Coffee Buyers NYC" },
        "created_by": { "name": "Jane Doe", "email": "jane.doe@acme.example" },
        "project": { "id": 4, "name": "Retail 2025" },
        "partner": { "name": "Acme DSP", "description": "Programmatic DSP" },
        "pricing_model": { "name": "CPM", "price": 2.5 },
        "datastreams": [
          { "name": "match_file", "status": "success", "results": { "uri": "s3://bucket/path/output.csv" } }
        ],
        "created_at": "2025-02-01 12:00:00",
        "updated_at": "2025-02-02 09:30:00"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 25,
      "total": 1,
      "last_page": 1
    }
  }
}

Get Activation

GET /api/v2/analyses/activations/{id}

Retrieves a single activation by id.

The same read is also available at GET /api/v2/my-data/activations/{id} for backward compatibility; both return the identical response shape.

Auth: bearer token + Accept: application/json. Rate limit: read bucket (120 requests/min).

Path parameters

curl "https://console.intuizi.com/api/v2/analyses/activations/501" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

import requests

res = requests.get(
    "https://console.intuizi.com/api/v2/analyses/activations/501",
    headers={"Authorization": "Bearer <YOUR_TOKEN>", "Accept": "application/json"},
)
activation = res.json()["data"][0]

const res = await fetch(
  "https://console.intuizi.com/api/v2/analyses/activations/501",
  { headers: { Authorization: "Bearer <YOUR_TOKEN>", Accept: "application/json" } }
);
const activation = (await res.json()).data[0];

$res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
    ->get('https://console.intuizi.com/api/v2/analyses/activations/501');
$activation = $res->json('data.0');

Response

Each entry in datastreams[] carries a name, a status, an always-object results ({ "uri": "s3://..." } or { "gs://..." } when an output file is available, else {}), and an error string only when the datastream failed. The name is the stream’s internal slug, not the name Get Datastreams prints. The status is success for a delivered stream, failed when it failed, or skipped when it cannot run on the audience’s data, and the last two carry an error. Output URIs are normalized to their s3:// or gs:// form. Storage locations and URLs are removed from the error, and an error passed through from the query engine or cloud storage is cut to its first sentence, which states the reason.

{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": [
    {
      "id": 501,
      "description": "Q1 retail export",
      "status": { "id": 104, "name": "Completed" },
      "audience": { "id": 88, "name": "Coffee Buyers NYC" },
      "created_by": { "name": "Jane Doe", "email": "jane.doe@acme.example" },
      "project": { "id": 4, "name": "Retail 2025" },
      "partner": { "name": "Acme DSP", "description": "Programmatic DSP" },
      "pricing_model": { "name": "CPM", "price": 2.5 },
      "datastreams": [
        {
          "name": "match_file",
          "status": "success",
          "results": { "uri": "s3://bucket/path/output.csv" }
        }
      ],
      "delivery": { "index_exchange": null },
      "filters": {
        "freq_limit": true, "freq_min": 2, "freq_max": 5,
        "score_limit": false, "min_score": null, "max_score": null,
        "affinity_spend_limit": false, "affinity_spend_min": null, "affinity_spend_max": null,
        "affinity_txn_limit": false, "affinity_txn_min": null, "affinity_txn_max": null
      },
      "filter_hash": "sha256:4f9d0c7e1b2a8d3f6e5c4b3a2918f7e6d5c4b3a291807f6e5d4c3b2a19180706",
      "created_at": "2025-02-01 12:00:00",
      "updated_at": "2025-02-02 09:30:00"
    }
  ]
}

delivery.index_exchange is null unless the activation went to Index Exchange and the export reached it. An Index Exchange activation reads:

"delivery": {
  "index_exchange": {
    "segment_id": "intuizi_5495",
    "segment_name": "Intuizi - Brooks Running visitors L90",
    "match_key": "device_id",
    "folder": "ie_data/deviceifa",
    "files": ["s3://ix-bucket/ie_data/deviceifa/20261010120000.append.csv.gz"],
    "rows": 8297,
    "taxonomy": "uploaded",
    "delivered_at": "2026-10-10T12:00:41Z",
    "cpm_usd": "1.35",
    "rate_source": "operator",
    "access_requested": "public",
    "publication": {
      "state": "pending_manual",
      "ix_segment_numeric_id": null,
      "applied_cpm": null,
      "applied_access": null,
      "checked_at": null,
      "handoff": "In the Index Exchange UI > Segments > intuizi_5495 > Permissions & Fees: set Public, Standard fee 1.35 USD CPM. IX lists new segments about 2-5 h after delivery."
    }
  }
}

taxonomy is uploaded when the export registered a new segment, or skipped (existing segment) when the activation reused the IX Segment ID you supplied.

Delete Activation

POST /api/v2/analyses/activations/delete-by-id

Soft-deletes an activation.

Auth: bearer token + Accept: application/json + Content-Type: application/json. Rate limit: write bucket (30 requests/min).

Body

curl -X POST "https://console.intuizi.com/api/v2/analyses/activations/delete-by-id" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "id": 501 }'

import requests

res = requests.post(
    "https://console.intuizi.com/api/v2/analyses/activations/delete-by-id",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={"id": 501},
)

const res = await fetch(
  "https://console.intuizi.com/api/v2/analyses/activations/delete-by-id",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <YOUR_TOKEN>",
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({ id: 501 }),
  }
);

$res = Http::withToken('<YOUR_TOKEN>')->acceptJson()
    ->post('https://console.intuizi.com/api/v2/analyses/activations/delete-by-id', ['id' => 501]);

Response

{
  "status": "success",
  "code": 200,
  "message": "Resource deleted successfully.",
  "data": []
}