Skip to main content

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.

Create a booking

POST /v1/bookings

Request body

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.

campaignId

body Yes integer ID of the campaign you want to create the booking under.

bookingType

body Yes string Booking type. Possible values are: DISPLAY, IN_STORE, SPONSORED_PRODUCT

Create a booking

{
  "name": "apibooking",
  "startDate": "2026-08-03T12:28:35.965Z",
  "endDate": "2026-08-30T12:28:35.965Z",
  "activeDays": [
    "MONDAY",
    "TUESDAY",
    "WEDNESDAY",
    "THURSDAY",
    "FRIDAY",
    "SATURDAY",
    "SUNDAY"
  ],
  "deliveryFactors": {
    "unit": "IMPRESSIONS",
    "volume": 10000,
    "price": 5,
    "budget": 3000,
    "pricingType": "CPM",
    "cpcOptimized": false
  },
  "mediaProduct": {
    "positionId": 2,
    "formatId": 1 
  },
  "frequencyLimits": [
  ],
  "userFrequencies": [
    {
      "impressionsAmount": 0,
      "expiryInSeconds": 0
    }
  ],
  "pacing": "FRONTLOADED",
  "comment": "string",
  "rtbEnabled": true,
  "priorityId": 1,
  "deliveryMultiples": null,
  "excludePositionIds": [
  ],
  "excludePublicationIds": [
  ],
  "autoDeliveryLimits": true,
  "sponsoredProductIds": [
    "string"
  ],
  "startTime": "08:30:00",
  "endTime": "20:30:00",
  "campaignId": 21,
  "bookingType": "DISPLAY"
}

Response - 201

{
    "internalId": 31,
    "name": "apibooking",
    "status": "ACTIVE",
    "lifetimeStatus": "INCOMPLETE",
    "positionId": 2,
    "positionName": "",
    "formatId": 1,
    "formatName": "Halfpage",
    "startDate": "2026-08-03T12:28:35Z",
    "endDate": "2026-08-30T12:28:35Z",
    "creationDate": "2026-08-03T14:05:38Z",
    "lastEditedDate": "2026-08-03T14:05:38Z",
    "deliveryFactors": {
        "unit": "IMPRESSIONS",
        "volume": 10000,
        "pricingType": "CPM",
        "price": 5.0,
        "budget": 3000.0,
        "currency": "EUR",
        "cpcOptimized": false
    },
    "activeDays": [
        "MONDAY",
        "TUESDAY",
        "WEDNESDAY",
        "THURSDAY",
        "FRIDAY",
        "SATURDAY",
        "SUNDAY"
    ],
    "creativeCount": 0,
    "frequencyLimits": [],
    "userFrequencies": [
        {
            "impressionsAmount": 0,
            "expiryInSeconds": 0
        }
    ],
    "pacing": "FRONTLOADED",
    "deliveryMethod": "AUTO",
    "deliveryParameter": null,
    "deliveryMultiples": "FREE",
    "campaignId": 21,
    "comment": "string",
    "priority": {
        "id": 1,
        "name": "paying",
        "index": 0
    },
    "isBookedOnChannel": false,
    "excludePositionIds": [],
    "excludePublicationIds": [],
    "rtbEnabled": true,
    "targetExpressions": {},
    "autoDeliveryLimits": true,
    "bookingType": "DISPLAY",
    "startTime": "08:30:00",
    "endTime": "20:30:00"
}

Response codes

Status Meaning 201 Bookings created successfully.  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.
Back to top