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

Field	Type	Required	Description
user	string (1–255)	Yes	User identifier (e.g. email or username).
mappings	array of `Mapping Schema`	Yes	At least one mapping entry.

Mapping Schema

Field	Type	Required	Description
advertiserCompanyId	integer (≥ 1)	Yes	The advertiser company to grant access to.
invoiceCompanyId	integer	No	Restrict the mapping to a specific invoicing company.
brandId	integer (≥ 1)	Yes	The brand to grant access to.

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

Responses

Status	Meaning
201	User mapping created.
400	Invalid input (e.g. missing `advertiserCompanyId` or `brandId`).
401 / 403	Not authenticated / not allowed.

List users with mappings

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

Parameter	In	Required	Type	Description
limit	query	No	integer	Max results (≤ 100).
offset	query	No	integer	Results to skip.
search	query	No	string	Loose match on user identifier.
advertiserCompanyId	query	No	integer	Only users mapped to this advertiser company.
invoiceCompanyId	query	No	integer	Only users mapped to this invoice company.
brandId	query	No	integer	Only users mapped to this brand.

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

Response — array of UserMapping Schema

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

List a single user's mappings

GET /v1/user-mapping/{user}

Parameter	In	Required	Type	Description
user	path	Yes	string	The user identifier.
limit / offset	query	No	integer	Pagination.
advertiserCompanyId	query	No	integer	Filter by advertiser company.
invoiceCompanyId	query	No	integer	Filter by invoice company.
brandId	query	No	integer	Filter by brand.

Response — array of Mapping Schema

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

Delete a user mapping

DELETE /v1/user-mapping

Request body — DeleteUserMappingRequest

Field	Type	Required	Description
user	string (1–255)	Yes	The user identifier.
advertiserCompanyId	integer (≥ 1)	—	Advertiser company of the mapping to remove.
invoiceCompanyId	integer	—	Invoice company of the mapping to remove.
brandId	integer (≥ 1)	—	Brand of the mapping to remove.

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

Responds 200 when the mapping is deleted.