Media Partners API

Media Partners

Media partners is the overarching term for an advertiser or debtor. Media parntners 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.

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 fetch.

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.

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}

Returns a single MediaBrand Schema.