Overview
With Equativ's TV booking API, broadcasters (TV channels) can sync their traditional TV booking information (replaceable ads) with Equativ. The TV booking information includes all the TV scheduling data describing the original TV ad break. The TV booking information is fetched asynchronously (prior to the ad call) and then leveraged by Equativ to do the addressable decisioning.
Related articles
Authentication
To use the TV booking API, you must create a clientId with the corresponding secret. Once created, each request to the API has to be enriched with the JSONWebToken(JWT) as bearer authorization scheme.
To get the token, send the following request to Equativ’s auth-server:
curl -d "client_id=<YOUR_CLIENTID>&client_secret=<YOUR_CLIENTSECRET>&grant_type=client_credentials&scope=<REQUESTED_SCOPE>" -H "Content-Type: application/x-www-form-urlencoded" -X POST https://smartadserver.fusionauth.io/oauth2/token
If the request is valid, the token is returned in the response body.
Endpoints and operations — Swagger
The TV Booking API provides the following endpoints:
- /api/Ad — to sync Ads
- /api/AdBreak — to sync AdBreaks
- /api/Csv — to sync TV Booking information using a csv file
The
Swagger interface shows all available operations, including contextual documentation. You can also use it to test requests.
Parameters
| Parameter | Necessity___ | Description |
|---|
| channelId | mandatory | the id of the channel for which you have the appropriate rights and for which you intend to create TV booking information |
| broadcastDate | mandatory | the date of the ad to be played; format: YYYYMMdd;
overnight ads can be attached to the previous date with the breakId adjusted accordingly; e. g. for 01:30 am on July 2nd, 2021, the according value would be: breakId 2530 and broadcastDate 20210701 |
| breakId | mandatory | the Id (integer) that represents the ad break in format HHMM (e. g. 1030) |
| sequenceId | mandatory | indicates the ad’s position in the ad break; values must be positive integer values starting with 1 (1, 2, 3, 4 etc.) |
| adDuration | mandatory | the duration of the ad in seconds which will be replaced by an ad with the exact same duration |
| addressableCondition | mandatory | indicates under which conditions the ad can be replaced; possible values:
- 0 - not addressable
- 1 - addressable without any condition
- 2 - addressable only for Single advertiser spot optimization (SASO); read more about this feature in Creating addressable TV insertions
- 3 - addressable only if the viewer is off target, i. e. if the viewer is not part of the ad’s targeted audience
|
| advertiserId | optional | the advertiser Id; needed for the Uniqueness feature; read more about this feature in Creating addressable TV insertions |
| campaignId | optional | the campaign id; needed for the Uniqueness feature; read more about this feature in Creating addressable TV insertions |
| creativeId | optional | the creative id; needed for the Uniqueness feature; read more about this feature in Creating addressable TV insertions |
| categoryId | optional | the category the advertiser belongs to (automotive, food etc.); needed for competitive exclusion |
| audienceTargetId | optional | the Id of the audience the ad is targeted to |
| spotId | optional | an Id (integer) used mainly by sales houses to identify a unique ad opportunity, i. e. a specific date/time slot that can be sold to show an ad; parameter is used for reporting purposes only (no impact on ad decisioning) |
