Mappings API - Ours Privacy

Manage destination and source mappings. List mappings for a destination or source, create mappings from templates, edit field mappings and condition logic, reorder priority, and configure the destination default mapping.

Use this page to list, create, edit, and reorder the mappings on a destination or source.

A mapping binds inbound events to a destination, with optional field-level transforms and a condition tree that gates when the mapping fires. Each parent entity (destination or source) has its mappings sorted by priority; the first matching mapping in priority order is what runs.

Where this fits in the dispatch flow

Mappings run after the allow-list and governance stages:

SourceAllowed EventsData GovernanceMappingsDestination

Configuration changes at any stage take effect once you publish a new version.

An event must pass Allowed Events (matched + the destination listed) and Data Governance (no category gating it) before any mapping fires. A mapping describes how the event is shaped for one destination. By then, the whether has already been decided upstream.

Two ways to create a mapping

POST /rest/v1/mappings accepts two body shapes. Pick one:

Quick-create: { allowedEventId, destinationId }. Binds an existing allowed event to a destination. Returns the mapping with an empty mappings[]; follow up with PATCH to populate field bindings.
From a template: { entityId, templateId, mappings?, logic?, isEnabled?, name?, insertAfterIdx? }. Creates a complete mapping in one request. Discover the valid templateId and mappings[].property values with GET /rest/v1/mappings/templates?entityId={destinationOrSourceId}.

Discovery endpoints

These endpoints describe what a mapping can send:

GET /rest/v1/mappings/templates?entityId={id}: every mapping template available for a destination or source, with full property descriptors (property, kind, required, valid options, suggested modificationOptions). The isDefault: true entry is the destination's built-in default template.
GET /rest/v1/mappings/default-variables: platform-provided dot-paths you can reference in a mapping map value (e.g. visitor.email, event.request_context.ip).
GET /rest/v1/mappings/custom-variables: account-specific variables sampled from the last 14 days of events. An empty list means no custom event properties have been seen yet.
GET /rest/v1/mappings/modifications: the labelled list of values accepted on mappings[].modification (hashing, casing, URL truncation).

Default mappings

A destination's default mapping is the catch-all that runs when no other mapping on the destination matches. Each destination has at most one. Default mappings cannot carry custom logic, and their mappings[] is always replaced wholesale on write.

GET /rest/v1/default-mappings: every stored default mapping for the account.
GET /rest/v1/default-mappings/{destinationId}: the default mapping for one destination. Returns an empty mappings[] when no default has been written yet.
PUT /rest/v1/default-mappings/{destinationId}: create or replace the default mapping for a destination.

Renaming an event for one destination

Some destinations let you send an allowed event under a different name without changing the event everywhere else. Check entities[].capabilities.supportsRenamedEvents in GET /rest/v1/destinations/types for the destination's type. A rename applies once the allowed event is enabled for that destination. Preview works either way, so you can check which events a rename affects before enabling the event.

Preview with GET /rest/v1/mappings/rename-preview?destinationId={destinationId}&allowedEventId={allowedEventId}. The response reports willCascade, the mapperName of any existing mapper, and every affectedEventNames entry.
Set the name with PUT /rest/v1/mappings/rename:

{
  "destinationId": "00000000-0000-0000-0000-000000000000",
  "allowedEventId": "11111111-1111-1111-1111-111111111111",
  "renamedEventName": "Purchase",
  "confirmCascade": false
}

When willCascade is true, the event shares a mapper with other allowed events and the rename applies to all of them. Review affectedEventNames, then send confirmCascade: true.

Send renamedEventName: null to clear the rename. Clearing deletes the rename mapper, including any other property mappings it carried. Publish a new version to activate either change.

Updating and reordering

PATCH /rest/v1/mappings/{id} is patch-only: only the fields you send are changed. mappings[] is replaced wholesale when sent. Flip isEnabled: false to pause a mapping without other edits.

POST /rest/v1/mappings/reorder reassigns priority for a set of mappings on a single parent entity. Send { uuids: [...] } with the mapping ids in their new order, where index 0 becomes the highest-priority mapping.

Edits don't take effect until you publish a new version. See Versions for the publish flow.

GET/rest/v1/mappings

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

limit?|

Maximum number of mappings to return. Defaults to 1000; values below 1 are clamped to 1 and values above 1000 are clamped to 1000. Most accounts can fetch the full list in one request.

cursor?string

Opaque pagination cursor from pagination.nextCursor in the previous response. Do not decode or modify it. Malformed cursors return 400 Bad Request.

entityId*string

Filter mappings by their parent entity id. Must be a destination id or source id.

Mappings

Where this fits in the dispatch flow

Two ways to create a mapping

Discovery endpoints

Default mappings

Renaming an event for one destination

Updating and reordering

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`