# Campaign API ## Campaigns Campaigns are a grouping of bookings and their associated creatives. ### Create a campaign ``` POST /v1/campaigns ``` Creates a new campaign. **Request body** - `CreateCampaignDto`

Field	Type	Required	Description
`name`	string	Yes	Display name of the company.
`advertiserId`	integer	No	ID of the advertiser/media partner you want to attach to this campaign.
`brandIds`	integer	No	IDs of the brands you want attached to this campaign.
`externalKey`	string	No	Your own external reference key.
`frequencyLimits`	integer, string	No	Frequency limit settings for the campaign.
`- amount`	integer	No	Limit of `event` per set `period` per `scope`.
`- event`	string	No	Set the limit to either `IMPRESSIONS` or `CLICKS`.
`- period`	string	No	Period for which the `amount` is applied as limit to the `event`. Either `DAILY` or `HOURLY`.
`- scope`	string	No	On which level the limit is applied. In this case always `CAMPAIGN`.
`priorityId`	integer	Yes	Priority of the campaign. 1 is the highest priority, with higher numbers representing lower priorities. By default clients have priorities 1 through 5 configured.
`campaignType`	string	Yes	Campaign type is either `FULL` for managed campaigns and, `GUARANTEED` or `AUCTIONED` for Self Service. In case of doubt with Self Service, pick `GUARANTEED`.
`reservationType`	string	Yes	Type of the campaign, either `CAMPAIGN`, `OFFER`, `Option` or `DRAFT` in the case of an Advendio campaign.
`deliveryFactors`	integer, string	No	Campaign goals expressed in`volume` of `unit`, or in `budget`.
`- unit`	string	No	Unit of the to reach `volume`. Either `IMPRESSIONS` or `CLICKS`.
`- volume`	integer	No	Amount of `unit` to reach as campaign goal.
`- budget`	integer	No	Campaign budget that can be spend before the delivery stops
`internalNote`	string	No	Fills in the Internal ID
`externalKey`	string	No	Fills in the External ID
`publisherId`	integer	No	ID of the publisher you want to associate with the campaign. `1` is the main publisher

**Creating a Campaign** ``` { "name": "Apitest", "poNumber": "95", "advertiserId": 1, "invoiceCompanyId": 1, "brandIds": [ 1 ], "frequencyLimits": [ { "amount": 1000, "event": "IMPRESSIONS", "period": "DAILY", "scope": "CAMPAIGN" } ], "priorityId": 1, "campaignType": "FULL", "reservationType": "CAMPAIGN", "deliveryFactors": { "unit": "IMPRESSIONS", "volume": 10000, "budget": 2000 }, "internalNote": "apitest", "externalKey": "testapi", "publisherId": 1 } ``` **Response** - 201 ``` { "internalId": 21, "name": "Apitest", "lifetimeStatus": "INCOMPLETE", "startDate": null, "endDate": null, "budget": "2000.00", "bookingBudgetSum": "0", "volume": 10000, "toReachUnit": "IMPRESSIONS", "advertiser": 1, "advertiserName": "Philips", "invoiceCompany": 1, "invoiceCompanyName": "Philips", "brands": [ 1 ], "mediaBrands": [ { "id": 1, "name": "Evnia" } ], "status": "CAMPAIGN", "priority": 1, "origin": "OTHER", "type": "FULL", "frequencyLimits": [ { "amount": 1000, "event": "IMPRESSIONS", "period": "DAILY", "scope": "CAMPAIGN" } ], "createdBy": 33, "creationDate": "2026-07-14T12:36:00Z", "lastEditedBy": null, "lastEditedDate": "2026-07-14T12:36:00Z", "externalKey": "testapi", "poNumber": "95", "validTill": null, "deliveryScheme": { "uniform": true }, "message": null, "creativeCount": 0, "internalNote": "apitest", "publisherId": 1 } ``` **Response codes**

Status	Meaning
`201`	Campaign created.
`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 campaigns ``` GET /v1/campaigns ``` Retrieves a list of campaigns. **Request body -** `CampaignDto`

Parameter	In	Required	Type	Description
`InternalId`	path	Yes	integer	The campaign's ID.
`limit`	query	Yes	integer	Max number of results.
`offset`	query	Yes	integer	Results to skip.
`includeInactive`	query	No	boolean	Include deactivated brands.
`search`	query	No	string	URL-encoded, case-insensitive match on name.

**Response** - 201 ``` [ { "internalId": 1, "name": "Example Display", "lifetimeStatus": "COMPLETED", "startDate": "2026-03-18T23:00:00Z", "endDate": "2026-04-30T21:59:59Z", "budget": "0.00", "bookingBudgetSum": "0.0", "volume": 0, "toReachUnit": "IMPRESSIONS", "advertiser": null, "advertiserName": null, "invoiceCompany": null, "invoiceCompanyName": null, "brands": [], "mediaBrands": [], "status": "CAMPAIGN", "priority": 1, "origin": "CLASSIC", "type": "FULL", "frequencyLimits": [], "createdBy": 2, "creationDate": "2026-03-19T13:46:14Z", "lastEditedBy": null, "lastEditedDate": "2026-03-19T13:46:14Z", "externalKey": null, "poNumber": "", "validTill": "1974-09-15T23:00:00Z", "deliveryScheme": { "uniform": true }, "message": null, "creativeCount": 2, "internalNote": "", "publisherId": 1 } ] ``` **Response codes**

Status	Meaning
`200`	Campaigns 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 campaigns ``` PUT /v1/campaigns/{campaignId} ``` Update a single campaign. **Request body** - `CreateCampaignDto`

Field	Type	Required	Description
`name`	string	Yes	Display name of the company.
`advertiserId`	integer	No	ID of the advertiser/media partner you want to attach to this campaign.
`brandIds`	integer	No	IDs of the brands you want attached to this campaign.
`externalKey`	string	No	Your own external reference key.
`frequencyLimits`	integer, string	No	Frequency limit settings for the campaign.
`- amount`	integer	No	Limit of `event` per set `period` per `scope`.
`- event`	string	No	Set the limit to either `IMPRESSIONS` or `CLICKS`.
`- period`	string	No	Period for which the `amount` is applied as limit to the `event`. Either `DAILY` or `HOURLY`.
`- scope`	string	No	On which level the limit is applied. In this case always `CAMPAIGN`.
`priorityId`	integer	Yes	Priority of the campaign. 1 is the highest priority, with higher numbers representing lower priorities. By default clients have priorities 1 through 5 configured.
`campaignType`	string	Yes	Campaign type is either `FULL` for managed campaigns and, `GUARANTEED` or `AUCTIONED` for Self Service. In case of doubt with Self Service, pick `GUARANTEED`.
`reservationType`	string	Yes	Type of the campaign, either `CAMPAIGN`, `OFFER`, `Option` or `DRAFT` in the case of an Advendio campaign.
`deliveryFactors`	integer, string	No	Campaign goals expressed in`volume` of `unit`, or in `budget`.
`- unit`	string	No	Unit of the to reach `volume`. Either `IMPRESSIONS` or `CLICKS`.
`- volume`	integer	No	Amount of `unit` to reach as campaign goal.
`- budget`	integer	No	Campaign budget that can be spend before the delivery stops
`internalNote`	string	No	Fills in the Internal ID
`externalKey`	string	No	Fills in the External ID
`publisherId`	integer	No	ID of the publisher you want to associate with the campaign. `1` is the main publisher

**Updating a campaign** ``` { "name": "Apitest", "poNumber": "95", "advertiserId": 1, "invoiceCompanyId": 1, "brandIds": [ 1 ], "frequencyLimits": [ { "amount": 1200, "event": "IMPRESSIONS", "period": "DAILY", "scope": "CAMPAIGN" } ], "priorityId": 1, "campaignType": "FULL", "reservationType": "CAMPAIGN", "deliveryFactors": { "unit": "IMPRESSIONS", "volume": 10000, "budget": 2000 }, "internalNote": "apitest", "externalKey": "testapi", "publisherId": 1 } ``` **Response** - 200 ``` { "internalId": 21, "name": "Apitest", "lifetimeStatus": "INCOMPLETE", "startDate": null, "endDate": null, "budget": "2000.00", "bookingBudgetSum": "0", "volume": 10000, "toReachUnit": "IMPRESSIONS", "advertiser": 1, "advertiserName": "Philips", "invoiceCompany": 1, "invoiceCompanyName": "Philips", "brands": [ 1 ], "mediaBrands": [ { "id": 1, "name": "Evnia" } ], "status": "CAMPAIGN", "priority": 1, "origin": "OTHER", "type": "FULL", "frequencyLimits": [ { "amount": 1200, "event": "IMPRESSIONS", "period": "DAILY", "scope": "CAMPAIGN" } ], "createdBy": 33, "creationDate": "2026-07-14T12:36:00Z", "lastEditedBy": null, "lastEditedDate": "2026-07-15T13:31:14Z", "externalKey": "testapi", "poNumber": "95", "validTill": null, "deliveryScheme": { "uniform": true }, "message": null, "creativeCount": 0, "internalNote": "apitest", "publisherId": 1 } ``` **Response codes**

Status	Meaning
`200`	Campaign 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.

### Delete campaigns ``` DELETE /v1/campaigns/{campaignId} ``` (soft)delete Campaign by ID by (soft)deleting all its Bookings. Is limited by state (draft, or non-started auction). **Request**

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

**Response codes**

Status	Meaning
`204`	Campaign deleted.
`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.

### Get a single campaign ``` GET /v1/campaigns/{campaignId} ``` Retrieves information on a single campaign. **Request body -** `CampaignDto`

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

**Response** - 201 ``` { "internalId": 17, "name": "Philips Evnia QD OLED", "lifetimeStatus": "COMPLETED", "startDate": "2026-07-04T22:00:00Z", "endDate": "2026-07-10T21:59:00Z", "budget": "6600.00", "bookingBudgetSum": "4500.0", "volume": 1500000, "toReachUnit": "IMPRESSIONS", "advertiser": null, "advertiserName": null, "invoiceCompany": null, "invoiceCompanyName": null, "brands": [], "mediaBrands": [], "status": "CAMPAIGN", "priority": 1, "origin": "MCB", "type": "FULL", "frequencyLimits": [ { "amount": 200000, "event": "IMPRESSIONS", "period": "HOURLY", "scope": "CAMPAIGN" }, { "amount": 500000, "event": "IMPRESSIONS", "period": "DAILY", "scope": "CAMPAIGN" } ], "createdBy": 1, "creationDate": "2026-07-01T09:35:02Z", "lastEditedBy": null, "lastEditedDate": "2026-07-01T09:35:02Z", "externalKey": null, "poNumber": null, "validTill": null, "deliveryScheme": { "uniform": true }, "message": null, "creativeCount": 2, "internalNote": "1.000.000 impressies\n6000 euro budget", "publisherId": 1 } ``` **Response codes**

Status	Meaning
`200`	Campaign 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 campaign status ``` POST /v1/campaigns/{campaignId}/status ``` Update the status of a guaranteed campaign.

Changes only go in the following direction: draft -> offer (-> option) -> campaign Any other changes to status (from example from *draft* to *campaign*) will result in an error.

**Request Body** - UpdateCampaignStatusRequest

Parameter	Required	Type	Description
`status`	Yes	string	Status you want to change the campaign to. Options are `DRAFT`, `OFFER`, `OPTION` or `CAMPAIGN`
`message`	No	string	Message to attach to the status change.

**Changing a campaigns status** ``` { "status": "OFFER", "message": "Apitest4" } ``` **Response** - 200 ``` { "internalId": 27, "name": "Apitest4", "lifetimeStatus": "PENDING", "startDate": "2026-07-19T22:00:00Z", "endDate": "2026-07-31T21:59:00Z", "budget": "0.00", "bookingBudgetSum": "1.0", "volume": 0, "toReachUnit": "IMPRESSIONS", "advertiser": 2, "advertiserName": "Logitech International S.A.", "invoiceCompany": null, "invoiceCompanyName": null, "brands": [ 2 ], "mediaBrands": [ { "id": 2, "name": "Logitech" } ], "status": "OFFER", "priority": 8, "origin": "MCB", "type": "GUARANTEED", "frequencyLimits": [], "createdBy": 30, "creationDate": "2026-07-20T13:01:12Z", "lastEditedBy": null, "lastEditedDate": "2026-07-22T07:40:52Z", "externalKey": null, "poNumber": "", "validTill": null, "deliveryScheme": { "uniform": true }, "message": "Apitest4", "creativeCount": 0, "internalNote": "", "publisherId": 1 } ``` **Response codes**

Status	Meaning
`200`	Campaign status update.
`400`	Bad request - invalid input or parameters.
`401` / `403`	Not authenticated / not allowed.
`404`	Not Found - Resource not found.
`422`	Unprocessable entity (status change not allowed by business rules, see callout)
`500`	Internal Server Error - Unexpected failure.

### Change the status of the bookings in a campaign ``` PATCH /v1/campaigns/{campaignId}/bookings/status ``` Conditionally update the status of the bookings in a campaign. **Request body**

Parameter	Required	Type	Description
/	Yes	string	Status you want to change the bookings to. Options are `ACTIVE`, `PAUSED`, or `STOPPED`

**Change the status of a campaigns' bookings** ``` "PAUSED" ``` **Response** - 200 ``` [ 28 ] ``` **Response codes**

Status	Meaning
`200`	Booking status changed.
`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.

### Get the booking shares of a campaign ``` GET /v1/campaigns/{campaignId}/booking-shares ``` Get Booking shares per booking ID for the campaign. **Request body** - BookingShareDto

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

**Response** - 200 ``` [ { "bookingId": 28, "share": 1.0 } ] ``` **Response codes**

Status	Meaning
`200`	Booking share 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.

### Get list of campaign types visible to user ``` GET /v1/campaigns/filterValues/types ``` Get a unique list of campaign types for campaign filtering. Only values used in campaigns visible to the users are returned. **Response** - 200 ``` [ "FULL", "GUARANTEED", "AUCTIONED" ] ``` **Response codes**

Status	Meaning
`200`	Booking share 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.

Parameter	Required	Type	Description
/	Yes	string	Status you want to change the bookings to. Options are `ACTIVE`, `PAUSED`, or `STOPPED`