Overview
The Commitment API V4 enables publishers to create, update, and manage upfront commitments. Upfront commitments are advanced purchasing deals of advertising inventory that allow publishers and advertisers alike to coordinate budgets ahead of the television season. By creating upfront commitments for budget management, publishers can unify spend across direct sold, PG, and PMP for specific buyers, advertisers, and brands.
Use the Commitment API V4 to accomplish the following tasks:
- List details for one or all commitments in a network
- Create commitments with demand sources, split budgets, and custom pacings
- Update commitments' demand sources to add campaigns and deals
- Deactivate and re-activate existing commitments
Uniform Resource Identifiers (URI)
| Production URI |
|---|
https://api.freewheel.tv/services/v4/allocation/commitments |
| Staging URI |
|---|
https://api.stg.freewheel.tv/services/v4/allocation/commitments |
Workflows
Update a Commitment's Demand Sources
Publisher
- Requests all commitments in the network with GET.
FreeWheel
- Returns a list of commitments and their IDs.
Publisher
- Selects a commitment ID and uses it as a path parameter. Adds the new campaign and deal IDs to the
demand_sourcesobject. Sends the request with the PATCH method.
FreeWheel
- Updates the commitment with the new demand sources.
Attributes
The following attributes are used when creating or updating a commitment. For an interactive example, see Create a Commitment.
| Name | Type | Description |
|---|---|---|
| name | string | Name of the commitment |
| type | string | Type of the commitment Valid values: UPFRONT OTHER: Select Other if the commitment is not part of an upfront deal. |
| description | string | Description of the commitment |
| start_time | date-time | Start time of the commitment |
| end_time | date-time | End time of the commitment |
| global_agency_id | string | Global agency ID of the commitment |
| global_advertiser_id | string | Global advertiser ID of the commitment. This attribute can be empty if there is no advertiser. |
| global_brand_id | string | Global brand ID of the commitment. This attribute can be empty if there is no advertiser. |
| demand_sources | object | Object containing demand sources |
| budget | object | Object containing budget allocations |
| alert_threshold | double | Alert threshold of the commitment |
| custom_pacings | object | Object containing custom pacings |
| alert_email_delay | string | Alert email delay of the commitment in days. The maximum alert email delay is restricted by the start and end date. |
| owners | object | Object containing a list of owners |
| alert_pmp_threshold | double | Alert threshold of the commitment, for only PMP spend. Set the value to -1 if the commitment has no PMP-only performance curve configured. |
| dsp_synching_mode | string | Synching mode to the DSP Valid values: FULL: Send full commitment performance status to the DSP. PMP: Send PMP only performance status to the DSP. |
| pmp_custom_pacings | object | Object containing PMP custom pacings |
| alert_enabled | boolean | Must be TRUE to enable alerts. At least one owner email address must be configured when alert_enabled is true. |
Child Attributes
Demand Sources Object
| Name | Type | Description |
|---|---|---|
| deal_ids | array of strings | List of deal IDs to add as a demand source. Supported deal types include: - Programmatic Guaranteed (PG) - First Look - Biddable Guaranteed (BG) - Deal - Backfill |
| campaign_ids | array of strings | List of campaign IDs to add as a demand source |
Budget Object
| Name | Type | Description |
|---|---|---|
| total | double | The total budget of the commitment. This must be the sum of programmatic and direct sold budgets. |
| programmatic | double | The programmatic budget of the commitment. This must be the sum of the PMP and PG budgets if the user opts to split the programmatic budget. |
| direct_sold | double | The direct sold budget of the commitment. |
| pmp | double | The PMP budget of the commitment. |
| pg | double | The PG budget of the commitment. |
Custom Pacings Object
| Name | Type | Description |
|---|---|---|
| items | array of objects | List of custom pacings of the commitment. |
Items Object
| Name | Type | Description |
|---|---|---|
| delivery_percentage | double | Delivery percentage of the pacing |
| end_time | date-time | End time of the pacing |
Owners Object
| Name | Type | Description |
|---|---|---|
| items | array of objects | List of the owners of the commitment. Up to 10 owners may be included. |
Items Object
| Name | Type | Description |
|---|---|---|
| id | string | ID of the owner |
| name | string | Name of the owner |
| email_address | string | Email address of the owner |
PMP Custom Pacings Object
| Name | Type | Description |
|---|---|---|
| items | array of objects | List of PMP custom pacings of the commitment. |
Items Object
| Name | Type | Description |
|---|---|---|
| delivery_percentage | double | Delivery percentage of the pacing |
| end_time | date-time | End time of the pacing |