API ReferenceCommunity DiscussionAnnouncements
API ReferenceAnnouncementsCommunity Discussion
API ReferenceCommunity DiscussionAnnouncementsLog In
API Reference
Start typing to search…

Audience Targeting

Overview

Audience targeting allows you to target video campaigns based on user segments, contextual categories, and language preferences.

The restrictions object

The restrictions object contains an array of targeting rules that define which audiences your video campaign will target or exclude.

A sample object

{
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["12345", "67890"],
      "restriction_name": "UNIFIED_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CONTEXTUAL_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "LANGUAGE"
    }
  ]
}

type

Possible values:

typeDescription
"INCLUDE"Target only the specified audience segments
"EXCLUDE"Block the specified audience segments
"ALL"No restrictions (target all audiences)

value

An array of segment IDs, language codes, or other targeting values that correspond to the restriction_name. The array can contain multiple values for broader targeting or a single value for precise targeting.

restriction_name

Possible values:

UNIFIED_SEGMENTS(aka Marketplace audiences) Target specific audience segments from Taboola's marketplace.
CONTEXTUAL_SEGMENTSTarget based on contextual content categories.
LANGUAGETarget users based on language preferences.

Targeting

Marketplace audiences

Target specific audience segments (UNIFIED_SEGMENTS) from Taboola's marketplace.

Get available marketplace segments

GET /backstage/api/1.0/{account_id}/dictionary/marketplace_segments
📘

Marketplace segments

For more detail about fetching marketplace segments, see:

Segment types

Segment TypeDescription
DemographicAge, gender, income level
InterestHobbies, interests, behaviors
IntentPurchase intent, research behavior
CustomCustom audience segments

Set marketplace audience targeting

POST /backstage/api/1.0/{account_id}/video-campaigns/managed/{campaign_id}
{
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["12345", "67890"],
      "restriction_name": "UNIFIED_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CONTEXTUAL_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "LANGUAGE"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Audience Targeted Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["12345", "67890"],
      "restriction_name": "UNIFIED_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CONTEXTUAL_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "LANGUAGE"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

Contextual segments

Targeting based on contextual content categories (CONTEXTUAL_SEGMENTS).

Get available contextual segments

GET /backstage/api/1.0/{account_id}/dictionary/contextual_segments
📘

Contextual segments

For more detail about fetching contextual segments, see:

Contextual segment types

Segment TypeDescription
Content CategoryNews, sports, technology, etc.
TopicSpecific topics within categories
SentimentPositive, negative, neutral content
LanguageContent language preferences

Set contextual targeting

POST /backstage/api/1.0/{account_id}/video-campaigns/managed/{campaign_id}
{
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "UNIFIED_SEGMENTS"
    },
    {
      "type": "INCLUDE",
      "value": ["45678", "90123"],
      "restriction_name": "CONTEXTUAL_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "LANGUAGE"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Contextual Targeted Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "UNIFIED_SEGMENTS"
    },
    {
      "type": "INCLUDE",
      "value": ["45678", "90123"],
      "restriction_name": "CONTEXTUAL_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "LANGUAGE"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

Languages

Target users based on language preferences (LANGUAGE).

Get available languages

GET /backstage/api/1.0/resources/languages

Set language targeting

POST /backstage/api/1.0/{account_id}/video-campaigns/managed/{campaign_id}
{
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "UNIFIED_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CONTEXTUAL_SEGMENTS"
    },
    {
      "type": "INCLUDE",
      "value": ["en", "es", "fr"],
      "restriction_name": "LANGUAGE"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Multi-Language Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "UNIFIED_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CONTEXTUAL_SEGMENTS"
    },
    {
      "type": "INCLUDE",
      "value": ["en", "es", "fr"],
      "restriction_name": "LANGUAGE"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

Language codes

LanguageCodeDescription
EnglishenEnglish language
SpanishesSpanish language
FrenchfrFrench language
GermandeGerman language
PortugueseptPortuguese language

A complete example

{
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["12345", "67890"],
      "restriction_name": "UNIFIED_SEGMENTS"
    },
    {
      "type": "INCLUDE",
      "value": ["45678", "90123"],
      "restriction_name": "CONTEXTUAL_SEGMENTS"
    },
    {
      "type": "INCLUDE",
      "value": ["en", "es"],
      "restriction_name": "LANGUAGE"
    }
  ]
}

This example:

  • Targets specific audience segments (12345, 67890)
  • Includes contextual segments (45678, 90123)
  • Targets English and Spanish language users

Making updates

Update existing targeting

Example - pass a complete set of targeting options

POST /backstage/api/1.0/{account_id}/video-campaigns/managed/{campaign_id}
{
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["11111", "22222", "33333"],
      "restriction_name": "UNIFIED_SEGMENTS"
    },
    {
      "type": "EXCLUDE",
      "value": ["44444"],
      "restriction_name": "CONTEXTUAL_SEGMENTS"
    },
    {
      "type": "INCLUDE",
      "value": ["en", "de"],
      "restriction_name": "LANGUAGE"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Updated Audience Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["11111", "22222", "33333"],
      "restriction_name": "UNIFIED_SEGMENTS"
    },
    {
      "type": "EXCLUDE",
      "value": ["44444"],
      "restriction_name": "CONTEXTUAL_SEGMENTS"
    },
    {
      "type": "INCLUDE",
      "value": ["en", "de"],
      "restriction_name": "LANGUAGE"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}
👍

Best practice

For maximum clarity, we recommend passing the full set of targeting options.

📘

POST

To update a video campaign, use the POST operation.

Example 2 - pass a subset of targeting options

POST /backstage/api/1.0/{account_id}/video-campaigns/managed/{campaign_id}
{
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["11111", "22222"],
      "restriction_name": "UNIFIED_SEGMENTS"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Updated Audience Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["11111", "22222"],
      "restriction_name": "UNIFIED_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CONTEXTUAL_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "LANGUAGE"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}
📘

Passing a subset of targeting options

You can pass a restrictions object with a subset of the available targeting options - e.g. with "UNIFIED_SEGMENTS" only. The other targeting options will remain unaffected.

🚧

PATCH operation not supported

Audience targeting does not support a PATCH operation. For each targeting option you pass, make sure to include the full set of values.

Clear existing targeting

Remove all audience targeting restrictions by setting "type": "ALL" and "value": [] (empty array). You must provide a complete set of restrictions - an empty collection will result in an error.

POST /backstage/api/1.0/{account_id}/video-campaigns/managed/{campaign_id}
{
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "UNIFIED_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CONTEXTUAL_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "LANGUAGE"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Broad Audience Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "UNIFIED_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CONTEXTUAL_SEGMENTS"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "LANGUAGE"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": truenk line 
}

Best practices

📘

Targeting tips

  • Start with broad segments - Begin with broader audience segments and refine based on performance.
  • Test different combinations - Experiment with different audience segment combinations to find optimal performance.
  • Monitor segment performance - Track performance by segment to identify high-performing audiences.
  • Consider audience overlap - Be aware that some audience segments may overlap, affecting reach estimates.
  • Use contextual targeting - Combine audience targeting with contextual targeting for better precision.
  • Test language targeting - For international campaigns, test different language combinations

Related pages