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.
Revision #1
Created 2026-09-23 09:50:50 UTC by Casper Steuperaert
Updated 2026-09-23 09:51:13 UTC by Casper Steuperaert