# Advertiser - Companies API

## Create advertiser & invoicing companies

Both are created with the **same endpoint**; the `roles` array is what makes a company an advertiser, an invoicing party, or both.

### Create a company

```
POST /v1/media-partners
```

Creates a media partner (advertiser company, invoicing company, or both, depending on `roles`).

**Request body** — `CreateMediaPartnerRequest`

<table id="bkmrk-field-type-required-"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>string</td><td>Yes</td><td>Display name of the company.</td></tr><tr><td><code>roles</code></td><td>array of enum</td><td>Yes</td><td>Any of <code>ADVERTISER</code>, <code>INVOICE</code></td></tr><tr><td><code>externalKey</code></td><td>string</td><td>No</td><td>Your own external reference key.</td></tr><tr><td><code>subsystemExternalIds</code></td><td>object (string → string)</td><td>No</td><td>External ids per subsystem.</td></tr></tbody></table>

**Create an advertiser company**

```json
{
  "name": "Acme Beverages",
  "roles": ["ADVERTISER"],
  "externalKey": "acme-bev",
  "subsystemExternalIds": {
    "crm": "CRM-10432"
  }
}
```

**Create an invoicing company**

```json
{
  "name": "Acme Beverages Billing BV",
  "roles": ["INVOICE"],
  "externalKey": "acme-bev-billing"
}
```

**Create a company that is both advertiser and invoicing party**

```json
{
  "name": "Acme Beverages",
  "roles": ["ADVERTISER", "INVOICE"]
}
```

**Responses**

<table id="bkmrk-status-meaning-201-m"><thead><tr><th>Status</th><th>Meaning</th></tr></thead><tbody><tr><td><code>201</code></td><td>Media partner created.</td></tr><tr><td><code>400</code></td><td>Invalid input (e.g. empty `name` or unknown role).</td></tr><tr><td><code>401</code> / <code>403</code></td><td>Not authenticated / not allowed.</td></tr><tr><td><code>500</code></td><td>Unexpected failure.</td></tr></tbody></table>

> 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
```

<table id="bkmrk-parameter-in-require" style="width: 92.619%; height: 178.781px;"><thead><tr style="height: 29.7969px;"><th style="width: 15.6812%; height: 29.7969px;">Parameter</th><th style="width: 7.29635%; height: 29.7969px;">In</th><th style="width: 10.0337%; height: 29.7969px;">Required</th><th style="width: 9.43123%; height: 29.7969px;">Type</th><th style="width: 57.3868%; height: 29.7969px;">Description</th></tr></thead><tbody><tr style="height: 29.7969px;"><td style="width: 15.6812%; height: 29.7969px;"><code>limit</code></td><td style="width: 7.29635%; height: 29.7969px;">query</td><td style="width: 10.0337%; height: 29.7969px;">Yes</td><td style="width: 9.43123%; height: 29.7969px;">integer</td><td style="width: 57.3868%; height: 29.7969px;">Max number of results to return.</td></tr><tr style="height: 29.7969px;"><td style="width: 15.6812%; height: 29.7969px;"><code>offset</code></td><td style="width: 7.29635%; height: 29.7969px;">query</td><td style="width: 10.0337%; height: 29.7969px;">Yes</td><td style="width: 9.43123%; height: 29.7969px;">integer</td><td style="width: 57.3868%; height: 29.7969px;">Number of results to skip.</td></tr><tr style="height: 29.7969px;"><td style="width: 15.6812%; height: 29.7969px;"><code>search</code></td><td style="width: 7.29635%; height: 29.7969px;">query</td><td style="width: 10.0337%; height: 29.7969px;">No</td><td style="width: 9.43123%; height: 29.7969px;">string</td><td style="width: 57.3868%; height: 29.7969px;">URL-encoded, case-insensitive match on name.</td></tr><tr style="height: 29.7969px;"><td style="width: 15.6812%; height: 29.7969px;"><code>roles</code></td><td style="width: 7.29635%; height: 29.7969px;">query</td><td style="width: 10.0337%; height: 29.7969px;">No</td><td style="width: 9.43123%; height: 29.7969px;">array</td><td style="width: 57.3868%; height: 29.7969px;">Filter on the role(s) the media partner has, e.g. `roles=ADVERTISER`.</td></tr><tr style="height: 29.7969px;"><td style="width: 15.6812%; height: 29.7969px;"><code>includeInactive</code></td><td style="width: 7.29635%; height: 29.7969px;">query</td><td style="width: 10.0337%; height: 29.7969px;">No</td><td style="width: 9.43123%; height: 29.7969px;">boolean</td><td style="width: 57.3868%; height: 29.7969px;">Include deactivated media partners.</td></tr></tbody></table>

**Response** — array of `MediaPartner Schema`

```json
[
  {
    "id": 4021,
    "name": "Acme Beverages",
    "roles": ["ADVERTISER"],
    "externalKey": "acme-bev",
    "subsystemExternalIds": { "crm": "CRM-10432" },
    "active": true
  }
]
```

### Get a single company

```
GET /v1/media-partners/{mediaPartnerId}

```

<table id="bkmrk-parameter-in-require-1"><thead><tr><th>Parameter</th><th>In</th><th>Required</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>mediaPartnerId</code></td><td>path</td><td>Yes</td><td>integer</td><td>The id of the media partner.</td></tr></tbody></table>

Returns a single `MediaPartner Schema` (same shape as above).