メインコンテンツまでスキップ
API docs by Redocly

Rokt Partnerships API (0.1.0-preview)

Rokt Partnerships Engineering: smb-partnerships@rokt.com

Partner-facing REST API for white-label onboarding of merchant accounts onto the Rokt network. Designed for SMB tech platforms to register merchants, configure marketplace and offer controls, and manage placement status, all without a manual Rokt UI step.

PREVIEW: Subject to Change. This API surface is in active development. Payloads, endpoints, and behavior may shift. Rokt will notify you of any breaking change.

Two cross-cutting contracts to bind to before any call

1. Every response is enveloped. Success and error responses use the same wrapper:

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-...-...",
  "data": { /* endpoint-specific payload */ }
}

Your client should read the endpoint payload from data, not from the response root. The request_id is the correlation ID for support tickets.

Exception: POST /v1/partnership/network-privacy-requests returns a direct privacy request response rather than the partnership envelope.

2. X-Platform-Parent-Account-Id is required on every write. Every write call (POST /register, PUT /marketplacecontrolslists, PUT /status, POST /payout-setup) must include the X-Platform-Parent-Account-Id header set to your partner platform's Rokt parent account ID. Reads accept the header as optional. Missing it on a write returns 422.

Exception: POST /v1/partnership/network-privacy-requests takes parent_account_id as a query parameter and does not require Idempotency-Key.

Accounts

Register and list managed merchant accounts.

Register a managed merchant

Creates (or matches) a Rokt account for a merchant onboarded via your platform. Idempotent on external_account_id: sending the same external_account_id twice returns the same account_id without creating a duplicate.

Conflict behavior

  • 200: New account created OR existing account matched via external_account_id. The same account_id is returned in both cases.
  • 409: A different Rokt integration is already attached to this store_identifier (e.g. another platform already registered the same storefront URL). Surface the prompt below to the merchant.

store_identifier must be a valid URL (3–400 chars). Send the full origin including scheme, e.g. https://acme.myshopify.com, not just acme.myshopify.com. The server rejects bare hostnames with 400.

Wait 1–2 minutes before calling other endpoints on the new account_id. Auth propagation for newly-created merchant accounts is asynchronous. Calls to controls, status, or payout-setup endpoints immediately after a successful register may return 401 or 403 until propagation completes. Retry with backoff for the first 1–2 minutes after registration before treating an auth failure as terminal.

Rate limit: 10 requests/minute per partner. See Rate Limits.

Authorizations:
ApiToken
header Parameters
X-Platform-Parent-Account-Id
required
string
Example: <your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Required on every write call. Missing returns 422; mismatch with the managed account's actual parent returns 403.

Request Body schema: application/json
required
brand
required
string <= 200 characters

Display name of the merchant.

vertical_id
required
integer

Partner-taxonomy vertical ID. Translated server-side to Rokt's taxonomy via your vertical mapping.

sub_vertical_id
required
integer

Partner-taxonomy sub-vertical ID.

country_code
required
string^[A-Z]{2}$

ISO 3166-1 alpha-2 country code, uppercase.

platform_parent_account_id
required
string

Your partner platform's Rokt parent account ID.

store_identifier
required
string <uri> [ 3 .. 400 ] characters

Stable URL identifying the merchant's storefront. Used for cross-partner conflict detection.

external_account_id
required
string

Your stable identifier for the merchant in your own system. Idempotency key for registration.

user_identifier
required
string [ 1 .. 255 ] characters

Identifier of the user initiating the signup on your platform, typically the merchant owner's email address or your stable internal user ID. Stored as the audit tag partnership_signup_user_identifier on the created account for consent / compliance trails. Required; non-empty after trimming; max 255 characters.

Array of objects (RegisterPartnershipPage) non-empty

Optional for most integrations: when omitted, Rokt creates the preset's default page set (typically confirmation + Overlay). When supplied, Rokt creates one page + layout per entry instead.

A subset of integrations require pages to be passed explicitly because their primary surface isn't confirmation (e.g. tracking-focused integrations). Omitting pages for those returns 400 with a message naming the surfaces and layout types your preset accepts. Consult your Rokt contact if you're unsure whether your integration requires pages.

Constraints: at least one entry when supplied; each surface may appear only once. Empty arrays are rejected (omit the field to use the preset default, or include at least one entry).

Responses

Request samples

Content type
application/json
{
  • "brand": "Acme Apparel",
  • "vertical_id": 1500,
  • "sub_vertical_id": 1610,
  • "country_code": "US",
  • "platform_parent_account_id": "<your-platform-parent-account-id>",
  • "store_identifier": "https://acme-apparel.example.com",
  • "external_account_id": "partner-merchant-abc123",
  • "user_identifier": "owner@acme-apparel.com"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "error": null,
  • "message": "ok",
  • "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
  • "data": {
    }
}

List managed accounts

Returns the set of merchant accounts managed by a given partner parent account. Pass your partner platform's Rokt parent account ID in the parent_account_id query parameter.

Cursor-paginated. The response carries a top-level next_cursor string when more pages exist; pass it back as the cursor query parameter on the next call. When next_cursor is null the iteration is complete.

Single-account detail endpoint is not yet available. Use the per-resource reads (GET /marketplacecontrolslists, GET /status) to inspect an individual managed account. A consolidated GET /accounts/{id} is planned but not yet exposed on the partner surface.

Authorizations:
ApiToken
query Parameters
parent_account_id
required
string

Your partner platform's Rokt parent account ID. Server returns 400 if omitted.

cursor
string

Opaque cursor returned in next_cursor from a prior call. Omit on the first page.

limit
integer [ 1 .. 200 ]
Default: 50

Maximum items per page. Server-side cap is 200.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "next_cursor": "string"
}

Add pages to an existing managed account

Create one or more additional page+layout combinations on a merchant that's already been registered. Rokt reuses the same per-surface provisioning steps the registration flow uses, but does NOT re-create marketplace controls or targeting rule sets; those already exist at account level.

Use this when a partner adds a new surface to a merchant's integration post-launch (e.g. a tracking page added after the confirmation page was already configured at registration).

V1 limitations

  • New pages are created without a linked targeting rule set. If you need ruleset linkage today, include the surface on the original registration call.
  • Surface uniqueness is enforced by the underlying handler: calling twice for the same surface returns 422, not a clean 409. Use GET /accounts and the registration response's pages[].page_identifier to track which surfaces already exist.
Authorizations:
ApiToken
path Parameters
account_id
required
string^[0-9]+$

The Rokt-issued managed merchant account ID. Returned as a string everywhere. IDs can exceed 2^53, which overflows JavaScript Number; bind to string, not int64.

header Parameters
X-Platform-Parent-Account-Id
required
string
Example: <your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Required on every write call. Missing returns 422; mismatch with the managed account's actual parent returns 403.

Idempotency-Key
required
string <uuid>

Stable client-generated token that collapses retries to a single server-side operation. Required on all write calls; sending the same key twice within a 24-hour dedup window returns the cached response. After 24h the key expires and re-sending it triggers a fresh execution. See Idempotency Keys.

Request Body schema: application/json
required
platform_integration
required
string

The identifier for your integration (for example, your-integration-name). This value is the same for every merchant registered under your integration, and is set when your partnership is configured with Rokt.

required
Array of objects (RegisterPartnershipPage) non-empty

Responses

Request samples

Content type
application/json
{
  • "platform_integration": "<your-preset-key>",
  • "pages": [
    ]
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "error": null,
  • "message": "ok",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "dry_run": true,
  • "data": {
    }
}

Switch a page's layout type

Switch an existing page between layout types (e.g. Overlay ↔ Embedded) without re-registering the merchant or recreating the page. The page's page_identifier and URL targeting are unchanged by the switch; your SDK code keeps passing the same identifier into selectPlacements.

The layout types a page can switch to are the same set your integration's preset accepts at registration and on POST /v1/partnership/accounts/{account_id}/pages.

Two distinct error codes for layout_type problems:

  • 422: Returned when layout_type is not a recognised enum value (e.g. a typo or unknown string). Caught by the F&A input validation layer before reaching transactions.
  • 400: Returned when layout_type is a valid value but is not supported for this page's surface on your integration (e.g. requesting S2S on a confirmation page when your integration only supports Overlay and Embedded). The error message names the allowed values.

Theme edits applied via PATCH /v1/partnership/accounts/{account_id}/layouts/{layout_id} are preserved across switches; switching back to a layout type the page used before restores that layout, including its theme edits.

Requesting the layout_type the page already has returns 200 as a no-op, safe to call from reconciliation loops.

The response carries the layout_id now active on the page. Use that value for subsequent theme edits; a layout_id captured before the switch refers to the inactive layout.

Authorizations:
ApiToken
path Parameters
account_id
required
string^[0-9]+$

The Rokt-issued managed merchant account ID. Returned as a string everywhere. IDs can exceed 2^53, which overflows JavaScript Number; bind to string, not int64.

page_id
required
string <uuid>

Rokt-issued page identifier (from pages[].page_id on the registration or add-pages response).

header Parameters
X-Platform-Parent-Account-Id
required
string
Example: <your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Required on every write call. Missing returns 422; mismatch with the managed account's actual parent returns 403.

Idempotency-Key
required
string <uuid>

Stable client-generated token that collapses retries to a single server-side operation. Required on all write calls; sending the same key twice within a 24-hour dedup window returns the cached response. After 24h the key expires and re-sending it triggers a fresh execution. See Idempotency Keys.

Request Body schema: application/json
required
platform_integration
required
string

The identifier for your integration (for example, your-integration-name). This value is the same for every merchant registered under your integration, and is set when your partnership is configured with Rokt.

layout_type
required
string
Enum: "Overlay" "Embedded"

The layout style to switch the page to.

  • Overlay: modal that appears over the merchant's page.
  • Embedded: renders inline within an anchor element on the merchant's page (default selector #rokt-container). The values a page can switch to are the same set your preset accepts at registration; some integrations support only a subset. Requesting the type the page already has returns 200 as a no-op.

Responses

Request samples

Content type
application/json
{
  • "platform_integration": "<your-preset-key>",
  • "layout_type": "Embedded"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "error": null,
  • "message": "ok",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "dry_run": true,
  • "data": {
    }
}

Taxonomy

Read the partner-vertical to Rokt-vertical mappings seeded for your parent account.

Seeding itself is not self-serve: Rokt creates the rows during onboarding from the category list you supply. Until they exist, register and marketplace-control writes reject with 400.

List seeded vertical mappings

Returns the partner-vertical to Rokt-vertical mappings seeded for your parent account, in your own taxonomy.

Any {partner_vertical_id, partner_sub_vertical_id} pair in the response is safe to send on POST /v1/accounts/register/partnership and PUT /marketplacecontrolslists. Both resolve partner category IDs through this mapping and reject with 400 when a pair is missing.

Rows are ordered by partner_vertical_id, then partner_sub_vertical_id. vertical_name is the only Rokt-side field returned; Rokt's internal numeric vertical IDs stay server-side.

An empty vertical_mappings array means nothing is seeded yet, so every register call will fail. Email smb-partnerships@rokt.com your complete category list and wait for confirmation.

Read-only. Rokt creates mapping rows. There is no partner-callable write on this path.

Authorizations:
ApiToken
query Parameters
parent_account_id
required
string^[0-9]+$
Example: parent_account_id=<your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Server returns 400 if omitted.

parent_account
string^[0-9]+$

Legacy alias for parent_account_id, accepted for backward compatibility. Prefer parent_account_id on new integrations.

header Parameters
X-Platform-Parent-Account-Id
string
Example: <your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Optional on reads; when present, server enforces that you actually manage the target account. Recommended on every call for clarity even when not strictly required.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "error": null,
  • "message": "ok",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "dry_run": true,
  • "data": {
    }
}

Controls

Marketplace and offer control configuration.

Get marketplace controls

Returns the merchant's current marketplace control configuration: blocked verticals (in partner taxonomy) and domain controls.

Authorizations:
ApiToken
path Parameters
account_id
required
string^[0-9]+$

The Rokt-issued managed merchant account ID. Returned as a string everywhere. IDs can exceed 2^53, which overflows JavaScript Number; bind to string, not int64.

header Parameters
X-Platform-Parent-Account-Id
string
Example: <your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Optional on reads; when present, server enforces that you actually manage the target account. Recommended on every call for clarity even when not strictly required.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "error": null,
  • "message": "ok",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "dry_run": true,
  • "data": {
    }
}

Update marketplace controls

Replaces the marketplace controls (blocked verticals + domain rules) on a managed account.

PUT is desired-state, not a patch. Send the full list every time. Anything you omit becomes unblocked. There is no merge, no PATCH, no diff. See SET Semantics for the full mental model.

Partner vertical IDs are translated to Rokt's internal taxonomy server-side via your vertical mapping. Sending a partner vertical with no mapping returns a 400 and rejects the whole request atomically (no partial writes).

Optimistic concurrency (preview)

Optionally include contentHash from a prior GET. The field is accepted by the partner-facing layer. End-to-end stale-hash rejection is not yet verified on this preview surface; treat the 409 path as best-effort until GA.

Rate limit: 60 requests/minute per partner. See Rate Limits.

Authorizations:
ApiToken
path Parameters
account_id
required
string^[0-9]+$

The Rokt-issued managed merchant account ID. Returned as a string everywhere. IDs can exceed 2^53, which overflows JavaScript Number; bind to string, not int64.

query Parameters
dry_run
boolean
Default: false

When true, the server runs the full request (validation, translation, database writes inside a transaction) and then rolls everything back. The response payload is the same shape as a real write, but the envelope adds dry_run: true alongside data. See Dry-Run Mode.

header Parameters
X-Platform-Parent-Account-Id
required
string
Example: <your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Required on every write call. Missing returns 422; mismatch with the managed account's actual parent returns 403.

Idempotency-Key
required
string <uuid>

Stable client-generated token that collapses retries to a single server-side operation. Required on all write calls; sending the same key twice within a 24-hour dedup window returns the cached response. After 24h the key expires and re-sending it triggers a fresh execution. See Idempotency Keys.

Request Body schema: application/json
required
name
required
string

Display name for this controls list.

required
Array of objects (PartnerMclVertical)
Array of objects (PartnershipDomainControl)
Default: []
contentHash
string or null

Optional optimistic-concurrency token from your last GET.

Responses

Request samples

Content type
application/json
{
  • "name": "Acme Network Controls",
  • "blockedVerticals": [
    ],
  • "domains": [
    ],
  • "contentHash": null
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "error": null,
  • "message": "ok",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "dry_run": true,
  • "data": {
    }
}

Layouts

Per-merchant layout theme edits.

Apply theme edits to a partnership layout

Apply a partner's theme edits to one of the merchant's partnership- created templated layouts. Every field on the body is optional; only the keys you send get applied, and any settings you do not touch are preserved.

The server runs the same patch-bump predicate the Rokt One Platform UI uses on save (same major+minor, status=Published, highest patch) so merchant layouts pick up upstream template patch fixes automatically. Minor and major template version bumps never auto-apply.

Returns 404 if the layout does not exist on the account or has been archived. Returns 422 if the layout was not created through the partnership onboarding flow; every layout_id returned by POST /accounts/register/partnership and POST /v1/partnership/accounts/{account_id}/pages is editable here, so partners using the standard flow should not see this.

Authorizations:
ApiToken
path Parameters
account_id
required
string^[0-9]+$

The Rokt-issued managed merchant account ID. Returned as a string everywhere. IDs can exceed 2^53, which overflows JavaScript Number; bind to string, not int64.

layout_id
required
string <uuid>

Rokt-issued layout identifier (from pages[].layout_id on the registration response).

header Parameters
X-Platform-Parent-Account-Id
required
string
Example: <your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Required on every write call. Missing returns 422; mismatch with the managed account's actual parent returns 403.

Idempotency-Key
required
string <uuid>

Stable client-generated token that collapses retries to a single server-side operation. Required on all write calls; sending the same key twice within a 24-hour dedup window returns the cached response. After 24h the key expires and re-sending it triggers a fresh execution. See Idempotency Keys.

Request Body schema: application/json
required
primaryColor
string^#(?:[0-9a-fA-F]{3}){1,2}$

Hex color (#RGB or

backgroundColor
string^#(?:[0-9a-fA-F]{3}){1,2}$

Hex color applied to the outer/main and body container backgrounds.

textColor
string^#(?:[0-9a-fA-F]{3}){1,2}$

Hex color applied to all major text components (header, paragraphs, footer).

borderRadius
integer [ 0 .. 24 ]

Border radius in pixels applied to outer/main containers and (Overlay only) the close button.

closeButtonColor
string^#(?:[0-9a-fA-F]{3}){1,2}$

Hex color applied to the close button (text + border). Overlay only; ignored for Embedded layouts.

Responses

Request samples

Content type
application/json
{
  • "primaryColor": "#FF6B35",
  • "backgroundColor": "#FFFFFF",
  • "textColor": "#1A1A1A",
  • "borderRadius": 8,
  • "closeButtonColor": "#666666"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "error": null,
  • "message": "ok",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "dry_run": true,
  • "data": {
    }
}

Status

Pause and resume partnership placements.

Get partnership status

Returns the aggregate active/paused status across all non-archived page variants on the account.

Aggregation rule

  • "active": every non-archived variant is enabled
  • "paused": every non-archived variant is disabled (or none exist)
  • "mixed": some enabled, some disabled

The per-variant breakdown is returned in variants so partners can compute per-page state client-side if needed.

Authorizations:
ApiToken
path Parameters
account_id
required
string^[0-9]+$

The Rokt-issued managed merchant account ID. Returned as a string everywhere. IDs can exceed 2^53, which overflows JavaScript Number; bind to string, not int64.

header Parameters
X-Platform-Parent-Account-Id
string
Example: <your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Optional on reads; when present, server enforces that you actually manage the target account. Recommended on every call for clarity even when not strictly required.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "error": null,
  • "message": "ok",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "dry_run": true,
  • "data": {
    }
}

Pause or resume partnership

Cascades active/paused status across all non-archived page variants on the account. Archived variants are unaffected.

Round-trip identity: after PUT status=paused you should always see GET status → "paused". If you see "mixed" instead, the PUT failed to update some variants; surface a support ticket.

Rate limit: 60 requests/minute per partner. See Rate Limits.

Authorizations:
ApiToken
path Parameters
account_id
required
string^[0-9]+$

The Rokt-issued managed merchant account ID. Returned as a string everywhere. IDs can exceed 2^53, which overflows JavaScript Number; bind to string, not int64.

query Parameters
dry_run
boolean
Default: false

When true, the server runs the full request (validation, translation, database writes inside a transaction) and then rolls everything back. The response payload is the same shape as a real write, but the envelope adds dry_run: true alongside data. See Dry-Run Mode.

header Parameters
X-Platform-Parent-Account-Id
required
string
Example: <your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Required on every write call. Missing returns 422; mismatch with the managed account's actual parent returns 403.

Idempotency-Key
required
string <uuid>

Stable client-generated token that collapses retries to a single server-side operation. Required on all write calls; sending the same key twice within a 24-hour dedup window returns the cached response. After 24h the key expires and re-sending it triggers a fresh execution. See Idempotency Keys.

Request Body schema: application/json
required
status
required
string
Enum: "active" "paused"

Responses

Request samples

Content type
application/json
Example
{
  • "status": "paused"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "error": null,
  • "message": "ok",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "dry_run": true,
  • "data": {
    }
}

Payout Setup

Stripe Connect payout onboarding for managed accounts.

V1 payout model: Rokt pays the partner-side payout (your platform's revenue share, per your partnership agreement) to your manager account, not to individual managed accounts. Distributing each merchant's portion among your managed accounts is your platform's responsibility.

Start Stripe Connect payout setup

Initiates Stripe Connect onboarding for the managed merchant.

V1 payout model: Rokt pays the partner-side payout (your platform's revenue share, per your partnership agreement) to your manager account, not to individual managed accounts. Distributing each merchant's portion among your managed accounts is your platform's responsibility.

Choose one of two onboarding shapes:

  • experience: "embedded": render the Stripe-hosted onboarding flow inside your own app. Do not send a contact block; server rejects with 400 if you do ("contact is only valid for hosted_invite payout setup").
  • experience: "hosted_invite": Rokt emails the merchant an onboarding link. contact.email is required; the server rejects with 400 if absent.

Do not pass any bank account, card, routing, SSN, IBAN, tax, PayPal, or external-account fields in the request; these are explicitly forbidden in any nested key and return 400. Stripe collects financial data directly from the merchant.

Rate limit: 10 requests/minute per partner. See Rate Limits.

Authorizations:
ApiToken
path Parameters
account_id
required
string^[0-9]+$

The Rokt-issued managed merchant account ID. Returned as a string everywhere. IDs can exceed 2^53, which overflows JavaScript Number; bind to string, not int64.

header Parameters
X-Platform-Parent-Account-Id
required
string
Example: <your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Required on every write call. Missing returns 422; mismatch with the managed account's actual parent returns 403.

Idempotency-Key
required
string <uuid>

Stable client-generated token that collapses retries to a single server-side operation. Required on all write calls; sending the same key twice within a 24-hour dedup window returns the cached response. After 24h the key expires and re-sending it triggers a fresh execution. See Idempotency Keys.

Request Body schema: application/json
required
provider
required
string
Value: "stripe_connect"
experience
required
string
Enum: "embedded" "hosted_invite"

Mutually-exclusive with contact:

  • embedded: do not send contact (server returns 400).
  • hosted_invite: contact.email is required.
object

Required for hosted_invite; forbidden for embedded.

Responses

Request samples

Content type
application/json
Example
{
  • "provider": "stripe_connect",
  • "experience": "embedded"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "error": null,
  • "message": "ok",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "dry_run": true,
  • "data": {
    }
}

Get payout setup status

Polls the current state of Stripe Connect onboarding for the managed merchant.

Authorizations:
ApiToken
path Parameters
account_id
required
string^[0-9]+$

The Rokt-issued managed merchant account ID. Returned as a string everywhere. IDs can exceed 2^53, which overflows JavaScript Number; bind to string, not int64.

query Parameters
provider
string
Default: "stripe_connect"
Value: "stripe_connect"
header Parameters
X-Platform-Parent-Account-Id
string
Example: <your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Optional on reads; when present, server enforces that you actually manage the target account. Recommended on every call for clarity even when not strictly required.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "error": null,
  • "message": "ok",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "dry_run": true,
  • "data": {
    }
}

Privacy

Network privacy and managed-account data deletion requests.

Submit a network privacy request

Submit a consumer network privacy request on behalf of an end user of the Rokt network.

This endpoint is for network-wide consumer identifiers, not for a managed merchant account. Use POST /v1/partnership/accounts/{account_id}/data-deletion-requests for account-level deletion.

Supported request types:

  • NETWORK_OPT_OUT accepts exactly one of email or phone and submits an OPT_OUT action to Rokt's privacy/consent service.
  • NETWORK_DATA_DELETION accepts exactly one of email or sha256Email and submits the same network suppression action Rokt uses for deleted network user data.

The Accounts API does not persist raw consumer identifiers or downstream response bodies.

This route returns a direct privacy response, not the standard partnership envelope. It does not create a partnership operation and does not require Idempotency-Key.

Rate limit: 10 requests/minute per partner. See Rate Limits.

Authorizations:
ApiToken
query Parameters
parent_account_id
required
string^[0-9]+$
Example: parent_account_id=<your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Required for network privacy requests because they do not target a managed account path.

Request Body schema: application/json
required
requestType
required
string (NetworkPrivacyRequestType)
Enum: "NETWORK_OPT_OUT" "NETWORK_DATA_DELETION"

NETWORK_OPT_OUT submits a Rokt Ads network opt-out. NETWORK_DATA_DELETION submits the same network suppression action Rokt uses for deleted network user data.

email
string or null <email>

Consumer email address. Supported for opt-out and network data deletion.

phone
string or null

Consumer phone number. Supported only for NETWORK_OPT_OUT.

sha256Email
string or null

Base64-encoded SHA256 email digest. Supported only for NETWORK_DATA_DELETION.

Responses

Request samples

Content type
application/json
Example
{
  • "requestType": "NETWORK_OPT_OUT",
  • "email": "consumer@example.com"
}

Response samples

Content type
application/json
{
  • "request_id": "dad24980-de21-43e5-839b-cf66f840d9d1",
  • "request_type": "NETWORK_OPT_OUT",
  • "identifier_type": "email",
  • "status": "submitted",
  • "downstream_request_id": "consent-123",
  • "message": "Network opt-out request submitted to Rokt's privacy/consent service."
}

Submit account-level data deletion

Submit a data deletion request for a managed merchant account owned by your partner parent account.

This endpoint is separate from POST /v1/partnership/network-privacy-requests, which acts on an end user's network-level privacy request by consumer identifier.

Rokt validates your API token against RegisterPartnership on X-Platform-Parent-Account-Id, verifies that the parent owns the supplied managed account_id, and forwards the request to the internal Data Deletion account API. The Accounts API does not persist downstream response bodies.

The request body is empty. The target account is the account_id in the path.

dry_run=true validates the request and skips downstream submission. Dry-run responses do not carry X-Operation-Id because no operation is persisted.

Rate limit: 10 requests/minute per partner. See Rate Limits.

Authorizations:
ApiToken
path Parameters
account_id
required
string^[0-9]+$

The Rokt-issued managed merchant account ID. Returned as a string everywhere. IDs can exceed 2^53, which overflows JavaScript Number; bind to string, not int64.

query Parameters
dry_run
boolean
Default: false

When true, the server runs the full request (validation, translation, database writes inside a transaction) and then rolls everything back. The response payload is the same shape as a real write, but the envelope adds dry_run: true alongside data. See Dry-Run Mode.

header Parameters
X-Platform-Parent-Account-Id
required
string
Example: <your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Required on every write call. Missing returns 422; mismatch with the managed account's actual parent returns 403.

Idempotency-Key
required
string <uuid>

Stable client-generated token that collapses retries to a single server-side operation. Required on all write calls; sending the same key twice within a 24-hour dedup window returns the cached response. After 24h the key expires and re-sending it triggers a fresh execution. See Idempotency Keys.

Responses

Response samples

Content type
application/json
Example
{
  • "status": 202,
  • "error": null,
  • "message": "accepted",
  • "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
  • "data": {
    }
}

Operations

Poll the status of asynchronous-style operations.

Poll an operation by ID

Returns the persistent record of a partnership operation by its operation_id. Every write call returns X-Operation-Id in its response headers; capture that value if you want to recover from an HTTP timeout without re-issuing the write.

The caller's parent account must match the operation's owner; cross-tenant reads return 403. The X-Platform-Parent-Account-Id header is required on every poll; missing or mismatched returns 403 (not 422 as on write endpoints).

Rate limit: 600 requests/minute per partner (polling-friendly). See Rate Limits.

Authorizations:
ApiToken
path Parameters
operation_id
required
string <uuid>
header Parameters
X-Platform-Parent-Account-Id
required
string
Example: <your-platform-parent-account-id>

Your partner platform's Rokt parent account ID. Required on every write call. Missing returns 422; mismatch with the managed account's actual parent returns 403.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "error": null,
  • "message": "ok",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "dry_run": true,
  • "data": {
    }
}