🚧
Which Audiences?

Audience onboarding is supported only for audiences created via Backstage API (see above).

All other audience types are not supported:

Taboola Pixel Audiences.

Lookalike Audiences.

First Party Audiences managed by a DMP.

Examples

Sample ADD request:

POST /backstage/api/1.0/demo-advertiser/audience_onboarding/

{
  "operation": "ADD",
  "audience_id": 19,
  "integration_source": "Tealium",
  "identities": [
    {
      "cluster": [
        {
          "user_id": "dff8563ed00b29845659902068cdb3bd338690c605c0cad716477e3693dd0c4f",
          "type": "EMAIL_ID",
          "is_hashed": true
        }
      ]
    },
    {
      "cluster": [
        {
          "user_id": "e6ecbacdf49534c184514bd8fe0e71c55a1ddc9fd35f22f1263fcf7e5170f3e1",
          "type": "EMAIL_ID",
          "is_hashed": true
        },
        {
          "user_id": "00000000-00000000-01234567-89ABCDEF",
          "type": "DEVICE_ID",
          "is_hashed": false
        }
      ]
    }
  ]
}

Blank response with HTTP status 200.

📘
Sample request object

The above example adds identities for 2 users to audience 19.

Each cluster property groups all the User IDs (to be added) for 1 user.

For more detail about the request object schema, refer to the Fields section below.

🚧
Guidelines

For testing purposes, we recommend populating the audience with at least 1,000 users.

To cater for network latency, we suggest limiting each upload to 100k users.

🚧
If no errors occur, the API returns a blank response with HTTP status 200.

Sample REMOVE request:

POST /backstage/api/1.0/demo-advertiser/audience_onboarding/

{
  "operation": "REMOVE",
  "audience_id": 19,
  "integration_source": "Tealium",
  "identities": [
    {
      "cluster": [
        {
          "user_id": "dff8563ed00b29845659902068cdb3bd338690c605c0cad716477e3693dd0c4f",
          "type": "EMAIL_ID",
          "is_hashed": true
        }
      ]
    },
    {
      "cluster": [
        {
          "user_id": "e6ecbacdf49534c184514bd8fe0e71c55a1ddc9fd35f22f1263fcf7e5170f3e1",
          "type": "EMAIL_ID",
          "is_hashed": true
        }
      ]
    }
  ]
}

A successful request returns a blank response with HTTP status 200.

📘
Sample request object

The above example removes identities for 2 users from audience 19.

Each cluster property groups all the User IDs (to be removed) for 1 user.

For more detail about the request object schema, refer to the Fields section below.

🚧
If no errors occur, the API returns a blank response with HTTP status 200.

Example - Insufficient Fields:

POST /backstage/api/1.0/demo-advertiser/audience_onboarding/

{
  "operation": "ADD",
  "audience_id": 19,
  "integration_source": "Tealium",
  "identities": [
    {
      "cluster": [
        {
          "user_id": "e6ecbacdf49534c184514bd8fe0e71c55a1ddc9fd35f22f1263fcf7e5170f3e1",
          "type": "EMAIL_ID"
        }
      ]
    }
  ]
}

{
   "http_status": 400,
   "message": "Missing required field 'is_hashed'",
   "offending_field": "is_hashed"
}

Requirements

🚧
See the overview (above) for supported countries and audience types.