Skip to content
How to use
Activate an Audience
.md

Activate an Audience

Activate a completed audience to deliver it to a destination - an endpoint connection at a partner. Activation is asynchronous: you submit it, poll it to Completed, then read the result location from its datastreams.

Prerequisites

  • A bearer token (Authentication).
  • An audience in status 104 Completed (see Create an Audience) with at least 500 unique devices - the activation eligibility engine also checks Affinity device coverage, so an audience can fail activation for more than just the device floor (see Common rejections below). Check before activating: the audience read returns results_count, is_activation_allowed, and eligibility (reasons, notices
    • metrics). A notice does not block: audience_expired means the data window ended more than 90 days ago, so a MAID or IP pricing model is rejected while EID / SCID / HEM deliveries go through.
  • An endpoint connection, a pricing model, and the datastreams you want - read them with Working with Reference Data.

Pick the destination

You assemble three things from reference data:

  1. The endpoint connection (endpoint_connection_id) - your company’s saved link to a partner. This is the anchor: the platform resolves the partner, the available pricing, and the datastreams server-side from it.
  2. The pricing model (pricing_model_id) - one of the pricing options Get Pricing Models lists for that partner whose dataset_types include one of your audience’s dataset types. The activation takes its price.
  3. The datastreams - the output streams you want from the partner. Each one you want delivered is sent as { "id": <id>, "status": true }; a stream without status is not activated.
You cannot supply the partner identity yourself. The activation request prohibits partner_id, partner_name, and pricing_model - sending any of them returns 422. The partner and pricing are always derived from the endpoint connection, so a caller can never inject a different identity.

Credentials

The activation is delivered with the partner input values you send (see Partner inputs). The credentials stored on the endpoint connection are never copied into an activation. You can also supply credentials per call in the request body.

  • Required somewhere: if neither caller credentials nor stored credentials exist, the activation is rejected with 422.
  • Write-only: credentials are never returned in any create, read, or list response, and never logged.
Caller-supplied credentials are secret material. Send them only over HTTPS, never log them on your side, and never put them in a URL or query string. They are accepted in the request body and never returned by the API. See Endpoint Connections & Partners.

Partner inputs

Most partners also take account-detail inputs (an account id, a seat id, a folder prefix, and so on). Their definitions come from the endpoint connection - Get Endpoint Connections returns partner.inputs: each input’s name, type and whether it is required, in a fixed order.

  • Send the values as audience_inputs (top level) and/or datastreams[].inputs (per stream), index-matched to that definitions order. Per-stream values win; inputs flagged required must be supplied for every enabled datastream.
  • A file-type input is the service-account JSON key (GCP-style destinations). Send its decoded JSON as datastreams[].service_account - it is only accepted for partners that define a file input.

For the step-by-step version of this - reading the connection, its pricing models, its datastreams and its input definitions, then mapping your values onto them - see Deliver to a Partner Endpoint.

Optional: preview the frequency filter

If the audience was built with the Frequency analysis you can export only the devices seen on a given number of distinct days - the Audience Manager’s “Limit by Frequency” range. Before you activate, ask Preview Activation what a range would export:

GET /api/v2/analyses/activations/preview?audience_id=88&freq_min=2&freq_max=5

It returns filtered_count (exact, the same figure the Audience Manager shows as Limit Audience), the histogram and its frequency_bounds, the read-only recency window and a filter_hash. Nothing is created or billed, so preview as many ranges as you like. Then send the same freq_min / freq_max with freq_limit: true and that filter_hash in the create body below: the server recomputes the hash and refuses a request whose range or audience data no longer matches the preview. Recency is fixed by the audience definition - to count against another date window, build a new audience.

Request

POST /api/v2/analyses/activations/create

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": 17,
    "pricing_model_id": 3,
    "datastreams": [
      { "id": 5, "status": true },
      { "id": 6, "status": true }
    ],
    "credentials": {
      "api_key": "<PARTNER_API_KEY>",
      "api_secret": "<PARTNER_API_SECRET>"
    }
  }'
The Idempotency-Key header is optional and you generate it yourself - any unique string (a UUID v4 is typical), one per logical create. Reuse the same key only when retrying the exact same request: the retry replays the original response (Idempotency-Replayed: true) instead of launching a duplicate activation; the same key with a different body returns 409.

The exact, field-level contract - and the credentials field marked write-only / sensitive - is in the API Reference. This guide is the narrative; the reference is the contract.

Common rejections

StatusWhen
404audience_id or endpoint_connection_id was not found.
422No credentials available (neither caller-supplied nor stored).
422The audience fails an eligibility gate (is_activation_allowed is false): fewer than 500 devices or Affinity device coverage below 2x - the message is eligibility.reasons[0].message.
422The pricing model delivers an identifier an eligibility notice blocks: a MAID or IP pricing model on an audience whose data window ended more than 90 days ago (eligibility.notices[].code = audience_expired). Pick an EID / SCID / HEM pricing model or rebuild the audience with a recent window.
422A prohibited identity field (partner_id, partner_name, pricing_model) was sent.
422freq_min / freq_max were sent without an explicit freq_limit, or the filter_hash does not match the previewed range on the audience as it is stored now.
422An activation limit bound was sent without its flag (score_limit, affinity_spend_limit, affinity_txn_limit), a flag is true without its bounds, or a bound is out of range (a score that is not one of 0.1 … 1.0, a range that can match no one).
422A limit does not apply to the audience: a score range on an audience that is not a Lookalike Model, or spend / transaction limits on an audience that is not made of one Transactions dataset.

Poll until Completed

Activation runs asynchronously (see The Async Model). The create response gives you the new activation id; poll it until its lifecycle status reaches 104 Completed.

curl "https://console.intuizi.com/api/v2/analyses/activations/<ACTIVATION_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"
  • 100-103, 108, 109 - still processing. Poll again shortly.
  • 105 DataStreaming - results are being delivered to the destination. It comes before 104, so poll again.
  • 104 Completed - done, and the results are available.
  • 107 Additional Info - the export stopped and will not continue. Stop polling. Audience Manager shows the reason on the activation.
  • 4xx - an error state. Stop polling and inspect the response.

Instead of polling, a registered webhook pushes the activation.completed event to your server the moment the activation completes, or activation.failed the moment it stops at 107 or a 4xx state, with the same activation object as data. Keep a low-frequency poll as the fallback for a delivery that exhausts its retries.

Read the results

Once the activation reaches 104 (Completed), read the result location from the datastreams array in the response. 105 (DataStreaming) happens before 104 - it means the delivery is still in progress. Each datastream exposes a result URI:

{
  "status": "success",
  "code": 200,
  "message": "...",
  "data": [
    {
      "id": 91,
      "status": { "id": 104, "name": "Completed" },
      "datastreams": [ { "name": "standard_delivery", "status": "success", "results": { "uri": "s3://..." } } ]
    }
  ]
}

Pull data[0].datastreams[].results.uri to fetch the output. See Read an Activation for the full read response.

Activation delivers data to an external partner. Treat it as a live, billable, non-reversible delivery: once an activation is created it is queued for streaming to the destination. Activate only completed audiences, against the connection you intend, with the pricing model you intend.

Reference

Read an AudienceDeliver to a Partner Endpoint