post
https://backstage.taboola.com/backstage/api/1.0//audience_onboarding
Add (/remove) users to (/from) a First Party Audience.
See the overview (above) for supported countries and audience types.
Rate limit: Tier 1
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
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
clusterproperty 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
clusterproperty 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.
Rate limit
Rate limitTier 1. Has its own budget at a far more permissive tier than the rest of audience onboarding.
See Rate limits for the request allowance each tier carries.