Add/remove users

Add (/remove) users to (/from) a First Party Audience.
See the overview (above) for supported countries and audience types.

🚧

Which Audiences?

  1. Audience onboarding is supported only for audiences created via Backstage API (see above).
  2. All other audience types are not supported:

Examples

Sample ADD request:

POST /backstage/api/1.0/demo-advertiser/audience_onboarding/
{
   "operation": "ADD",
   "audience_id": 19,
   "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

  1. The above example adds identities for 2 users to audience 19.
  2. 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,
   "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

  1. The above example removes identities for 2 users from audience 19.
  2. 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,
   "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.

Language