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

<table id="bkmrk-field-type-required--2"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>user</code></td><td>string (1–255)</td><td>Yes</td><td>User identifier (e.g. email or username).</td></tr><tr><td><code>mappings</code></td><td>array of `Mapping Schema`</td><td>Yes</td><td>At least one mapping entry.</td></tr></tbody></table>

**Mapping Schema**

<table id="bkmrk-field-type-required--3"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>advertiserCompanyId</code></td><td>integer (≥ 1)</td><td>Yes</td><td>The advertiser company to grant access to.</td></tr><tr><td><code>invoiceCompanyId</code></td><td>integer</td><td>No</td><td>Restrict the mapping to a specific invoicing company.</td></tr><tr><td><code>brandId</code></td><td>integer (≥ 1)</td><td>Yes</td><td>The brand to grant access to.</td></tr></tbody></table>

```json
{
  "user": "jane.doe@partner.example",
  "mappings": [
    {
      "advertiserCompanyId": 4021,
      "invoiceCompanyId": 4022,
      "brandId": 8801
    }
  ]
}
```

**Responses**

<table id="bkmrk-status-meaning-201-u"><thead><tr><th>Status</th><th>Meaning</th></tr></thead><tbody><tr><td><code>201</code></td><td>User mapping created.</td></tr><tr><td><code>400</code></td><td>Invalid input (e.g. missing `advertiserCompanyId` or `brandId`).</td></tr><tr><td><code>401</code> / <code>403</code></td><td>Not authenticated / not allowed.</td></tr></tbody></table>

### List users with mappings

```
GET /v1/user-mapping?limit=50&offset=0
```

<table id="bkmrk-parameter-in-require-6"><thead><tr><th>Parameter</th><th>In</th><th>Required</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>limit</code></td><td>query</td><td>No</td><td>integer</td><td>Max results (≤ 100).</td></tr><tr><td><code>offset</code></td><td>query</td><td>No</td><td>integer</td><td>Results to skip.</td></tr><tr><td><code>search</code></td><td>query</td><td>No</td><td>string</td><td>Loose match on user identifier.</td></tr><tr><td><code>advertiserCompanyId</code></td><td>query</td><td>No</td><td>integer</td><td>Only users mapped to this advertiser company.</td></tr><tr><td><code>invoiceCompanyId</code></td><td>query</td><td>No</td><td>integer</td><td>Only users mapped to this invoice company.</td></tr><tr><td><code>brandId</code></td><td>query</td><td>No</td><td>integer</td><td>Only users mapped to this brand.</td></tr></tbody></table>

The response includes a `Record-Count` header with the total number of matches.

**Response** — array of `UserMapping Schema`

```json
[
  { "user": "jane.doe@partner.example", "mappingCount": 3 }
]
```

### List a single user's mappings

```
GET /v1/user-mapping/{user}
```

<table id="bkmrk-parameter-in-require-7"><thead><tr><th>Parameter</th><th>In</th><th>Required</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>user</code></td><td>path</td><td>Yes</td><td>string</td><td>The user identifier.</td></tr><tr><td><code>limit</code> / <code>offset</code></td><td>query</td><td>No</td><td>integer</td><td>Pagination.</td></tr><tr><td><code>advertiserCompanyId</code></td><td>query</td><td>No</td><td>integer</td><td>Filter by advertiser company.</td></tr><tr><td><code>invoiceCompanyId</code></td><td>query</td><td>No</td><td>integer</td><td>Filter by invoice company.</td></tr><tr><td><code>brandId</code></td><td>query</td><td>No</td><td>integer</td><td>Filter by brand.</td></tr></tbody></table>

**Response** — array of `Mapping Schema`

```json
[
  {
    "advertiserCompanyId": 4021,
    "invoiceCompanyId": 4022,
    "brandId": 8801
  }
]
```

### Delete a user mapping

```
DELETE /v1/user-mapping
```

**Request body** — `DeleteUserMappingRequest`

<table id="bkmrk-field-type-required--4"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>user</code></td><td>string (1–255)</td><td>Yes</td><td>The user identifier.</td></tr><tr><td><code>advertiserCompanyId</code></td><td>integer (≥ 1)</td><td>—</td><td>Advertiser company of the mapping to remove.</td></tr><tr><td><code>invoiceCompanyId</code></td><td>integer</td><td>—</td><td>Invoice company of the mapping to remove.</td></tr><tr><td><code>brandId</code></td><td>integer (≥ 1)</td><td>—</td><td>Brand of the mapping to remove.</td></tr></tbody></table>

```json
{
  "user": "jane.doe@partner.example",
  "advertiserCompanyId": 4021,
  "invoiceCompanyId": 4022,
  "brandId": 8801
}
```

Responds `200` when the mapping is deleted.