Vertical Taxonomy Translation

Audience

This API surface is for integration partners building on top of the Rokt network. Rokt ecommerce partners integrating placements on their own checkout should use the Rokt Ecommerce developer docs instead.

Your platform has its own vertical taxonomy (MCC codes, category IDs, your internal scheme), and Rokt has its own internal taxonomy of ~24 verticals and ~152 sub-verticals. The Partnerships API speaks your taxonomy on the wire. The server translates to Rokt's IDs through a vertical mapping table keyed by your platform_parent_account_id.

Where translation happens: register and MCL PUTs

The vertical mapping is consulted on two partner-facing call shapes — not just marketplace controls:

• POST /v1/accounts/register/partnership — the vertical_id and sub_vertical_id fields on the request body are your partner-taxonomy values, resolved server-side against partnership_vertical_map for your platform_parent_account_id. If either ID has no mapping row, register fails with 400 before the merchant is created.
• PUT /v1/partnership/accounts/{account_id}/marketplacecontrolslists — each {partnerVerticalId, partnerSubVerticalId} pair in blockedVerticals is resolved the same way. See the next section for the atomic-400 behavior.

Both share the same partnership_vertical_map table, scoped to your platform_parent_account_id. Onboard a new partner-side vertical once and it works on both surfaces immediately.

remarque

Mapping rows are seeded by Rokt out-of-band through an admin-only POST /v1/partnership/vertical-mappings endpoint — it's not exposed on the partner API surface. Email smb-partnerships@rokt.com with {partner_vertical_id, partner_sub_vertical_id, partner_name} triples and the target Rokt vertical for each; Rokt operations runs the admin call against your platform_parent_account_id.

Forward translation (on PUT)

When you send a PUT /…/marketplacecontrolslists:

{
  "blockedVerticals": [
    { "partnerVerticalId": 1500, "partnerSubVerticalId": 1610, "policy": "Block" }
  ]
}

For each {partnerVerticalId, partnerSubVerticalId} pair, the server looks up the row in the vertical mapping scoped to your platform_parent_account_id and resolves it to a Rokt vertical_id. The mapping is many-to-one: multiple partner pairs can legitimately resolve to the same Rokt vertical, and that's fine — your taxonomy is finer-grained or coarser-grained than Rokt's, and we preserve fidelity by storing both sides.

your taxonomy                       vertical mapping                  rokt taxonomy
{ 1500, 1610 }    ─────translate────▶  parent_account_id=2849096…  ───▶  rokt_vertical_id=42
{ 1500, 1611 }    ─────translate────▶  parent_account_id=2849096…  ───▶  rokt_vertical_id=42
{ 1502, 1620 }    ─────translate────▶  parent_account_id=2849096…  ───▶  rokt_vertical_id=58

Missing mapping = atomic 400

If any pair in your blockedVerticals array has no corresponding row in the vertical mapping, the whole request rejects with 400. There are no partial writes — the request is atomic.

{
  "status": 400,
  "error": "BadRequest",
  "message": "No partnership vertical mapping exists for MCL translation",
  "request_id": "req_01HX9F2J7M3K8N5VYBQZP4R6T2",
  "data": null
}

attention

Add taxonomy rows before launch, not after. If you're onboarding new partner verticals, email smb-partnerships@rokt.com with the list of {partner_vertical_id, partner_sub_vertical_id, partner_name} triples and the target Rokt vertical for each. Mapping rows are added out-of-band — there's no self-serve route in the API today.

You can surface a 400 safely without committing by using dry_run=true — useful in your onboarding UI to validate a merchant's category selection before the real save.

Reverse translation (on GET)

When you GET marketplace controls, the response includes both the raw Rokt-side verticals list and a partner-friendly translatedVerticals block:

{
  "accountId": "<your-account-id>",
  "marketplaceControlsListId": "8c8e1c12-...",
  "name": "Acme Network Controls",
  "verticals": [
    {
      "verticalId": 42,
      "policy": "Block",
      "position1Policy": "Block"
    }
  ],
  "translatedVerticals": [
    {
      "partner_vertical_id": 1500,
      "partner_sub_vertical_id": 1610,
      "partner_vertical_name": "Apparel",
      "partner_sub_vertical_name": "Activewear",
      "rokt_vertical_id": 42,
      "rokt_subvertical_id": 4210
    }
  ],
  "domains": [],
  "contentHash": "h_abc123"
}

Use translatedVerticals in your UI — your end users think in their taxonomy. The raw verticals list with Rokt IDs is for support and audit only; ignore it in the happy path.

astuce

translatedVerticals round-trips your exact {partnerVerticalId, partnerSubVerticalId} pair from the PUT. If many partner pairs map to the same Rokt vertical, you still see one translatedVerticals entry per pair you sent — no information loss across the round-trip.

Walkthrough: full round-trip

1. 1
   PUT with a partner-taxonomy pair

   curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
     -H "Authorization: Bearer $ROKT_TOKEN" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Acme Network Controls",
       "blockedVerticals": [
         {"partnerVerticalId": 1500, "partnerSubVerticalId": 1610, "policy": "Block", "position1Policy": "Block"}
       ],
       "domains": []
     }'

   Server resolves {1500, 1610} → rokt_vertical_id: 42, persists both, returns 200.

2. 2
   GET the controls back

   curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
     -H "Authorization: Bearer $ROKT_TOKEN"

3. 3
   Observe both sides of the translation

   The response carries:

   • verticals[0].verticalId = 42 (Rokt side — for support)
   • translatedVerticals[0].partner_vertical_id = 1500, partner_sub_vertical_id = 1610 (your side — for UI)
   • translatedVerticals[0].rokt_vertical_id = 42 (the join, for cross-reference)

   Render translatedVerticals in your dashboard. The merchant sees the categories they understand.

Pre-flight checklist before launch

• All partner verticals you intend to expose to merchants have rows in your vertical mapping for your platform_parent_account_id.
• Your onboarding UI surfaces only mapped partner verticals (or uses dry_run=true to validate before letting the merchant save).
• Your dashboard renders from translatedVerticals, not from raw verticals.
• You have an internal owner who owns the partner-side taxonomy and emails smb-partnerships when it changes.

Related

SET Semantics

Why you must send the full blockedVerticals array on every PUT.

Dry-Run Mode

Surface missing-mapping 400s without touching state.