Skip to main content

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 involume 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 involume 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 found.
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 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.
Back to top