New IO
POST {{campaign_url}}/advertisers/:advertiserId/insertionOrders
Create a new insertion order (IO)
You can create a new IO by sending this POST request. To define settings for your IO, open the body tab and edit the JSON object.
For DTO fields budget (nested structure schedules included) and impressionFrequency (nested structures personOrDeviceFrequencyCapDetails and householdFrequencyCapDetails included), see the corresponding DTO tables below to customize the data.
Request Body (Definitions)
*Optional element
| JSON Object Key | Description | Type |
|---|---|---|
| name | Name of this IO. | string |
| managerAccountId | Numeric ID of the account manager under which this IO is created. | integer |
| *externalInsertionOrderId | Third-party ID associated with the IO for third-party reporting purposes. | string |
| attributionService | Nexxen or third-party service that provides attribution data for this IO. Last-touch attribution (LTA): Credits only the user's last touchpoint for a conversion. Multi-touch attribution (MTA): Considers indirect actions that contribute to conversion. Allowed values: amobeeLta, doubleClickLta, visualIqMta, clearSaleingMta, atlasLta | string |
| customPackageMode | Number of levels in campaign hierarchy. Cannot be edited once the IO is created. Two-level: IO, line item Three-level: IO, package, line item Allowed values: twoLevel, threeLevel | string |
| pacingBasis | Pacing metric by which delivery should be controlled. Cannot be edited once the IO is created. Allowed values: budget, impression | string |
| budget (DTO) | Structure containing budget and flight schedule details. | DTO |
| *cpaGoalAmount (Required if pacing is set to autoAllocate) | Amount for a cost-per-action goal. Cannot be defined if cpcGoalAmount is defined. | float |
| *cpcGoalAmount (Required if pacing is set to autoAllocate) | Amount for a cost-per-click goal. Cannot be defined if cpaGoalAmount is defined. | float |
| creativeRotationEvent | Event that defines how delivery of two or more creatives associated with the IO should be rotated. Allowed values: clicks, actions | string |
| frequencyType | Frequency type (i.e., identity method) of the IO; defines what type of frequency cap can be applied. Device (cookie-based): Caps impressions at the device level, even if all devices belong to the same user. Person: Matches devices to owner (cross-device) & caps impressions at the person level. Household: Matches devices to household (cross-device) & caps impressions at the household level. Allowed values: device, person, household | string |
| *impressionFrequency (DTO) | Structure to define max number of IO impressions to serve a given user in the specified time frame. | DTO |
| status | Play status of this IO. Allowed values: play, pause, stop, archived | string |
budget DTO
| Key | Description | Type |
|---|---|---|
| asapDelivery | Indicates if the IO's entire budget should be spent as quickly as possible. | boolean |
| clientMargin | Client margin as a percent (%) value. | integer |
| pacing | Pacing at which the IO budget should be spent. See pacing rules below. Allowed values: even, daily, asap, evenImpression, autoAllocate, dailyImpression | string |
| pacingMultiplier | Additional factor that allows acceleration of budget pacing within the specified flights. | integer |
| schedules (Required, except when pacing is set to autoAllocate) | Flight or set of flights for this IO. | comma-separated array containing one or more schedule DTOs |
pacing Rules
| Option | Rules |
|---|---|
| even | Spreads the entire budget evenly across the IO flight. Required fields: startDate, endDate, budget |
| daily | Spends only the day's budget. Required fields: startDate, dailyCap |
| asap | Spends the IO budget as quickly as possible. Only one schedule is allowed in the schedules DTO. Required fields: startDate, budget Cannot be specified: endDate |
| evenImpression | Spends to achieve equal number of impressions per day. Required fields: startDate, endDate, budget, impressionCap |
| autoAllocate | Allows Nexxen algorithm to allocate budget towards campaign objects based on their performance. Schedules are not allowed. |
| dailyImpression | Spends only a specified number of impressions per day. Required fields: startDate, endDate, impressionCap |
schedule DTO
| Key | Description | Type |
|---|---|---|
| budget | Sum of the negotiated publisher budget, Nexxen's fees, and third-party costs. Either budget or dailyCap must be specified but not both. | float |
| dailyCap | Daily amount cap for the flight schedule. Either budget or dailyCap must be specified but not both. | long |
| startDate | Start date of the flight schedule. Must be in the format yyyy-mm-ddThh:mm:ss+offset. | string |
| endDate | End date of the flight schedule. Must be in the format yyyy-mm-ddThh:mm:ss+offset. | string |
| impressionCap | Maximum number of impressions to be served across the entire flight schedule. | long |
impressionFrequency DTO
personOrDeviceFrequencyCapDetails DTO
| Key | Description | Type |
|---|---|---|
| cap | Number of impressions to limit delivery to across the specified period. | integer |
| period | Number of minutes/hours/days used to define impression frequency. | integer |
| periodUnits | Unit of time used to define impression frequency. Allowed values: minutes, hours, days | string |
householdFrequencyCapDetails DTO
Values for these keys are only non-zero if frequencyType is household.
| Key | Description | Type |
|---|---|---|
| cap | Number of impressions to limit delivery to across the specified period. | integer |
| period | Number of minutes/hours/days used to define impression frequency. | integer |
| periodUnits | Unit of time used to define impression frequency. Allowed values: minutes, hours, days | string |
RESPONSES
status: Created
{"data":[{"id":"1608792488","marketId":"1","resourceType":"insertionOrder","status":"stopStartDate","name":"irene test IO","managerAccountId":"0123456","frequencyType":"household","impressionFrequency":{"personOrDeviceFrequencyCapDetails":{"cap":1,"period":1,"periodUnits":"days"},"householdFrequencyCapDetails":{"cap":3,"period":1,"periodUnits":"days"}},"cpaGoalAmount":5,"attributionService":"visualIqMta","budget":{"schedules":[{"startDate":"2022-09-27T13:41:30Z","endDate":"2022-10-27T13:41:30Z","budget":100,"impressionCap":10}]},"creativeRotationEvent":"clicks","advertiserId":"1608792487","createdAt":"2022-09-01T05:51:34Z","updatedAt":"2022-09-01T05:51:34Z","currency":"usd","customPackageMode":"threeLevel","pacingBasis":"impression"}],"errors":[]}