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