Adhese API This section details available Adhese API's. Where to find the Adhese APIs API Usage This page provides info on where to find detailed explanation on the Adhese APIs. See this guide on how to gain access to the APIs. It is intended as a starting point for developers and users who need to integrate with the API. Adhese stores its detailed API documentation in Swagger. Next to the documentation on Swagger, there will be explanations on every endpoint here on our documentation platform. Capabilities of Swagger Data retrieval – fetch structured data from the system. Data submission – send and store data on the platform. Schema definition – provides information on request/response objects, parameters, query strings, and headers. Configuration access – interact with specific configurations and settings. Monitoring & Diagnostics – review statuses, logs, and operational information. “Try It Out” feature – execute real API requests directly from the UI. For full details on all endpoints, see the Swagger UI. Where to find endpoints All available endpoints are documented in Swagger: The Swagger UI allows you to: Browse the list of endpoints. Review request/response schemas. Test endpoints directly in the browser. Where to find Swagger Swagger is publicly accessible under: https://{customer-url}/swagger-ui/index.html To access Swagger's interactive features, such as executing requests, please contact Support. OpenAPI Specification In addition to the interactive Swagger UI, the raw OpenAPI v3 specification can be retrieved in human-readable format (JSON). URL: https://{customer-url}/api/v3/api-docs/campaign-api This file defines: All endpoints, parameters, and request/response schemas Authentication requirements Metadata (titles, descriptions, tags) Typical use cases: Import into Postman to quickly generate a workspace. Client SDK generation via tools like Swagger Codegen or OpenAPI Generator. Validation & automation as part of CI/CD pipelines. Sending a request with Keycloak authentication Ensure the Use-Keycloak-Auth header is included and set to true (default value) optional field with api-version header should be left empty Once ready, you can test the endpoints directly in Swagger (provided you have the necessary permissions). How to get Access to the API In order to get access to the API's of Adhese, you require a service account, your service account lets your backend system call the Adhese API without a user login. It uses the OAuth 2.0 client credentials flow: you exchange a client ID and secret for a short-lived access token, then include that token in every API request. Prerequisites Your Adhese support agent will provide: Client ID — the identifier for your service account (e.g. my-company-integration) Client secret — treat this like a password; keep it out of source control Realm — your Adhese realm name (e.g. customer-name) Token endpoint POST https://{realm}.auth.adhese.eu/realms/{realm}/protocol/openid-connect/token Getting a token Send a POST request with Content-Type: application/x-www-form-urlencoded. curl curl -X POST \ "https://{realm}.auth.adhese.eu/realms/{realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=my-customer-integration" \ -d "client_secret=" \ -d "scope=adhese-api" Python import requests response = requests.post( "https://{realm}.auth.adhese.eu/realms/{realm}/protocol/openid-connect/token", data={ "grant_type": "client_credentials", "client_id": "my-customer-integration", "client_secret": "", "scope": "adhese-api", # or "adhese-api ratecard" }, ) token = response.json()["access_token"] Response { "access_token": "eyJhbGciOiJSUzI1NiIsInR5...", "token_type": "Bearer", "expires_in": 300, "scope": "adhese-api" } Scopes The scope parameter controls which permissions appear in your token. Your support agent configures which scopes are available to your service account. Scope Use when adhese-api Calling the Adhese API ratecard Calling the Ratecard API To request multiple scopes, separate them with a space: scope=adhese-api ratecard Only request scopes for the APIs you will actually call. Roles for a scope you did not request will not appear in the token even if they were granted. Token contents The access token is a signed JWT. When decoded, it contains your granted permissions under permissions.adhese-api and/or permissions.ratecard: { "permissions": { "adhese-api": [ "booking:view", "campaign:view", "creative:view" ] } } The exact roles listed depend on what your support agent has configured for your service account. Calling the API Pass the token as a Bearer in the Authorization header of every request: curl "https://api.adhese.org/..." \ -H "Authorization: Bearer " Token expiry Tokens expire after a while. Cache the token and reuse it across requests for its remaining lifetime. When it expires, request a new one using the same client credentials — the client credentials flow has no refresh token. A simple approach: track the expires_in value from the token response, subtract a small buffer (e.g. 30 seconds), and request a new token when that time has elapsed. 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.     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 Create a new booking based on the parameters entered in the request. 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 - CreateBookingDto { "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. Duplicate a booking POST /v1/bookings/{bookingId}/duplicate Creates a duplicate of the booking in the request prepended with Copy. State and external key are not copied over. Request body Parameter In Required Type Description InternalId path Yes integer The booking ID of the booking you want to copy. Response - 200 { "internalId": 32, "name": "Copy: Evnia 27M2N8500/01", "status": "PAUSED", "lifetimeStatus": "COMPLETED", "positionId": 8, "positionName": "Home Halfpage", "formatId": 1, "formatName": "Halfpage", "startDate": "2026-07-04T22:00:00Z", "endDate": "2026-07-31T21:59:00Z", "creationDate": "2026-08-05T15:20:49Z", "lastEditedDate": "2026-08-05T15:20:49Z", "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": 0, "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 Bookings successfully copied.  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. Retrieve bookings trafficked to creatives GET /v1/creatives/advar/{id}/bookings Retrieves bookings trafficked to a creative on the ID of an advar creative. Parameter In Required Type Description InternalId path Yes integer The creative ID of the creative who's trafficked bookings you want to retrieve. Response - 200 [ { "internalId": 32, "name": "Copy: Evnia 27M2N8500/01", "status": "PAUSED", "lifetimeStatus": "COMPLETED", "positionId": 8, "positionName": "Home Halfpage", "formatId": 1, "formatName": "Halfpage", "startDate": "2026-07-04T22:00:00Z", "endDate": "2026-07-31T21:59:00Z", "creationDate": "2026-08-05T15:20:49Z", "lastEditedDate": "2026-08-05T15:20:49Z", "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": 0, "frequencyLimits": [], "userFrequencies": [], "pacing": null, "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" }, { "internalId": 22, "name": "Evnia 27M2N8500/01", "status": "ACTIVE", "lifetimeStatus": "COMPLETED", "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-31T13:36:26Z", "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": 0, "frequencyLimits": [], "userFrequencies": [], "pacing": null, "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 Bookings successfully retrieved.  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. Retrieve creatives trafficked to a booking GET /v1/bookings/{bookingId}/creatives Retrieves all creatives trafficked to a booking by way of Booking ID. Parameter In Required Type Description InternalId path Yes integer The booking ID of the booking who's trafficked creatives you want to retrieve. Response - 200 [ { "creativeId": 18, "campaignId": 17, "creativeName": "27M2N8500/01 Rectangle 1", "formatId": 1, "advarTemplateName": "Image_FlexBanner.html", "sku": null, "lastEditedDate": "2026-07-01T10:16:32Z", "templateParameters": { "": "https://www.philips.be/c-p/27M2N8500_01/gamemonitor-qd-oled-gamemonitor", "": "QD OLED-gamemonitor" }, "templateFiles": { "2": { "fileName": null, "filePath": "https://demo-preview.adhese.org/pool/lib/18_2nd_1.png" } }, "lastEdited": 1782900992000 }, { "creativeId": 19, "campaignId": 17, "creativeName": "27M2N8500/01 Rectangle 2", "formatId": 1, "advarTemplateName": "Image_FlexBanner.html", "sku": null, "lastEditedDate": "2026-07-01T10:19:06Z", "templateParameters": { "": "https://www.philips.be/c-p/27M2N8500_01/gamemonitor-qd-oled-gamemonitor", "": "QD OLED-gamemonitor 2" }, "templateFiles": { "2": { "fileName": null, "filePath": "https://demo-preview.adhese.org/pool/lib/19_2nd_1.png" } }, "lastEdited": 1782901146000 }, { "creativeId": 27, "campaignId": 17, "creativeName": "Apitest advar banner ", "formatId": 1, "advarTemplateName": "Image_FlexBanner_recu.html", "sku": "", "lastEditedDate": "2026-08-06T07:35:49Z", "templateParameters": { "": "", "": "", "": "" }, "templateFiles": { "2": { "fileName": null, "filePath": "https://demo-preview.adhese.org/pool/lib/27_2nd_1.png" } }, "lastEdited": 1786001749000 } ] Response codes Status Meaning 200 Bookings successfully retrieved.  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. Creative API Creatives The images, banners, video, audio that are displayed as ads. List creatives GET /v1/creatives/advar Get a list of advar creatives filtered on at least one parameter. Request body Parameter In Required Type Description creativeId path Yes integer The creatives ID. campaignId parameter No integer Campaign ID of the campaign whose advar creatives you want to list. creativeId parameter No integer Comma separated list of creative ids you want to list. bookingId parameter No integer Comma separated list of booking ids you want to list creatives for. search parameter No string An url-encoded search string to apply to the list of creatives (ignoring case, on creative name). limit parameter No integer Pagination property to limit the number of returned targets. offset parameter No integer Pagination property to offset the returned targets. Response - 200 [ { "creativeId": 18, "campaignId": 17, "creativeName": "27M2N8500/01 Rectangle 1", "formatId": 1, "advarTemplateName": "Image_FlexBanner.html", "sku": null, "lastEditedDate": "2026-07-01T10:16:32Z", "templateParameters": { "": "https://www.philips.be/c-p/27M2N8500_01/gamemonitor-qd-oled-gamemonitor", "": "QD OLED-gamemonitor" }, "templateFiles": { "2": { "fileName": null, "filePath": "https://demo-preview.adhese.org/pool/lib/18_2nd_1.png" } }, "lastEdited": 1782900992000 }, { "creativeId": 19, "campaignId": 17, "creativeName": "27M2N8500/01 Rectangle 2", "formatId": 1, "advarTemplateName": "Image_FlexBanner.html", "sku": null, "lastEditedDate": "2026-07-01T10:19:06Z", "templateParameters": { "": "https://www.philips.be/c-p/27M2N8500_01/gamemonitor-qd-oled-gamemonitor", "": "QD OLED-gamemonitor 2" }, "templateFiles": { "2": { "fileName": null, "filePath": "https://demo-preview.adhese.org/pool/lib/19_2nd_1.png" } }, "lastEdited": 1782901146000 }, { "creativeId": 27, "campaignId": 17, "creativeName": "Apitest advar banner ", "formatId": 1, "advarTemplateName": "Image_FlexBanner.html", "sku": "", "lastEditedDate": "2026-08-10T07:29:49Z", "templateParameters": { "": "", "": "" }, "templateFiles": { "2": { "fileName": null, "filePath": "https://demo-preview.adhese.org/pool/lib/27_2nd_1.png" } }, "lastEdited": 1786346989000 } ] Response codes Status Meaning 200 Creatives found. 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. Update an advar creative PUT /v1/creatives/advar/{creativeId} Updates an advar creative by creative ID Request body Parameter In Required Type Description creativeId path Yes integer The creatives ID. Updating an advar creative { "campaignId": 17, "creativeName": "Apitest advar banner update", "sku": "string", "formatId": 1, "advarTemplateName": "Image_FlexBanner.html", "templateParameters": {}, "templateFiles": {} } Response - 200 { "creativeId": 27, "campaignId": 17, "creativeName": "Apitest advar banner update", "formatId": 1, "advarTemplateName": "Image_FlexBanner.html", "sku": "string", "lastEditedDate": "2026-08-10T13:36:10Z", "templateParameters": {}, "templateFiles": { "2": { "fileName": null, "filePath": "https://demo-preview.adhese.org/pool/lib/27_2nd_1.png" } }, "lastEdited": 1786368970000 } Response codes Status Meaning 200 Creative 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 a single creative GET /v1/creatives/advar/{id} Returns a single creatives' details by creative ID Request body Parameter In Required Type Description id path Yes string Id of the creative you want to return Response - 200 { "creativeId": 30, "campaignId": 27, "creativeName": "Copy of Apitestpotmancreative", "formatId": 1, "advarTemplateName": "Image_FlexBanner.html", "sku": null, "lastEditedDate": "2026-09-08T08:00:13Z", "templateParameters": { "": "https://example.com", "": "My creative alt text" }, "templateFiles": { "2": { "fileName": null, "filePath": "https://demo.preview.adhese.eu/pool/lib/30_2nd_1.jpg" } }, "readonly": false, "lastEdited": 1788854413000 } Response codes Status Meaning 200 Creative 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 the preview links of a single creative GET /v1/creatives/advar/{id}/preview-links Lists the preview links associated with the requested creative. Parameter In Required Type Description creativeId path Yes integer The creatives ID. Response - 200 [ "https://adhese.eu?adhesePreviewCreativeId=22:e0c0a655-3f46-4231-850c-acfa0ed976de&adhesePreviewSlotId=14&adhesePreviewWidth=16&adhesePreviewHeight=9&adhesePreviewTemplateFile=preview.html&adhesePreviewCreativeKey&adhesePreviewCreativeTemplate=landscape" ] Response codes Status Meaning 200 Preview links retrieved. 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. Upload a creative file POST /v1/creatives/file Uploads a creative file to temporary storage to use when uploading an advar creative. Request body Parameter In Required Type Description Content-Disposition header Yes string Contains the file name and is filled in accordingly attachment; filename=filename.extension Use-Keycloak-Auth header Yes boolean Default is true Content-Type header Yes string application/octet-stream formatId parameter Yes string The ID of the format that will be associated with the creative. key parameter No string Creative file index written as ordinal number (e.g. 2nd) with the exception of 1, which has key "main" (but is not used in advar creatives). Default value is  main File contents body Yes binary data File contents as binary data to be uploaded to temporary storage. Response - 201  { "filePath": "/home/adhese/www/docker.adhese.org/tmp/file_by_user_1_9072608199649672610.jpg" } Response codes Status Meaning 201 File uploaded successfully. 400 Bad request - invalid input or parameters. 401 /  403 Not authenticated / not allowed. 404 Not Found - Resource not found. 409 Conflict. 415 Unsupported Media Type. 422 Unprocessable entity. 500 Internal Server Error - Unexpected failure. Create an advar creative POST /v1/creatives/advar Creates an advar creative under the chosen campaign. Request body Parameter In Required Type Description campaignId body Yes string Id of the campaign under wich you want to create a creative. creativeName body Yes string The ID of the format that will be associated with the creative. sku body No string SKU of the product related to the product. formatId body Yes integer ID of the format that will be used for the creative. advarTemplateName body Yes string Name of the advar template that will be used. templateParameters body No string Additional parameters related to the advar. To be filled in as the macro of the parameter such as or . templateFiles body No string Creative name and files. key body Yes integer Creative file index written as ordinal number (e.g. 2) with the exception of 1, which has key "main" (but is not used in advar creatives). Default value is  main - fileName body No string Name of the creative's file. - filePath body No string Path where the file can be found. If a creative was uploaded via the API, this can be found in the response. Creating an advar creative { "campaignId": 27, "creativeName": "Apitestpotmancreative", "sku": null, "formatId": 1, "advarTemplateName": "Image_FlexBanner.html", "templateParameters": { "": "https://example.com", "": "My creative alt text" }, "templateFiles": { "2": { "fileName": "banner.png", "filePath": "/home/adhese/www/docker.adhese.org/tmp/file_by_user_1_9072608199649672610.jpg" } } } Response - 201 { "creativeId": 29, "campaignId": 27, "creativeName": "Apitestpotmancreative", "formatId": 1, "advarTemplateName": "Image_FlexBanner.html", "sku": null, "lastEditedDate": "2026-09-02T13:25:48Z", "templateParameters": { "": "https://example.com", "": "My creative alt text" }, "templateFiles": { "2": { "fileName": null, "filePath": "https://demo.preview.adhese.eu/pool/lib/29_2nd_1.jpg" } }, "readonly": false, "lastEdited": 1788355548000 } Response codes Status Meaning 201 File uploaded 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. Duplicate a creative POST /v1/creatives/advar/{creativeId}/duplicate Duplicates a chosen creative by campaign and creative ID. Request body Parameter In Required Type Description creativeId path Yes string Id of the creative you wish to duplicate. destinationCampaignId body Yes string The ID campaign to which the creative you wish to duplicate belongs. Duplicating a campaign { "destinationCampaignId": 27 } Response - 200 { "creativeId": 30, "campaignId": 27, "creativeName": "Copy of Apitestpotmancreative", "formatId": 1, "advarTemplateName": "Image_FlexBanner.html", "sku": null, "lastEditedDate": "2026-09-08T08:00:13Z", "templateParameters": { "": "https://example.com", "": "My creative alt text" }, "templateFiles": { "2": { "fileName": null, "filePath": "https://demo.preview.adhese.eu/pool/lib/30_2nd_1.jpg" } }, "readonly": false, "lastEdited": 1788854413000 } Response codes Status Meaning 200 Creative duplicated 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. List all bookings for a creative GET /v1/creatives/advar/{id}/bookings List all bookings trafficked to a certain creative. Request body Parameter In Required Type Description creativeId path Yes string Id of the creative you wish to duplicate. Response - 200 [ { "internalId": 28, "name": "Apitest4 booking", "status": "ACTIVE", "lifetimeStatus": "INCOMPLETE", "positionId": 8, "positionName": "Home Halfpage", "formatId": 1, "formatName": "Halfpage", "mediaProduct": { "positionId": 8, "formatId": 1 }, "startDate": "2026-08-30T22:00:00Z", "endDate": "2027-07-31T21:59:00Z", "creationDate": "2026-07-20T13:01:49Z", "lastEditedDate": "2026-07-31T12:40:58Z", "deliveryFactors": { "unit": "IMPRESSIONS", "volume": 1000, "pricingType": "CPM", "price": 1.0, "budget": 1.0, "currency": "EUR", "cpcOptimized": false }, "activeDays": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ], "creativeCount": 0, "frequencyLimits": [], "userFrequencies": [], "pacing": null, "deliveryMethod": "AUTO", "deliveryParameter": 0.0, "deliveryMultiples": "FREE", "campaignId": 27, "comment": null, "priority": null, "priorityId": null, "isBookedOnChannel": false, "excludePositionIds": [], "excludePublicationIds": [], "rtbEnabled": false, "targetExpressions": {}, "targeting": [], "autoDeliveryLimits": false, "bookingType": "DISPLAY", "startTime": "00:00:00", "endTime": "23:59:59" }, { "internalId": 36, "name": "Apitest4 booking", "status": "PAUSED", "lifetimeStatus": "PAUSED", "positionId": 8, "positionName": "Home Halfpage", "formatId": 1, "formatName": "Halfpage", "mediaProduct": { "positionId": 8, "formatId": 1 }, "startDate": "2026-08-30T22:00:00Z", "endDate": "2027-07-31T21:59:00Z", "creationDate": "2026-09-08T09:33:13Z", "lastEditedDate": "2026-09-08T09:33:42Z", "deliveryFactors": { "unit": "IMPRESSIONS", "volume": 1200, "pricingType": "CPM", "price": 1.1, "budget": 1.32, "currency": "EUR", "cpcOptimized": false }, "activeDays": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ], "creativeCount": 0, "frequencyLimits": [], "userFrequencies": [], "pacing": null, "deliveryMethod": "AUTO", "deliveryParameter": 0.0, "deliveryMultiples": "FREE", "campaignId": 27, "comment": "", "priority": null, "priorityId": null, "isBookedOnChannel": false, "excludePositionIds": [], "excludePublicationIds": [], "rtbEnabled": false, "targetExpressions": {}, "targeting": [], "autoDeliveryLimits": false, "bookingType": null, "startTime": "00:00:00", "endTime": "23:59:59" } ] Response codes Status Meaning 200 Bookings listed. 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. Deleting a creative DELETE /v1/creatives/{id} Removes a creative by ID. Request body Parameter In Required Type Description creativeId path Yes string Id of the creative you wish to remove. Response - 200 { "success": "DELETE on Creative 30 was successful", "key": 30 } Response codes Status Meaning 200 Bookings listed. 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.   Media Partners API Media Partners Media partners is the overarching term for an advertiser or debtor. Media partners have media brands associated with them. Create a Media Partner POST /v1/media-partners Creates a media partner (advertiser company, invoicing company, or both, depending on roles). Request body — CreateMediaPartnerRequest Field Type Required Description name string Yes Display name of the company. roles array of enum Yes Any of ADVERTISER, INVOICE externalKey string No Your own external reference key. subsystemExternalIds object (string → string) No External ids per subsystem. Example is a CRM or Advendio ID. Create an advertiser company { "name": "Acme Beverages", "roles": ["ADVERTISER"], "externalKey": "acme-bev", "subsystemExternalIds": { "crm": "CRM-10432" } } Create an invoicing company { "name": "Acme Beverages Billing BV", "roles": ["INVOICE"], "externalKey": "acme-bev-billing" } Create a company that is both advertiser and invoicing party { "name": "Acme Beverages", "roles": ["ADVERTISER", "INVOICE"] } Responses Status Meaning 201 Media partner created. 400 Invalid input (e.g. empty `name` or unknown role). 401 / 403 Not authenticated / not allowed. 500 Unexpected failure. The 201 response will return a body including the generated id and all information known about the media partner. List companies GET /v1/media-partners?limit=50&offset=0 Parameter In Required Type Description limit query Yes integer Max number of results to return. offset query Yes integer Number of results to skip. search query No string URL-encoded, case-insensitive match on name. roles query No array Filter on the role(s) the media partner has, e.g. `roles=ADVERTISER`. includeInactive query No boolean Include deactivated media partners. Response — array of MediaPartner Schema [ { "id": 4021, "name": "Acme Beverages", "roles": ["ADVERTISER"], "externalKey": "acme-bev", "subsystemExternalIds": { "crm": "CRM-10432" }, "active": true } ] Get a single media partner GET /v1/media-partners/{mediaPartnerId} Parameter In Required Type Description mediaPartnerId path Yes integer The id of the media partner you want to fetch. Responses Status Meaning 200 Media partner found. 400 Bad request -Invalid input or parameters. 401 / 403 Not authenticated / not allowed. 404 Media partner not found. 500Internal Server Error Update media partner PUT /v1/media-partners/{mediaPartnerId} Parameter In Required Type Description mediaPartnerId path Yes integer The id of the media partner you want to update. Request body — UpdateMediaPartnerRequest Field Type Required Description name string Yes Media partner name. roles string No Media partner role: INVOICE, ADVERTISER, INTERMEDIARY, MEDIA. subsystemExternalIds object (string → string) No External ids per subsystem. Response { "id": 1, "name": "Philips", "roles": [ "ADVERTISER", "INVOICE" ], "externalKey": null, "subsystemExternalIds": {}, "active": true } Deactivate a media partner PATCH /v1/media-partners/{mediaPartnerId}/deactivate Parameter In Required Type Description mediaPartnerId path Yes integer The id of the media partner you want to deactivate. Check for deactivation by fetching the media partners and see if the deactivated media partner is removed from the list of media partners. Responses Status Meaning 200 Media partner deactivated. 400 Bad request - Invalid input or parameters. 401 / 403 Not authenticated / not allowed. 404 Resource not found. 500Internal Server Error Activate a media partner PATCH /v1/media-partners/{mediaPartnerId}/activate Parameter In Required Type Description mediaPartnerId path Yes integer The id of the media partner you want to (re)activate. Check for activation by fetching the media partners and see if the reactivated media partner is added to the list of media partners. Responses Status Meaning 200 Media partner activated. 400 Bad request - Invalid input or parameters. 401 / 403 Not authenticated / not allowed. 404 Resource not found. 500Internal Server Error Create brands A brand is a media brand that belongs to a media partner (typically the advertiser company). A brand can be present in multiple media partners. Create a brand POST /v1/media-partners/{mediaPartnerId}/brands Parameter In Required Type Description mediaPartnerId path Yes integer The media partner (company) the brand belongs to. Request body — CreateMediaBrandRequest Field Type Required Description name string Yes Brand name. externalKey string No Your own external reference key. subsystemExternalIds object (string → string) No External ids per subsystem. { "name": "Acme Cola", "externalKey": "acme-cola", "subsystemExternalIds": {} } Responses Status Meaning 201 Media brand created. 400 Invalid input. 401 / 403 Not authenticated / not allowed. 404 Media partner not found. As with companies, 201 will return a body including the generated id and all information known about the brand. List a company's brands GET /v1/media-partners/{mediaPartnerId}/brands?limit=50&offset=0 Parameter In Required Type Description mediaPartnerId path Yes integer The media partner. 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 — array of MediaBrand Schema [ { "id": 8801, "name": "Acme Cola", "externalKey": "acme-cola", "subsystemExternalIds": {}, "active": true } ] Get a single brand GET /v1/media-partners/{mediaPartnerId}/brands/{mediaBrandId} Parameter In Required Type Description mediaPartnerId path Yes integer The media partner. mediaBrandId query Yes integer The media brand. includeInactive query No boolean Include deactivated brands. search query No string URL-encoded, case-insensitive match on name. Response - Returns a single MediaBrand Schema. { "id": 1, "name": "Evnia", "externalKey": "Evnia", "subsystemExternalIds": {}, "active": true } Update a brand PUT /v1/media-partners/{mediaPartnerId}/brands/{mediaBrandId} Parameter In Required Type Description mediaPartnerId path Yes integer The media partner. mediaBrandId query Yes integer The media brand. subsystemExternalIds object (string → string) No integer External ids per subsystem. Example is a CRM or Advendio ID. Response - Returns the updated brand information. { "id": 1, "name": "Evnia", "externalKey": "Evnia", "subsystemExternalIds": { "subrandid": "tpvision" }, "active": true } Deactivate a brand PATCH /v1/media-partners/{mediaPartnerId}/brands/{mediaBrandId}/deactivate Parameter In Required Type Description mediaPartnerId path Yes integer The id of the media partner. mediaBrandIdpathYesintegerThe id of the brand you want to deactivate Check for deactivation by fetching the brands and see if it is removed from the list of brands. Responses Status Meaning 200 Media brand deactivated. 400 Bad request - Invalid input or parameters. 401 / 403 Not authenticated / not allowed. 404 Resource not found. 500Internal Server Error Activate a brand PATCH /v1/media-partners/{mediaPartnerId}/brands/{mediaBrandId}/activate Parameter In Required Type Description mediaPartnerId path Yes integer The id of the media partner. mediaBrandIdpathYesintegerThe id of the brand you want to (re)activate Check for the brand reactivation by fetching the brands and see if it is added to the list of brands. Responses Status Meaning 200 Media brand activated. 400 Bad request - Invalid input or parameters. 401 / 403 Not authenticated / not allowed. 404 Resource not found. 500Internal Server Error User Mappings API Connect users to media partners A user mapping grants a user access to a company/brand combination. Each mapping entry requires an advertiserCompanyId and a brandId; invoiceCompanyId is optional. Create a user mapping POST /v1/user-mapping Request body — CreateUserMappingRequest Field Type Required Description user string (1–255) Yes User identifier (e.g. email or username). mappings array of `Mapping Schema` Yes At least one mapping entry. Mapping Schema Field Type Required Description advertiserCompanyId integer (≥ 1) Yes The advertiser company to grant access to. invoiceCompanyId integer No Restrict the mapping to a specific invoicing company. brandId integer (≥ 1) Yes The brand to grant access to. { "user": "jane.doe@partner.example", "mappings": [ { "advertiserCompanyId": 4021, "invoiceCompanyId": 4022, "brandId": 8801 } ] } Responses Status Meaning 201 User mapping created. 400 Invalid input (e.g. missing `advertiserCompanyId` or `brandId`). 401 / 403 Not authenticated / not allowed. List users with mappings GET /v1/user-mapping?limit=50&offset=0 Parameter In Required Type Description limit query No integer Max results (≤ 100). offset query No integer Results to skip. search query No string Loose match on user identifier. advertiserCompanyId query No integer Only users mapped to this advertiser company. invoiceCompanyId query No integer Only users mapped to this invoice company. brandId query No integer Only users mapped to this brand. The response includes a Record-Count header with the total number of matches. Response — array of UserMapping Schema [ { "user": "jane.doe@partner.example", "mappingCount": 3 } ] List a single user's mappings GET /v1/user-mapping/{user} Parameter In Required Type Description user path Yes string The user identifier. limit / offset query No integer Pagination. advertiserCompanyId query No integer Filter by advertiser company. invoiceCompanyId query No integer Filter by invoice company. brandId query No integer Filter by brand. Response — array of Mapping Schema [ { "advertiserCompanyId": 4021, "invoiceCompanyId": 4022, "brandId": 8801 } ] Delete a user mapping DELETE /v1/user-mapping Request body — DeleteUserMappingRequest Field Type Required Description user string (1–255) Yes The user identifier. advertiserCompanyId integer (≥ 1) — Advertiser company of the mapping to remove. invoiceCompanyId integer — Invoice company of the mapping to remove. brandId integer (≥ 1) — Brand of the mapping to remove. { "user": "jane.doe@partner.example", "advertiserCompanyId": 4021, "invoiceCompanyId": 4022, "brandId": 8801 } Responds 200 when the mapping is deleted. API Manuals Advertiser & Invoicing Companies, Brands, and User Mapping This guide explains how to create advertiser companies, invoicing companies, and brands in Adhese through the Campaign API, and how to connect (map) users to those companies and brands. All endpoints live under the Adhese API and are versioned with a  /v1 prefix. The server base path is  /api, so a full path looks like  /api/v1/media-partners and /v1/user-mapping. Key concepts & terminology In Adhese, an advertiser company and an invoicing company are the same underlying entity — a media partner — distinguished by the roles assigned to it. A single media partner can hold one or more roles at the same time. You want to create… What it is in the API How An advertiser company A media partner with the  ADVERTISER role POST /v1/media-partners with  "roles": ["ADVERTISER"] An invoicing company A media partner with the  INVOICE role POST /v1/media-partners with  "roles": ["INVOICE"] A company that is both A media partner with both roles POST /v1/media-partners with  "roles": ["ADVERTISER", "INVOICE"] A brand A media brand that belongs to a media partner POST /v1/media-partners/{mediaPartnerId}/brands A user ↔ company/brand link A user mapping POST /v1/user-mapping Available roles:  ADVERTISER,  INVOICE Note. The read-only endpoints  GET /v1/advertiser-companies and  GET /v1/brands expose the same entities from the campaign-booking perspective (used when creating or editing a campaign). Their  id values are the media-partner and media-brand ids you create below. Authentication & headers Every request is authenticated with a Bearer JWT and must carry the Keycloak auth header. Header Required Value Notes Authorization Yes Bearer JWT access token. Use-Keycloak-Auth Yes true Required on all  /v1 endpoints. Content-Type For  POST/ DELETE with a body application/json — Example request line and headers: POST /api/v1/media-partners Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... Use-Keycloak-Auth: true Content-Type: application/json Media Partners Media partners is the overarching term for an advertiser or debtor. Media partners have media brands associated with them. Create a Media Partner POST /v1/media-partners Creates a media partner (advertiser company, invoicing company, or both, depending on roles). Request body — CreateMediaPartnerRequest Field Type Required Description name string Yes Display name of the company. roles array of enum Yes Any of ADVERTISER, INVOICE externalKey string No Your own external reference key. subsystemExternalIds object (string → string) No External ids per subsystem. Example is a CRM or Advendio ID. Create an advertiser company { "name": "Acme Beverages", "roles": ["ADVERTISER"], "externalKey": "acme-bev", "subsystemExternalIds": { "crm": "CRM-10432" } } Create an invoicing company { "name": "Acme Beverages Billing BV", "roles": ["INVOICE"], "externalKey": "acme-bev-billing" } Create a company that is both advertiser and invoicing party { "name": "Acme Beverages", "roles": ["ADVERTISER", "INVOICE"] } Responses Status Meaning 201 Media partner created. 400 Invalid input (e.g. empty `name` or unknown role). 401 / 403 Not authenticated / not allowed. 500 Unexpected failure. The 201 response will return a body including the generated id and all information known about the media partner. List companies GET /v1/media-partners?limit=50&offset=0 Parameter In Required Type Description limit query Yes integer Max number of results to return. offset query Yes integer Number of results to skip. search query No string URL-encoded, case-insensitive match on name. roles query No array Filter on the role(s) the media partner has, e.g. `roles=ADVERTISER`. includeInactive query No boolean Include deactivated media partners. Response — array of MediaPartner Schema [ { "id": 4021, "name": "Acme Beverages", "roles": ["ADVERTISER"], "externalKey": "acme-bev", "subsystemExternalIds": { "crm": "CRM-10432" }, "active": true } ] Get a single media partner GET /v1/media-partners/{mediaPartnerId} Parameter In Required Type Description mediaPartnerId path Yes integer The id of the media partner you want to fetch. Responses Status Meaning 200 Media partner found. 400 Bad request -Invalid input or parameters. 401 / 403 Not authenticated / not allowed. 404 Media partner not found. 500Internal Server Error Update media partner PUT /v1/media-partners/{mediaPartnerId} Parameter In Required Type Description mediaPartnerId path Yes integer The id of the media partner you want to update. Request body — UpdateMediaPartnerRequest Field Type Required Description name string Yes Media partner name. roles string No Media partner role: INVOICE, ADVERTISER, INTERMEDIARY, MEDIA. subsystemExternalIds object (string → string) No External ids per subsystem. Response { "id": 1, "name": "Philips", "roles": [ "ADVERTISER", "INVOICE" ], "externalKey": null, "subsystemExternalIds": {}, "active": true } Deactivate a media partner PATCH /v1/media-partners/{mediaPartnerId}/deactivate Parameter In Required Type Description mediaPartnerId path Yes integer The id of the media partner you want to deactivate. Check for deactivation by fetching the media partners and see if the deactivated media partner is removed from the list of media partners. Responses Status Meaning 200 Media partner deactivated. 400 Bad request - Invalid input or parameters. 401 / 403 Not authenticated / not allowed. 404 Resource not found. 500Internal Server Error Activate a media partner PATCH /v1/media-partners/{mediaPartnerId}/activate Parameter In Required Type Description mediaPartnerId path Yes integer The id of the media partner you want to (re)activate. Check for activation by fetching the media partners and see if the reactivated media partner is added to the list of media partners. Responses Status Meaning 200 Media partner activated. 400 Bad request - Invalid input or parameters. 401 / 403 Not authenticated / not allowed. 404 Resource not found. 500Internal Server Error Create brands A brand is a media brand that belongs to a media partner (typically the advertiser company). A brand can be present in multiple media partners. Create a brand POST /v1/media-partners/{mediaPartnerId}/brands Parameter In Required Type Description mediaPartnerId path Yes integer The media partner (company) the brand belongs to. Request body — CreateMediaBrandRequest Field Type Required Description name string Yes Brand name. externalKey string No Your own external reference key. subsystemExternalIds object (string → string) No External ids per subsystem. { "name": "Acme Cola", "externalKey": "acme-cola", "subsystemExternalIds": {} } Responses Status Meaning 201 Media brand created. 400 Invalid input. 401 / 403 Not authenticated / not allowed. 404 Media partner not found. As with companies, 201 will return a body including the generated id and all information known about the brand. List a company's brands GET /v1/media-partners/{mediaPartnerId}/brands?limit=50&offset=0 Parameter In Required Type Description mediaPartnerId path Yes integer The media partner. 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 — array of MediaBrand Schema [ { "id": 8801, "name": "Acme Cola", "externalKey": "acme-cola", "subsystemExternalIds": {}, "active": true } ] Get a single brand GET /v1/media-partners/{mediaPartnerId}/brands/{mediaBrandId} Parameter In Required Type Description mediaPartnerId path Yes integer The media partner. mediaBrandId query Yes integer The media brand. includeInactive query No boolean Include deactivated brands. search query No string URL-encoded, case-insensitive match on name. Response - Returns a single MediaBrand Schema. { "id": 1, "name": "Evnia", "externalKey": "Evnia", "subsystemExternalIds": {}, "active": true } Update a brand PUT /v1/media-partners/{mediaPartnerId}/brands/{mediaBrandId} Parameter In Required Type Description mediaPartnerId path Yes integer The media partner. mediaBrandId query Yes integer The media brand. subsystemExternalIds object (string → string) No integer External ids per subsystem. Example is a CRM or Advendio ID. Response - Returns the updated brand information. { "id": 1, "name": "Evnia", "externalKey": "Evnia", "subsystemExternalIds": { "subrandid": "tpvision" }, "active": true } Deactivate a brand PATCH /v1/media-partners/{mediaPartnerId}/brands/{mediaBrandId}/deactivate Parameter In Required Type Description mediaPartnerId path Yes integer The id of the media partner. mediaBrandIdpathYesintegerThe id of the brand you want to deactivate Check for deactivation by fetching the brands and see if it is removed from the list of brands. Responses Status Meaning 200 Media brand deactivated. 400 Bad request - Invalid input or parameters. 401 / 403 Not authenticated / not allowed. 404 Resource not found. 500Internal Server Error Activate a brand PATCH /v1/media-partners/{mediaPartnerId}/brands/{mediaBrandId}/activate Parameter In Required Type Description mediaPartnerId path Yes integer The id of the media partner. mediaBrandIdpathYesintegerThe id of the brand you want to (re)activate Check for the brand reactivation by fetching the brands and see if it is added to the list of brands. Responses Status Meaning 200 Media brand activated. 400 Bad request - Invalid input or parameters. 401 / 403 Not authenticated / not allowed. 404 Resource not found. 500Internal Server Error Connect users to media partners A user mapping grants a user access to a company/brand combination. Each mapping entry requires an advertiserCompanyId and a brandId; invoiceCompanyId is optional. Create a user mapping POST /v1/user-mapping Request body — CreateUserMappingRequest Field Type Required Description user string (1–255) Yes User identifier (e.g. email or username). mappings array of `Mapping Schema` Yes At least one mapping entry. Mapping Schema Field Type Required Description advertiserCompanyId integer (≥ 1) Yes The advertiser company to grant access to. invoiceCompanyId integer No Restrict the mapping to a specific invoicing company. brandId integer (≥ 1) Yes The brand to grant access to. { "user": "jane.doe@partner.example", "mappings": [ { "advertiserCompanyId": 4021, "invoiceCompanyId": 4022, "brandId": 8801 } ] } Responses Status Meaning 201 User mapping created. 400 Invalid input (e.g. missing `advertiserCompanyId` or `brandId`). 401 / 403 Not authenticated / not allowed. List users with mappings GET /v1/user-mapping?limit=50&offset=0 Parameter In Required Type Description limit query No integer Max results (≤ 100). offset query No integer Results to skip. search query No string Loose match on user identifier. advertiserCompanyId query No integer Only users mapped to this advertiser company. invoiceCompanyId query No integer Only users mapped to this invoice company. brandId query No integer Only users mapped to this brand. The response includes a Record-Count header with the total number of matches. Response — array of UserMapping Schema [ { "user": "jane.doe@partner.example", "mappingCount": 3 } ] List a single user's mappings GET /v1/user-mapping/{user} Parameter In Required Type Description user path Yes string The user identifier. limit / offset query No integer Pagination. advertiserCompanyId query No integer Filter by advertiser company. invoiceCompanyId query No integer Filter by invoice company. brandId query No integer Filter by brand. Response — array of Mapping Schema [ { "advertiserCompanyId": 4021, "invoiceCompanyId": 4022, "brandId": 8801 } ] Delete a user mapping DELETE /v1/user-mapping Request body — DeleteUserMappingRequest Field Type Required Description user string (1–255) Yes The user identifier. advertiserCompanyId integer (≥ 1) — Advertiser company of the mapping to remove. invoiceCompanyId integer — Invoice company of the mapping to remove. brandId integer (≥ 1) — Brand of the mapping to remove. { "user": "jane.doe@partner.example", "advertiserCompanyId": 4021, "invoiceCompanyId": 4022, "brandId": 8801 } Responds 200 when the mapping is deleted. End-to-end walkthrough Create an advertiser company, an invoicing company, and a brand, then give a user access to them. 1. Create the advertiser company POST /v1/media-partners { "name": "Acme Beverages", "roles": ["ADVERTISER"], "externalKey": "acme-bev" } The response will give you its id → assume  4021. 2. Create the invoicing company POST /v1/media-partners { "name": "Acme Beverages Billing BV", "roles": ["INVOICE"], "externalKey": "acme-bev-billing" } The response will give you its id → assume  4022. 3. Create a brand under the advertiser company POST /v1/media-partners/4021/brands { "name": "Acme Cola", "externalKey": "acme-cola" } The response will give you its id → assume 8801. 4. Map the user to the company + brand POST /v1/user-mapping { "user": "jane.doe@partner.example", "mappings": [ { "advertiserCompanyId": 4021, "invoiceCompanyId": 4022, "brandId": 8801 } ] } 5. Verify the mapping GET /v1/user-mapping/jane.doe@partner.example [ { "advertiserCompanyId": 4021, "invoiceCompanyId": 4022, "brandId": 8801 } ] Error handling Errors are returned as an RFC 7807  ProblemDetail object. { "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "roles must not be empty", "instance": "/api/v1/media-partners" } Status Meaning 400 Bad Request — invalid input or parameters. 401 Unauthorized — authentication required or invalid token. 403 Forbidden — authenticated but not allowed to access this resource. 404 Not Found — resource not found. 422 Unprocessable Entity — the request was understood but could not be processed. 500 Internal Server Error — unexpected failure. Schema reference CreateMediaPartnerRequest · MediaPartner Schema { "id": 4021, "name": "string", "roles": ["ADVERTISER", "INVOICE", "INTERMEDIARY", "MEDIA"], "externalKey": "string", "subsystemExternalIds": { "subsystem": "externalId" }, "active": true } CreateMediaBrandRequest · MediaBrand Schema { "id": 8801, "name": "string", "externalKey": "string", "subsystemExternalIds": { "subsystem": "externalId" }, "active": true } AdvertiserCompany Schema { "id": 4021, "name": "string", "active": true, "externalId": "string", "subsystemExternalIds": { "subsystem": "externalId" } } Brand Schema { "id": 8801, "name": "string" } CreateUserMappingRequest Schema { "user": "string", "mappings": [ { "advertiserCompanyId": 4021, "invoiceCompanyId": 4022, "brandId": 8801 } ] } UserMapping Schema { "user": "string", "mappingCount": 3 } Inventory API Inventory API documentation. Documentation is split over it's various components: - Publisher - Publication - Position - Location - Other APIs The Inventory API page bundles all pages in one large manual. Inventory API Inventory The structure and makeup of the places where ads are going to be delivered. Publishers List a publisher GET /v1/inventory/publisher/{id} Retrieves details of a publisher by it's ID. Request body Parameter In Required Type Description id path Yes integer The publisher's ID. Response - 200 { "id": 1, "parentId": 0, "companyName": "Main Publisher", "quote": "", "active": 1, "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTelephone": "", "companyFax": "", "companyEmail": "", "companyURL": "", "companyVat": "", "companyBankAccount": "", "contactName": "", "contactFirstName": "", "contactAddress": "", "contactNumber": "", "contactZip": "", "contactCity": "", "contactCountry": "", "contactTelephone": "", "contactFax": "", "contactEmail": "", "description": "", "paymentMethod": "", "invoicingParty": "" } Response codes Status Meaning 200 Publisher retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unssuported media type 500 Internal Server Error - Unexpected failure. Update a publisher PUT /v1/inventory/publisher/{id} Updates the name, parent publisher, and active status of an existing publisher. Fields the request omits are left as they are. Request body Parameter In Required Type Description parentPublisherId body No integer The ID of the parent publisher. name body No string Name of the publisher active body No boolean Is the publisher active? Updating a publisher { "name": "Demo Publisher" } Response - 200 { "id": 1, "parentId": 0, "companyName": "Demo Publisher", "quote": "", "active": 1, "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTelephone": "", "companyFax": "", "companyEmail": "", "companyURL": "", "companyVat": "", "companyBankAccount": "", "contactName": "", "contactFirstName": "", "contactAddress": "", "contactNumber": "", "contactZip": "", "contactCity": "", "contactCountry": "", "contactTelephone": "", "contactFax": "", "contactEmail": "", "description": "", "paymentMethod": "", "invoicingParty": "" } Response codes Status Meaning 200 Publisher updated. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Delete a publisher DELETE /v1/inventory/publisher/{id} Sets a publisher to inactive. Request body Parameter In Required Type Description id path Yes integer The publisher's ID. Response codes Status Meaning 204 Publisher set to inactive. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. List publishers GET /v1/inventory/publisher Retrieves all publishers and their information. Response - 200 [ { "id": 1, "parentId": 0, "companyName": "Demo Publisher", "quote": "", "active": 1, "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTelephone": "", "companyFax": "", "companyEmail": "", "companyURL": "", "companyVat": "", "companyBankAccount": "", "contactName": "", "contactFirstName": "", "contactAddress": "", "contactNumber": "", "contactZip": "", "contactCity": "", "contactCountry": "", "contactTelephone": "", "contactFax": "", "contactEmail": "", "description": "", "paymentMethod": "", "invoicingParty": "" }, { "id": 2, "parentId": 1, "companyName": "Example Demo Publisher", "quote": "", "active": 0, "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTelephone": "", "companyFax": "", "companyEmail": "", "companyURL": "", "companyVat": "", "companyBankAccount": "", "contactName": "", "contactFirstName": "", "contactAddress": "", "contactNumber": "", "contactZip": "", "contactCity": "", "contactCountry": "", "contactTelephone": "", "contactFax": "", "contactEmail": "", "description": "", "paymentMethod": "-", "invoicingParty": "" } ] Create a publisher POST /v1/inventory/publisher Creates a new publisher. Request body Parameter In Required Type Description parentPublisherId body No integer The ID of the parent publisher. Leave blank if the new publisher is a main publisher name body Yes string Name of the publisher active body No boolean Is the publisher active? Default is  true Creating a new publisher { "parentPublisherId": 1, "name": "Example API Publisher", "active": true } Response - 201 { "id": 3, "parentId": 1, "companyName": "Example API Publisher", "quote": "", "active": 1, "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTelephone": "", "companyFax": "", "companyEmail": "", "companyURL": "", "companyVat": "", "companyBankAccount": "", "contactName": "", "contactFirstName": "", "contactAddress": "", "contactNumber": "", "contactZip": "", "contactCity": "", "contactCountry": "", "contactTelephone": "", "contactFax": "", "contactEmail": "", "description": "", "paymentMethod": "-", "invoicingParty": "" } Response codes Status Meaning 201 Publisher created. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Publications List a publication GET /v1/inventory/publication/{id} List a single publication by ID. Request body Parameter In Required Type Description id path Yes integer The publisher's ID. Response - 200 { "id": 3, "companyName": "Demo Sponsored Placements", "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTel": "", "companyFax": "", "companyUrl": "https://pool-demo.adhese.com/projects/marketing/index.html", "companyEmail": "", "publishersId": 1, "quote": "", "parentPublicationsId": 0, "description": "", "comment": "", "active": 1, "rank": 0, "screenshotExtension": "", "catchphrase": "", "language": "", "numberOfAuthors": 0, "inventoryCategory": "sponsored_product" } Response codes Status Meaning 200 Publication retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Update a publication PUT /v1/inventory/publication/{id} Updates the name, parent publisher, active status, quote and website of an existing publication. Fields the request omits are left as they are. Request body Parameter In Required Type Description parentPublisherId body No integer The ID of the publication's publisher. active body No boolean Is the publication active? Default is true. name body Yes string Name of the publication. quote body No string Quote field of the publication. website body Yes string Website of the publication. Updating a publication { "publisherId": 1, "active": true, "name": "Demo Display", "quote": "DD", "website": "https://pool-demo.adhese.com/projects/marketing/index.html" } Response - 200 { "id": 1, "companyName": "Demo Display", "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTel": "", "companyFax": "", "companyUrl": "https://pool-demo.adhese.com/projects/marketing/index.html", "companyEmail": "", "publishersId": 1, "quote": "DD", "parentPublicationsId": 0, "description": "", "comment": "", "active": 1, "rank": 0, "screenshotExtension": "", "catchphrase": "", "language": "", "numberOfAuthors": 0, "inventoryCategory": "display" } Response codes Status Meaning 200 Publication retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Delete a publication DELETE /v1/inventory/publication/{id} Sets a publication to inactive. Request body Parameter In Required Type Description id path Yes integer The publication's ID. Response codes Status Meaning 204 Publication set to inactive. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. List all publications under a publisher GET /v1/inventory/publication List all publications under one or more publishers. Request body Parameter In Required Type Description publisherIds parameter Yes integer The publisher IDs whose publications you want listed. The publisher IDs are comma separated. Response - 200 [ { "id": 1, "companyName": "Demo Display", "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTel": "", "companyFax": "", "companyUrl": "https://pool-demo.adhese.com/projects/marketing/index.html", "companyEmail": "", "publishersId": 1, "quote": "DD", "parentPublicationsId": 0, "description": "", "comment": "", "active": 1, "rank": 0, "screenshotExtension": "", "catchphrase": "", "language": "", "numberOfAuthors": 0, "inventoryCategory": "display" }, { "id": 2, "companyName": "Demo DOOH", "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTel": "", "companyFax": "", "companyUrl": "https://adhese.eu", "companyEmail": "", "publishersId": 1, "quote": "", "parentPublicationsId": 0, "description": "", "comment": "", "active": 1, "rank": 0, "screenshotExtension": "", "catchphrase": "", "language": "", "numberOfAuthors": 0, "inventoryCategory": "in_store" }, { "id": 3, "companyName": "Demo Sponsored Placements", "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTel": "", "companyFax": "", "companyUrl": "https://pool-demo.adhese.com/projects/marketing/index.html", "companyEmail": "", "publishersId": 1, "quote": "", "parentPublicationsId": 0, "description": "", "comment": "", "active": 1, "rank": 0, "screenshotExtension": "", "catchphrase": "", "language": "", "numberOfAuthors": 0, "inventoryCategory": "sponsored_product" } ] Response codes Status Meaning 200 Publications retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Create a publication POST /v1/inventory/publication Create a new publication. Request body Parameter In Required Type Description publisherId body No integer The ID of the parent publisher. Leave blank if the new publisher is a main publisher active body No boolean Is the publication active? Default is true. name body Yes string Name of the publication. quote body No string Quote field of the publication. website body Yes string Website of the publication. Creating a new publication { "publisherId": 3, "active": true, "name": "String Created Publication", "quote": "SCP", "website": "https://pool-demo.adhese.com/projects/marketing/index.html" } Response - 201 { "id": 5, "companyName": "String Created Publication", "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTel": "", "companyFax": "", "companyUrl": "https://pool-demo.adhese.com/projects/marketing/index.html", "companyEmail": "", "publishersId": 3, "quote": "SCP", "parentPublicationsId": 0, "description": "", "comment": "", "active": 1, "rank": 0, "screenshotExtension": "", "catchphrase": "", "language": "", "numberOfAuthors": 0, "inventoryCategory": null } Response codes Status Meaning 201 Publication created. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Positions List a single position GET /v1/inventory/position/{id} Lists the chosen positions information by ID. Request body Parameter In Required Type Description positionId path Yes integer The position ID whose information you want listed. Response - 200 { "id": 9, "publisherId": 1, "transferId": 0, "active": true, "creation": "Mar 25, 2026, 2:31:29 PM CET", "edited": "Mar 25, 2026, 2:31:29 PM CET", "name": "", "formatId": 4, "formatName": "Billboard", "formatWidth": 970, "formatHeight": 250, "formatSize": 0, "locationId": 5, "locationName": "ROS", "locationTypeId": 10, "publicationName": "Demo Display", "previewUrl": "", "url": "" } Response codes Status Meaning 200 Position listed. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Updating a position PUT /v1/inventory/position/{id} Updates a chosen positions name, format, location, position type, active status, and URL. Fields the request omits are left as they are. Request body Parameter In Required Type Description id path Yes integer The positions ID. active body No boolean Whether the position is active or not. name body No string Name of the position, recommended for use with the Campaign Manager UI. formatId body No integer ID of the positions format. locationId body No integer ID of the positions location. url body No string URL for identifying the position. positionTypeId body No integer ID of the position type (when applicable). Updating a position { "active": true, "name": "SCP Halfpage", "formatId": 1, "locationId": 9, "url": "_scp_halfpage", "positionTypeId": 10 } Response - 200 { "id": 19, "publisherId": 5, "transferId": 0, "active": true, "creation": "Sep 22, 2026, 11:46:01 AM CEST", "edited": "Sep 22, 2026, 11:52:26 AM CEST", "name": "SCP Halfpage", "formatId": 1, "formatName": "Halfpage", "formatWidth": 300, "formatHeight": 600, "formatSize": 0, "locationId": 9, "locationName": "SCP", "locationTypeId": 10, "publicationName": "String Created Publication", "previewUrl": "", "url": "_scp_halfpage" } Response codes Status Meaning 200 Position updated. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Delete a position DELETE /v1/inventory/position/{id} Sets a position to inactive by ID. Request body Parameter In Required Type Description positionId path Yes integer The ID of the position you want deactivated. Response codes Status Meaning 204 Position set to inactive. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. List all positions GET /v1/inventory/position List the details of all positions. Request body Parameter In Required Type Description publicationId body No integer The publication ID of the publication you want to filter positions on. active body No boolean Filter on the active or inactive status of positions. Response - 200 [ { "id": 1, "publisherId": 1, "transferId": 0, "active": true, "creation": "Mar 13, 2026, 3:09:34 PM CET", "edited": "Mar 13, 2026, 3:09:34 PM CET", "name": "", "formatId": 4, "formatName": "Billboard", "formatWidth": 970, "formatHeight": 250, "formatSize": 0, "locationId": 2, "locationName": "Kitchen", "locationTypeId": 10, "publicationName": "Demo Display", "previewUrl": "", "url": "" }, { "id": 2, "publisherId": 1, "transferId": 0, "active": true, "creation": "Mar 13, 2026, 3:09:46 PM CET", "edited": "Mar 13, 2026, 3:12:44 PM CET", "name": "", "formatId": 1, "formatName": "Halfpage", "formatWidth": 300, "formatHeight": 600, "formatSize": 0, "locationId": 2, "locationName": "Kitchen", "locationTypeId": 10, "publicationName": "Demo Display", "previewUrl": "", "url": "" }, { "id": 3, "publisherId": 1, "transferId": 0, "active": true, "creation": "Mar 13, 2026, 3:09:59 PM CET", "edited": "Mar 13, 2026, 3:12:56 PM CET", "name": "", "formatId": 3, "formatName": "Wide Skyscraper", "formatWidth": 160, "formatHeight": 600, "formatSize": 0, "locationId": 3, "locationName": "Electronics", "locationTypeId": 10, "publicationName": "Demo Display", "previewUrl": "", "url": "" }, ] Response codes Status Meaning 200 Positions listed. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Create a position POST /v1/inventory/position Creates a new position (ad slot) linked to a location, format, and position type. A request that omits the active status creates an active position. Request body Parameter In Required Type Description active body No boolean Whether the position is active or not. A request that omits the active status creates an active position. name body No string Name of the position, recommended for use with the Campaign Manager UI. formatId body Yes integer ID of the positions format. locationId body Yes integer ID of the positions location. url body No string URL for identifying the position. positionTypeId body No integer ID of the position type (when applicable). Creating a new position { "active": true, "name": "SCP Billboard", "formatId": 4, "locationId": 9, "url": "_scp_billboard", "positionTypeId": 10 } Response - 201 { "id": 20, "publisherId": 5, "transferId": 0, "active": true, "creation": "Sep 22, 2026, 1:56:07 PM CEST", "edited": "Sep 22, 2026, 1:56:07 PM CEST", "name": "SCP Billboard", "formatId": 4, "formatName": "Billboard", "formatWidth": 970, "formatHeight": 250, "formatSize": 0, "locationId": 9, "locationName": "SCP", "locationTypeId": 10, "publicationName": "String Created Publication", "previewUrl": null, "url": "_scp_billboard" } Response codes Status Meaning 201 Position created. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Locations List a single location GET /v1/inventory/location/{id} Retrieves a single location by its ID. Request body Parameter In Required Type Description locationId path Yes integer The location ID of the location you want to list. Response - 200 { "id": 9, "name": "SCP", "publicationId": 5, "publicationQuote": "SCP", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "scp_home", "previewUrl": "", "code": null, "price": 0.0, "active": true, "locationTypes": [ "full", "guaranteed" ], "numberOfBookings": 0 } Response codes Status Meaning 200 Location listed. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Update a location PUT /v1/inventory/location/{id} Updates the name, URL, channel option code, publication, and location types of an existing location. Request body Parameter In Required Type Description locationId path Yes integer The location ID of the location you want to list. publicationId body Yes integer ID of the publication to which the location belongs. name body No string Name of the location. url body No string URL for identifying the location on the webpage. channelOptionCode body No integer Determines if the location is for single positions or Channels. 0 means single position. Use Use GET /v1/inventory/location-channel-option for other valid channelOptionCode values for your account. locationTypes body No string Location types that belong to this location. Options are guranteed and/or full code body No string Location code. price body No integer Location price. Response - 200 { "id": 9, "name": "SCP", "publicationId": 5, "publicationQuote": "SCP", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "scp_overview", "previewUrl": "", "code": "001", "price": 1.0, "active": true, "locationTypes": [ "full", "guaranteed" ], "numberOfBookings": 0 } Response codes Status Meaning 200 Location updated. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Delete a location DELETE /v1/inventory/location/{id} Set a location to inactive by ID. Request body Parameter In Required Type Description locationId path Yes integer The ID of the location that you want deactivated. Response codes Status Meaning 204 Location set to inactive. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. List all locations by publication GET /v1/inventory/location Lists all locations under a publication by it's ID. Request body Parameter In Required Type Description publicationId parameters Yes integer The ID of the publication for which you want to list all locations. Response - 200 [ { "id": 4, "name": "Audio", "publicationId": 1, "publicationQuote": "DD", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "demo.com_audio", "previewUrl": "", "code": null, "price": 5.0, "active": true, "locationTypes": [ "full" ], "numberOfBookings": 0 }, { "id": 3, "name": "Electronics", "publicationId": 1, "publicationQuote": "DD", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "demo.com_electronics", "previewUrl": "", "code": null, "price": 5.0, "active": true, "locationTypes": [ "full", "guaranteed" ], "numberOfBookings": 0 }, { "id": 1, "name": "Home", "publicationId": 1, "publicationQuote": "DD", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "demo.com_home", "previewUrl": "", "code": "demo_web_home", "price": 5.0, "active": true, "locationTypes": [ "full", "guaranteed" ], "numberOfBookings": 3 }, { "id": 2, "name": "Kitchen", "publicationId": 1, "publicationQuote": "DD", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "demo.com_kitchen", "previewUrl": "", "code": null, "price": 5.0, "active": true, "locationTypes": [ "full" ], "numberOfBookings": 0 }, { "id": 5, "name": "ROS", "publicationId": 1, "publicationQuote": "DD", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 3, "url": "", "previewUrl": "", "code": null, "price": 5.0, "active": true, "locationTypes": [ "full" ], "numberOfBookings": 1 } ] Response codes Status Meaning 200 Locations listed. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Create a new location POST /v1/inventory/location Create a new location under a publication by ID. Request body Parameter In Required Type Description publicationId body Yes integer ID of the publication to which the location belongs. name body No string Name of the location. url body No string URL for identifying the location on the webpage. channelOptionCode body No integer Determines if the location is for single positions or Channels. 0 means single position. Use Use GET /v1/inventory/location-channel-option for other valid channelOptionCode values for your account. locationTypes body No string Location types that belong to this location. Options are guranteed and/or full code body No string Location code. price body No integer Location price. Response - 201 { "id": 11, "name": "SCP BR", "publicationId": 5, "publicationQuote": "SCP", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "scp_br", "previewUrl": null, "code": "002", "price": 1.2, "active": true, "locationTypes": [ "full", "guaranteed" ], "numberOfBookings": 0 } Response codes Status Meaning 201 Location created. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Miscellaneous Inventory APIs List position types GET /v1/inventory/position-type Lists all available position types for the account. Response - 200 [ { "id": 1, "name": "", "templateFile": "", "thirdPartyQuotum": 0 }, { "id": 13, "name": "newsletter img tag", "templateFile": "", "thirdPartyQuotum": 0 }, { "id": 10, "name": "normal javascript", "templateFile": "", "thirdPartyQuotum": 0 }, { "id": 12, "name": "normal javascript / no empty", "templateFile": "", "thirdPartyQuotum": 0 } ] Response codes Status Meaning 200 Position types retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. List location channel options GET /v1/inventory/location-channel-option Lists all location channel options (such as normal position and available group levels). Response - 200 [ { "code": 0, "name": "normal position (no group)" }, { "code": 1, "name": "group level 1" }, { "code": 2, "name": "group level 2" }, { "code": 3, "name": "group level 3" }, { "code": 4, "name": "group level 4" }, { "code": 5, "name": "group level 5" } ] Response codes Status Meaning 200 Location channel options retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. List available formats GET /v1/inventory/format Retrieves all available ad formats (templates) that can be assigned to positions. Response - 200 [ { "id": 4, "name": "Billboard", "width": 970, "height": 250, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "billboard", "codeBook": "billboard" }, { "id": 1, "name": "Halfpage", "width": 300, "height": 600, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "halfpage", "codeBook": "halfpage" }, { "id": 6, "name": "Landscape Screen", "width": 16, "height": 9, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "landscape", "codeBook": "landscape" }, { "id": 5, "name": "Leaderboard", "width": 728, "height": 90, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "leaderboard", "codeBook": "leaderboard" }, { "id": 2, "name": "Medium Rectangle", "width": 300, "height": 250, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "imu", "codeBook": "imu;halfpage" }, { "id": 7, "name": "Portrait Screen", "width": 9, "height": 16, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "portrait", "codeBook": "portrait" }, { "id": 3, "name": "Wide Skyscraper", "width": 160, "height": 600, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "skyscraper", "codeBook": "skyscraper" } ] Response codes Status Meaning 200 Formats retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Publishers List a publisher GET /v1/inventory/publisher/{id} Retrieves details of a publisher by it's ID. Request body Parameter In Required Type Description id path Yes integer The publisher's ID. Response - 200 { "id": 1, "parentId": 0, "companyName": "Main Publisher", "quote": "", "active": 1, "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTelephone": "", "companyFax": "", "companyEmail": "", "companyURL": "", "companyVat": "", "companyBankAccount": "", "contactName": "", "contactFirstName": "", "contactAddress": "", "contactNumber": "", "contactZip": "", "contactCity": "", "contactCountry": "", "contactTelephone": "", "contactFax": "", "contactEmail": "", "description": "", "paymentMethod": "", "invoicingParty": "" } Response codes Status Meaning 200 Publisher retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unssuported media type 500 Internal Server Error - Unexpected failure. Update a publisher PUT /v1/inventory/publisher/{id} Updates the name, parent publisher, and active status of an existing publisher. Fields the request omits are left as they are. Request body Parameter In Required Type Description parentPublisherId body No integer The ID of the parent publisher. name body No string Name of the publisher active body No boolean Is the publisher active? Updating a publisher { "name": "Demo Publisher" } Response - 200 { "id": 1, "parentId": 0, "companyName": "Demo Publisher", "quote": "", "active": 1, "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTelephone": "", "companyFax": "", "companyEmail": "", "companyURL": "", "companyVat": "", "companyBankAccount": "", "contactName": "", "contactFirstName": "", "contactAddress": "", "contactNumber": "", "contactZip": "", "contactCity": "", "contactCountry": "", "contactTelephone": "", "contactFax": "", "contactEmail": "", "description": "", "paymentMethod": "", "invoicingParty": "" } Response codes Status Meaning 200 Publisher updated. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Delete a publisher DELETE /v1/inventory/publisher/{id} Sets a publisher to inactive. Request body Parameter In Required Type Description id path Yes integer The publisher's ID. Response codes Status Meaning 204 Publisher set to inactive. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. List publishers GET /v1/inventory/publisher Retrieves all publishers and their information. Response - 200 [ { "id": 1, "parentId": 0, "companyName": "Demo Publisher", "quote": "", "active": 1, "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTelephone": "", "companyFax": "", "companyEmail": "", "companyURL": "", "companyVat": "", "companyBankAccount": "", "contactName": "", "contactFirstName": "", "contactAddress": "", "contactNumber": "", "contactZip": "", "contactCity": "", "contactCountry": "", "contactTelephone": "", "contactFax": "", "contactEmail": "", "description": "", "paymentMethod": "", "invoicingParty": "" }, { "id": 2, "parentId": 1, "companyName": "Example Demo Publisher", "quote": "", "active": 0, "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTelephone": "", "companyFax": "", "companyEmail": "", "companyURL": "", "companyVat": "", "companyBankAccount": "", "contactName": "", "contactFirstName": "", "contactAddress": "", "contactNumber": "", "contactZip": "", "contactCity": "", "contactCountry": "", "contactTelephone": "", "contactFax": "", "contactEmail": "", "description": "", "paymentMethod": "-", "invoicingParty": "" } ] Create a publisher POST /v1/inventory/publisher Creates a new publisher. Request body Parameter In Required Type Description parentPublisherId body No integer The ID of the parent publisher. Leave blank if the new publisher is a main publisher name body Yes string Name of the publisher active body No boolean Is the publisher active? Default is  true Creating a new publisher { "parentPublisherId": 1, "name": "Example API Publisher", "active": true } Response - 201 { "id": 3, "parentId": 1, "companyName": "Example API Publisher", "quote": "", "active": 1, "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTelephone": "", "companyFax": "", "companyEmail": "", "companyURL": "", "companyVat": "", "companyBankAccount": "", "contactName": "", "contactFirstName": "", "contactAddress": "", "contactNumber": "", "contactZip": "", "contactCity": "", "contactCountry": "", "contactTelephone": "", "contactFax": "", "contactEmail": "", "description": "", "paymentMethod": "-", "invoicingParty": "" } Response codes Status Meaning 201 Publisher created. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Publications List a publication GET /v1/inventory/publication/{id} List a single publication by ID. Request body Parameter In Required Type Description id path Yes integer The publisher's ID. Response - 200 { "id": 3, "companyName": "Demo Sponsored Placements", "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTel": "", "companyFax": "", "companyUrl": "https://pool-demo.adhese.com/projects/marketing/index.html", "companyEmail": "", "publishersId": 1, "quote": "", "parentPublicationsId": 0, "description": "", "comment": "", "active": 1, "rank": 0, "screenshotExtension": "", "catchphrase": "", "language": "", "numberOfAuthors": 0, "inventoryCategory": "sponsored_product" } Response codes Status Meaning 200 Publication retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Update a publication PUT /v1/inventory/publication/{id} Updates the name, parent publisher, active status, quote and website of an existing publication. Fields the request omits are left as they are. Request body Parameter In Required Type Description parentPublisherId body No integer The ID of the publication's publisher. active body No boolean Is the publication active? Default is true. name body Yes string Name of the publication. quote body No string Quote field of the publication. website body Yes string Website of the publication. Updating a publication { "publisherId": 1, "active": true, "name": "Demo Display", "quote": "DD", "website": "https://pool-demo.adhese.com/projects/marketing/index.html" } Response - 200 { "id": 1, "companyName": "Demo Display", "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTel": "", "companyFax": "", "companyUrl": "https://pool-demo.adhese.com/projects/marketing/index.html", "companyEmail": "", "publishersId": 1, "quote": "DD", "parentPublicationsId": 0, "description": "", "comment": "", "active": 1, "rank": 0, "screenshotExtension": "", "catchphrase": "", "language": "", "numberOfAuthors": 0, "inventoryCategory": "display" } Response codes Status Meaning 200 Publication retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Delete a publication DELETE /v1/inventory/publication/{id} Sets a publication to inactive. Request body Parameter In Required Type Description id path Yes integer The publication's ID. Response codes Status Meaning 204 Publication set to inactive. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. List all publications under a publisher GET /v1/inventory/publication List all publications under one or more publishers. Request body Parameter In Required Type Description publisherIds parameter Yes integer The publisher IDs whose publications you want listed. The publisher IDs are comma separated. Response - 200 [ { "id": 1, "companyName": "Demo Display", "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTel": "", "companyFax": "", "companyUrl": "https://pool-demo.adhese.com/projects/marketing/index.html", "companyEmail": "", "publishersId": 1, "quote": "DD", "parentPublicationsId": 0, "description": "", "comment": "", "active": 1, "rank": 0, "screenshotExtension": "", "catchphrase": "", "language": "", "numberOfAuthors": 0, "inventoryCategory": "display" }, { "id": 2, "companyName": "Demo DOOH", "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTel": "", "companyFax": "", "companyUrl": "https://adhese.eu", "companyEmail": "", "publishersId": 1, "quote": "", "parentPublicationsId": 0, "description": "", "comment": "", "active": 1, "rank": 0, "screenshotExtension": "", "catchphrase": "", "language": "", "numberOfAuthors": 0, "inventoryCategory": "in_store" }, { "id": 3, "companyName": "Demo Sponsored Placements", "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTel": "", "companyFax": "", "companyUrl": "https://pool-demo.adhese.com/projects/marketing/index.html", "companyEmail": "", "publishersId": 1, "quote": "", "parentPublicationsId": 0, "description": "", "comment": "", "active": 1, "rank": 0, "screenshotExtension": "", "catchphrase": "", "language": "", "numberOfAuthors": 0, "inventoryCategory": "sponsored_product" } ] Response codes Status Meaning 200 Publications retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Create a publication POST /v1/inventory/publication Create a new publication. Request body Parameter In Required Type Description publisherId body No integer The ID of the parent publisher. Leave blank if the new publisher is a main publisher active body No boolean Is the publication active? Default is true. name body Yes string Name of the publication. quote body No string Quote field of the publication. website body Yes string Website of the publication. Creating a new publication { "publisherId": 3, "active": true, "name": "String Created Publication", "quote": "SCP", "website": "https://pool-demo.adhese.com/projects/marketing/index.html" } Response - 201 { "id": 5, "companyName": "String Created Publication", "companyAddress": "", "companyNumber": "", "companyZip": "", "companyCity": "", "companyCountry": "", "companyTel": "", "companyFax": "", "companyUrl": "https://pool-demo.adhese.com/projects/marketing/index.html", "companyEmail": "", "publishersId": 3, "quote": "SCP", "parentPublicationsId": 0, "description": "", "comment": "", "active": 1, "rank": 0, "screenshotExtension": "", "catchphrase": "", "language": "", "numberOfAuthors": 0, "inventoryCategory": null } Response codes Status Meaning 201 Publication created. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Positions List a single position GET /v1/inventory/position/{id} Lists the chosen positions information by ID. Request body Parameter In Required Type Description positionId path Yes integer The position ID whose information you want listed. Response - 200 { "id": 9, "publisherId": 1, "transferId": 0, "active": true, "creation": "Mar 25, 2026, 2:31:29 PM CET", "edited": "Mar 25, 2026, 2:31:29 PM CET", "name": "", "formatId": 4, "formatName": "Billboard", "formatWidth": 970, "formatHeight": 250, "formatSize": 0, "locationId": 5, "locationName": "ROS", "locationTypeId": 10, "publicationName": "Demo Display", "previewUrl": "", "url": "" } Response codes Status Meaning 200 Position listed. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Updating a position PUT /v1/inventory/position/{id} Updates a chosen positions name, format, location, position type, active status, and URL. Fields the request omits are left as they are. Request body Parameter In Required Type Description id path Yes integer The positions ID. active body No boolean Whether the position is active or not. name body No string Name of the position, recommended for use with the Campaign Manager UI. formatId body No integer ID of the positions format. locationId body No integer ID of the positions location. url body No string URL for identifying the position. positionTypeId body No integer ID of the position type (when applicable). Updating a position { "active": true, "name": "SCP Halfpage", "formatId": 1, "locationId": 9, "url": "_scp_halfpage", "positionTypeId": 10 } Response - 200 { "id": 19, "publisherId": 5, "transferId": 0, "active": true, "creation": "Sep 22, 2026, 11:46:01 AM CEST", "edited": "Sep 22, 2026, 11:52:26 AM CEST", "name": "SCP Halfpage", "formatId": 1, "formatName": "Halfpage", "formatWidth": 300, "formatHeight": 600, "formatSize": 0, "locationId": 9, "locationName": "SCP", "locationTypeId": 10, "publicationName": "String Created Publication", "previewUrl": "", "url": "_scp_halfpage" } Response codes Status Meaning 200 Position updated. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Delete a position DELETE /v1/inventory/position/{id} Sets a position to inactive by ID. Request body Parameter In Required Type Description positionId path Yes integer The ID of the position you want deactivated. Response codes Status Meaning 204 Position set to inactive. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. List all positions GET /v1/inventory/position List the details of all positions. Request body Parameter In Required Type Description publicationId body No integer The publication ID of the publication you want to filter positions on. active body No boolean Filter on the active or inactive status of positions. Response - 200 [ { "id": 1, "publisherId": 1, "transferId": 0, "active": true, "creation": "Mar 13, 2026, 3:09:34 PM CET", "edited": "Mar 13, 2026, 3:09:34 PM CET", "name": "", "formatId": 4, "formatName": "Billboard", "formatWidth": 970, "formatHeight": 250, "formatSize": 0, "locationId": 2, "locationName": "Kitchen", "locationTypeId": 10, "publicationName": "Demo Display", "previewUrl": "", "url": "" }, { "id": 2, "publisherId": 1, "transferId": 0, "active": true, "creation": "Mar 13, 2026, 3:09:46 PM CET", "edited": "Mar 13, 2026, 3:12:44 PM CET", "name": "", "formatId": 1, "formatName": "Halfpage", "formatWidth": 300, "formatHeight": 600, "formatSize": 0, "locationId": 2, "locationName": "Kitchen", "locationTypeId": 10, "publicationName": "Demo Display", "previewUrl": "", "url": "" }, { "id": 3, "publisherId": 1, "transferId": 0, "active": true, "creation": "Mar 13, 2026, 3:09:59 PM CET", "edited": "Mar 13, 2026, 3:12:56 PM CET", "name": "", "formatId": 3, "formatName": "Wide Skyscraper", "formatWidth": 160, "formatHeight": 600, "formatSize": 0, "locationId": 3, "locationName": "Electronics", "locationTypeId": 10, "publicationName": "Demo Display", "previewUrl": "", "url": "" }, ] Response codes Status Meaning 200 Positions listed. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Create a position POST /v1/inventory/position Creates a new position (ad slot) linked to a location, format, and position type. A request that omits the active status creates an active position. Request body Parameter In Required Type Description active body No boolean Whether the position is active or not. A request that omits the active status creates an active position. name body No string Name of the position, recommended for use with the Campaign Manager UI. formatId body Yes integer ID of the positions format. locationId body Yes integer ID of the positions location. url body No string URL for identifying the position. positionTypeId body No integer ID of the position type (when applicable). Creating a new position { "active": true, "name": "SCP Billboard", "formatId": 4, "locationId": 9, "url": "_scp_billboard", "positionTypeId": 10 } Response - 201 { "id": 20, "publisherId": 5, "transferId": 0, "active": true, "creation": "Sep 22, 2026, 1:56:07 PM CEST", "edited": "Sep 22, 2026, 1:56:07 PM CEST", "name": "SCP Billboard", "formatId": 4, "formatName": "Billboard", "formatWidth": 970, "formatHeight": 250, "formatSize": 0, "locationId": 9, "locationName": "SCP", "locationTypeId": 10, "publicationName": "String Created Publication", "previewUrl": null, "url": "_scp_billboard" } Response codes Status Meaning 201 Position created. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Locations List a single location GET /v1/inventory/location/{id} Retrieves a single location by its ID. Request body Parameter In Required Type Description locationId path Yes integer The location ID of the location you want to list. Response - 200 { "id": 9, "name": "SCP", "publicationId": 5, "publicationQuote": "SCP", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "scp_home", "previewUrl": "", "code": null, "price": 0.0, "active": true, "locationTypes": [ "full", "guaranteed" ], "numberOfBookings": 0 } Response codes Status Meaning 200 Location listed. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Update a location PUT /v1/inventory/location/{id} Updates the name, URL, channel option code, publication, and location types of an existing location. Request body Parameter In Required Type Description locationId path Yes integer The location ID of the location you want to list. publicationId body Yes integer ID of the publication to which the location belongs. name body No string Name of the location. url body No string URL for identifying the location on the webpage. channelOptionCode body No integer Determines if the location is for single positions or Channels. 0 means single position. Use Use GET /v1/inventory/location-channel-option for other valid channelOptionCode values for your account. locationTypes body No string Location types that belong to this location. Options are guranteed and/or full code body No string Location code. price body No integer Location price. Response - 200 { "id": 9, "name": "SCP", "publicationId": 5, "publicationQuote": "SCP", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "scp_overview", "previewUrl": "", "code": "001", "price": 1.0, "active": true, "locationTypes": [ "full", "guaranteed" ], "numberOfBookings": 0 } Response codes Status Meaning 200 Location updated. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Delete a location DELETE /v1/inventory/location/{id} Set a location to inactive by ID. Request body Parameter In Required Type Description locationId path Yes integer The ID of the location that you want deactivated. Response codes Status Meaning 204 Location set to inactive. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. List all locations by publication GET /v1/inventory/location Lists all locations under a publication by it's ID. Request body Parameter In Required Type Description publicationId parameters Yes integer The ID of the publication for which you want to list all locations. Response - 200 [ { "id": 4, "name": "Audio", "publicationId": 1, "publicationQuote": "DD", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "demo.com_audio", "previewUrl": "", "code": null, "price": 5.0, "active": true, "locationTypes": [ "full" ], "numberOfBookings": 0 }, { "id": 3, "name": "Electronics", "publicationId": 1, "publicationQuote": "DD", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "demo.com_electronics", "previewUrl": "", "code": null, "price": 5.0, "active": true, "locationTypes": [ "full", "guaranteed" ], "numberOfBookings": 0 }, { "id": 1, "name": "Home", "publicationId": 1, "publicationQuote": "DD", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "demo.com_home", "previewUrl": "", "code": "demo_web_home", "price": 5.0, "active": true, "locationTypes": [ "full", "guaranteed" ], "numberOfBookings": 3 }, { "id": 2, "name": "Kitchen", "publicationId": 1, "publicationQuote": "DD", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "demo.com_kitchen", "previewUrl": "", "code": null, "price": 5.0, "active": true, "locationTypes": [ "full" ], "numberOfBookings": 0 }, { "id": 5, "name": "ROS", "publicationId": 1, "publicationQuote": "DD", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 3, "url": "", "previewUrl": "", "code": null, "price": 5.0, "active": true, "locationTypes": [ "full" ], "numberOfBookings": 1 } ] Response codes Status Meaning 200 Locations listed. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Create a new location POST /v1/inventory/location Create a new location under a publication by ID. Request body Parameter In Required Type Description publicationId body Yes integer ID of the publication to which the location belongs. name body No string Name of the location. url body No string URL for identifying the location on the webpage. channelOptionCode body No integer Determines if the location is for single positions or Channels. 0 means single position. Use Use GET /v1/inventory/location-channel-option for other valid channelOptionCode values for your account. locationTypes body No string Location types that belong to this location. Options are guranteed and/or full code body No string Location code. price body No integer Location price. Response - 201 { "id": 11, "name": "SCP BR", "publicationId": 5, "publicationQuote": "SCP", "impressions": 0, "impressionsWeekend": 0, "contacts": 0, "contactsWeekend": 0, "isChannel": 0, "url": "scp_br", "previewUrl": null, "code": "002", "price": 1.2, "active": true, "locationTypes": [ "full", "guaranteed" ], "numberOfBookings": 0 } Response codes Status Meaning 201 Location created. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. Miscellaneous Inventory APIs List position types GET /v1/inventory/position-type Lists all available position types for the account. Response - 200 [ { "id": 1, "name": "", "templateFile": "", "thirdPartyQuotum": 0 }, { "id": 13, "name": "newsletter img tag", "templateFile": "", "thirdPartyQuotum": 0 }, { "id": 10, "name": "normal javascript", "templateFile": "", "thirdPartyQuotum": 0 }, { "id": 12, "name": "normal javascript / no empty", "templateFile": "", "thirdPartyQuotum": 0 } ] Response codes Status Meaning 200 Position types retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. List location channel options GET /v1/inventory/location-channel-option Lists all location channel options (such as normal position and available group levels). Response - 200 [ { "code": 0, "name": "normal position (no group)" }, { "code": 1, "name": "group level 1" }, { "code": 2, "name": "group level 2" }, { "code": 3, "name": "group level 3" }, { "code": 4, "name": "group level 4" }, { "code": 5, "name": "group level 5" } ] Response codes Status Meaning 200 Location channel options retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure. List available formats GET /v1/inventory/format Retrieves all available ad formats (templates) that can be assigned to positions. Response - 200 [ { "id": 4, "name": "Billboard", "width": 970, "height": 250, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "billboard", "codeBook": "billboard" }, { "id": 1, "name": "Halfpage", "width": 300, "height": 600, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "halfpage", "codeBook": "halfpage" }, { "id": 6, "name": "Landscape Screen", "width": 16, "height": 9, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "landscape", "codeBook": "landscape" }, { "id": 5, "name": "Leaderboard", "width": 728, "height": 90, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "leaderboard", "codeBook": "leaderboard" }, { "id": 2, "name": "Medium Rectangle", "width": 300, "height": 250, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "imu", "codeBook": "imu;halfpage" }, { "id": 7, "name": "Portrait Screen", "width": 9, "height": 16, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "portrait", "codeBook": "portrait" }, { "id": 3, "name": "Wide Skyscraper", "width": 160, "height": 600, "active": true, "comment": "", "templateFile": "", "allTogetherOrder": 0, "hasCompletionRateEvents": 0, "codeTag": "skyscraper", "codeBook": "skyscraper" } ] Response codes Status Meaning 200 Formats retrieved. 400 Bad request - invalid input or parameters. 401/ 403 Not authenticated / not allowed. 404 Not Found - Resource not found. 405 Method not allowed 406 Not acceptable 409 Conflict. 415 Unsupported media type 500 Internal Server Error - Unexpected failure.