Booking API

Bookings

Bookings determine that what, where, how and when of ad delivery.

Get a booking

GET /v1/bookings/{bookingId}

Returns a single bookings' details by booking ID.

Request body

Parameter	In	Required	Type	Description
`InternalId`	path	Yes	integer	The booking's ID.

Response - 200

{
    "internalId": 22,
    "name": "Evnia 27M2N8500/01",
    "status": "ACTIVE",
    "lifetimeStatus": "STARTED",
    "positionId": 8,
    "positionName": "Home Halfpage",
    "formatId": 1,
    "formatName": "Halfpage",
    "startDate": "2026-07-04T22:00:00Z",
    "endDate": "2026-07-31T21:59:00Z",
    "creationDate": "2026-07-01T10:14:28Z",
    "lastEditedDate": "2026-07-15T13:42:55Z",
    "deliveryFactors": {
        "unit": "IMPRESSIONS",
        "volume": 1500000,
        "pricingType": "CPM",
        "price": 3.0,
        "budget": 4500.0,
        "currency": "EUR",
        "cpcOptimized": true
    },
    "activeDays": [
        "MONDAY",
        "TUESDAY",
        "THURSDAY",
        "FRIDAY",
        "SATURDAY",
        "SUNDAY"
    ],
    "creativeCount": 2,
    "frequencyLimits": [],
    "userFrequencies": [
        {
            "impressionsAmount": 10,
            "expiryInSeconds": 86400
        }
    ],
    "pacing": "FRONTLOADED",
    "deliveryMethod": "AUTO",
    "deliveryParameter": 0.0,
    "deliveryMultiples": "FREE",
    "campaignId": 17,
    "comment": null,
    "priority": null,
    "isBookedOnChannel": false,
    "excludePositionIds": [],
    "excludePublicationIds": [],
    "rtbEnabled": false,
    "targetExpressions": {},
    "autoDeliveryLimits": false,
    "bookingType": null,
    "startTime": "00:00:00",
    "endTime": "23:59:59"
}

Response codes

Status	Meaning
`200`	Booking found.
`400`	Bad request - invalid input or parameters.
`401` / `403`	Not authenticated / not allowed.
`404`	Not Found - Resource not found.
`500`	Internal Server Error - Unexpected failure.

Update a booking

PUT /v1/bookings/{bookingId}

Updates a single booking by booking ID.

Request body - UpdateBookingDto

Parameter	In	Required	Type	Description
`InternalId`	path	Yes	integer	The booking's ID.
`name`	body	Yes	string	Name of the campaign under which the booking is active.
`startDate`	body	Yes	string	Start date of the booking in date-time format `yyyy-mm-ddThh:mm:ssZ`
`endDate`	body	Yes	string	End date of the booking in date-time format `yyyy-mm-ddThh:mm:ssZ`
`activeDays`	body	Yes	string	Days of the week the booking is active. Possible values are: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY`
`deliveryFactors`	body	Yes	string, integer, number, boolean	Options that set the goals and to reach of the booking.
- `unit`	body	Yes	string	Unit of the to reach volume of the booking. Possible values are: `Impressions` or `Clicks`
- `volume`	body	No	integer	Amount of the unit to reach before the booking stops.
- `price`	body	No	number	Price of the booking set by pricing type.
- `budget`	body	No	number	Budget of the booking. When the budget is spent by the booking, delivery stops.
- `pricingType`	body	Yes	string	Method for determining ad spend via price. Possible values are: `CPM`, `CPC`, `CPP`, `CPL` or `ADM`
- `cpcOptimized`	body	No	boolean	Is CPC optimisation enabled for the booking: `true` or `false`
`mediaProduct`	body	Yes	integer	Position and format ID of the position of the booking.
- `positionID`	body	Yes	integer	Slot ID of the position.
- `formatID`	body	Yes	integer	ID of the format used in the position.
`frequencyLimits`	body	No	integer, string	Setting for capping delivery.
- `amount`	body	No	string	Amount of event to cap delivery by.
- `event`	body	No	string	Unit to measure for capping delivery. Either `IMPRESSIONS` or `CLICKS`
- `period`	body	No	string	Period where the cap is active, either `HOURLY` or `DAILY`. After the period has run out, the cap resets, either for the next hour or next day.
`pacing`	body	Yes	string	Delivery pacing options for the booking. Possible values are: `EVEN`, `FRONTLOADED`, `AS_FAST_AS_POSSIBLE`, `ROTATION`, `SHARE_OF_VOICE` or `ACCOUNT_SETTING`. Account setting takes the default pacing option set for the account
`deliveryParameter`	body	No	number	Sets the delivery percentage for SOV. Expressed as `1` for 100% of desired delivery share.
`comment`	body	No	string	Optional comment in the booking UI.
`rtbEnabled`	body	No	boolean	Can the booking go in competition with RTB bookings. Possible values are `true` or `false`
`priorityID`	body	No	integer	Priority of the booking expressed from `1` till `5`, If no value is chosen, the campaign priority will be picked.
`deliveryMultiples`	body	No	string	Extra exclusion settings for bookings. Possible values are: `EXCLUSIVE_ON_CAMPAIGN`, `EXCLUSIVE_ON_CREATIVE`, `ONE_AT_A_TIME`, `FREE`. Free is the default option and means no deliveryMultiples is set. ONE_AT_A_TIME refers to Exclusive on Advertiser.
`excludePositionIds`	body	No	integer	Position IDs to exclude from the selected media product (if it's a channel).
`excludePublicationIds`	body	No	integer	Publication IDs to exclude certain publication's inventory from the selected media product (if it's a channel)
`autoDeliveryLimits`	body	No	boolean	Activate auto delivery limits. Possible values are `true` or `false`.
`sponsoredProductIds`	body	No	string	ID's of the sponsored products attached to this booking.
`startTime`	body	No	string	Hour of the day when the booking will start delivery. formatted as `hh:mm:ss`.
`endTime`	body	No	string	Hour of the day when the booking will stop delivery (until the next day). formatted as `hh:mm:ss`.

Updating a booking

{
    "internalId": 22,
    "name": "Evnia 27M2N8500/01",
    "status": "ACTIVE",
    "lifetimeStatus": "STARTED",
    "positionId": 8,
    "positionName": "Home Halfpage",
    "formatId": 1,
    "formatName": "Halfpage",
    "startDate": "2026-07-04T22:00:00Z",
    "endDate": "2026-07-31T21:59:00Z",
    "creationDate": "2026-07-01T10:14:28Z",
    "lastEditedDate": "2026-07-15T13:42:55Z",
    "deliveryFactors": {
        "unit": "IMPRESSIONS",
        "volume": 2500000,
        "pricingType": "CPM",
        "price": 3.0,
        "budget": 5500.0,
        "currency": "EUR",
        "cpcOptimized": true
    },
    "mediaProduct": {
      "positionId": 8,
      "formatId": 1
    },
    "activeDays": [
        "MONDAY",
        "TUESDAY",
        "THURSDAY",
        "FRIDAY",
        "SATURDAY",
        "SUNDAY"
    ],
    "creativeCount": 2,
    "frequencyLimits": [],
    "userFrequencies": [
        {
            "impressionsAmount": 10,
            "expiryInSeconds": 86400
        }
    ],
    "pacing": "FRONTLOADED",
    "deliveryMethod": "AUTO",
    "deliveryMultiples": "FREE",
    "campaignId": 17,
    "comment": null,
    "priority": null,
    "isBookedOnChannel": false,
    "excludePositionIds": [],
    "excludePublicationIds": [],
    "rtbEnabled": false,
    "targetExpressions": {},
    "autoDeliveryLimits": false,
    "bookingType": null,
    "startTime": "00:00:00",
    "endTime": "23:59:59"
}

Response - 200

{
    "internalId": 22,
    "name": "Evnia 27M2N8500/01",
    "status": "ACTIVE",
    "lifetimeStatus": "STARTED",
    "positionId": 8,
    "positionName": "Home Halfpage",
    "formatId": 1,
    "formatName": "Halfpage",
    "startDate": "2026-07-04T22:00:00Z",
    "endDate": "2026-07-31T21:59:00Z",
    "creationDate": "2026-07-01T10:14:28Z",
    "lastEditedDate": "2026-07-31T12:02:18Z",
    "deliveryFactors": {
        "unit": "IMPRESSIONS",
        "volume": 2500000,
        "pricingType": "CPM",
        "price": 3.0,
        "budget": 5500.0,
        "currency": "EUR",
        "cpcOptimized": true
    },
    "activeDays": [
        "MONDAY",
        "TUESDAY",
        "THURSDAY",
        "FRIDAY",
        "SATURDAY",
        "SUNDAY"
    ],
    "creativeCount": 2,
    "frequencyLimits": [],
    "userFrequencies": [
        {
            "impressionsAmount": 10,
            "expiryInSeconds": 86400
        }
    ],
    "pacing": "FRONTLOADED",
    "deliveryMethod": "AUTO",
    "deliveryParameter": null,
    "deliveryMultiples": "FREE",
    "campaignId": 17,
    "comment": null,
    "priority": null,
    "isBookedOnChannel": false,
    "excludePositionIds": [],
    "excludePublicationIds": [],
    "rtbEnabled": false,
    "targetExpressions": {},
    "autoDeliveryLimits": false,
    "bookingType": null,
    "startTime": "00:00:00",
    "endTime": "23:59:59"
}

Response codes

Status	Meaning
`200`	Booking updated.
`400`	Bad request - invalid input or parameters.
`401` / `403`	Not authenticated / not allowed.
`404`	Not Found - Resource not found.
`409`	Conflict.
`422`	Unprocessable Entity
`500`	Internal Server Error - Unexpected failure.

Change the status of a booking

PUT /v1/bookings/{bookingId}/status

Change the status of a booking

Request body

Parameter	In	Required	Type	Description
`bookingId`	path	Yes	integer	The booking's ID.
/	body	Yes	string	Desired booking status. Possible values are: `ACTIVE`, `PAUSED`, `STOPPED`

Changing the status of a booking

"ACTIVE"

Response codes

Status	Meaning
`204`	Booking status updated.
`400`	Bad request - invalid input or parameters.
`401` / `403`	Not authenticated / not allowed.
`404`	Not Found - Resource not found.
`409`	Conflict.
`500`	Internal Server Error - Unexpected failure.

List bookings

GET /v1/bookings

List one or multiple bookings depending on filters chosen. Filtering is required for retrieving a list of bookings.

Request body

Parameter	In	Required	Type	Description
`campaignId`	parameters	No	integer	Campaign Id of the campaign whose bookings you want to list
`boookingId`	parameters	No	integer	Booking Ids of the booking(s) you want to list. IDs are comma separated.
`creativeId`	parameters	No	integer	ID of the creatives by which you want to return trafficked bookings. IDs are comma separated.
`limit`	parameters	No	integer	Pagination property to limit the number of returned targets.
`offset`	parameters	No	integer	Pagination property to offset the returned targets.
`search`	parameters	No	string	An url-encoded search string to apply to the list of bookings (ignoring case, on id and name).
`status`	parameters	No	string	Filter applied to one or more booking statuses. Possible values are: `ACTIVE`, `PAUSED`, `STOPPED`
`sortField`	parameters	No	string	Field that results should be sorted on. Possible values are: `INTERNAL_ID`, `NAME`, `STATUS`, `START_DATE`, `END_DATE`, `BOOKING_TYPE`
`sortDirection`	parameters	No	string	Sort direction to be applied. Possible values are: `ASC`, `DESC`

Response - 200

[
    {
        "internalId": 26,
        "name": "",
        "status": "ACTIVE",
        "lifetimeStatus": "COMPLETED",
        "positionId": 10,
        "positionName": "",
        "formatId": 1,
        "formatName": "Halfpage",
        "startDate": "2026-07-14T22:00:00Z",
        "endDate": "2026-07-31T21:59:59Z",
        "creationDate": "2026-07-15T13:44:13Z",
        "lastEditedDate": "2026-07-15T13:46:38Z",
        "deliveryFactors": {
            "unit": "IMPRESSIONS",
            "volume": 20000,
            "pricingType": "CPM",
            "price": 0.0,
            "budget": 0.0,
            "currency": "EUR",
            "cpcOptimized": false
        },
        "activeDays": [
            "MONDAY",
            "TUESDAY",
            "WEDNESDAY",
            "THURSDAY",
            "FRIDAY",
            "SATURDAY",
            "SUNDAY"
        ],
        "creativeCount": 1,
        "frequencyLimits": [],
        "userFrequencies": [],
        "pacing": "EVEN",
        "deliveryMethod": "AUTO",
        "deliveryParameter": 0.0,
        "deliveryMultiples": "FREE",
        "campaignId": 21,
        "comment": "",
        "priority": null,
        "isBookedOnChannel": true,
        "excludePositionIds": [],
        "excludePublicationIds": [],
        "rtbEnabled": false,
        "targetExpressions": {},
        "autoDeliveryLimits": false,
        "bookingType": null,
        "startTime": "00:00:00",
        "endTime": "23:59:59"
    },
    {
        "internalId": 29,
        "name": "",
        "status": "ACTIVE",
        "lifetimeStatus": "COMPLETED",
        "positionId": 15,
        "positionName": "",
        "formatId": 7,
        "formatName": "Portrait Screen",
        "startDate": "2026-07-28T22:00:00Z",
        "endDate": "2026-07-29T21:59:59Z",
        "creationDate": "2026-07-29T07:48:51Z",
        "lastEditedDate": "2026-07-29T07:49:31Z",
        "deliveryFactors": {
            "unit": "IMPRESSIONS",
            "volume": 0,
            "pricingType": "CPM",
            "price": 0.0,
            "budget": 0.0,
            "currency": "EUR",
            "cpcOptimized": false
        },
        "activeDays": [
            "MONDAY",
            "TUESDAY",
            "WEDNESDAY",
            "THURSDAY",
            "FRIDAY",
            "SATURDAY",
            "SUNDAY"
        ],
        "creativeCount": 0,
        "frequencyLimits": [],
        "userFrequencies": [],
        "pacing": "SHARE_OF_VOICE",
        "deliveryMethod": "SOV",
        "deliveryParameter": 1.0,
        "deliveryMultiples": "FREE",
        "campaignId": 21,
        "comment": "",
        "priority": null,
        "isBookedOnChannel": false,
        "excludePositionIds": [],
        "excludePublicationIds": [],
        "rtbEnabled": false,
        "targetExpressions": {},
        "autoDeliveryLimits": false,
        "bookingType": null,
        "startTime": "00:00:00",
        "endTime": "23:59:59"
    }
]

Response codes

Status	Meaning
`200`	Bookings returned successfully.
`400`	Bad request - invalid input or parameters.
`401` / `403`	Not authenticated / not allowed.
`404`	Not Found - Resource not found.
`409`	Conflict.
`500`	Internal Server Error - Unexpected failure.