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 a slim mapping with empty mappings[]; follow up with PATCH to populate field bindings.
Template fat-create — { entityId, templateId, mappings?, logic?, isEnabled?, name?, insertAfterIdx? }. Lands a fully-shaped mapping in one request. Discover the valid templateId and mappings[].property values with GET /rest/v1/mappings/templates?entityId={destinationOrSourceId}.

Sending both allowedEventId and templateId returns 400 — pick one variant.

Discovery endpoints

Before authoring a mapping, use these read-only endpoints to learn what to 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. 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} — hydrated row for one destination. Returns an empty mappings[] when no default has been written yet, so callers do not need to branch on 404 vs 200.
PUT /rest/v1/default-mappings/{destinationId} — upsert the default mapping for a destination.

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 — index 0 becomes the highest-priority mapping. All ids must belong to the same parent; mixing destinations and sources returns 400.

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

Authorization

apiKey

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.

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/mappings?entityId=00000000-0000-0000-0000-000000000000"

{
  "entities": [
    {
      "id": "string",
      "name": "string",
      "updatedAt": "string",
      "isEnabled": true,
      "templateName": "string",
      "templateId": "string",
      "destinationId": "string",
      "sourceId": "string",
      "isDefaultMapping": true,
      "priority": 0,
      "mappings": [
        {
          "property": "string",
          "map": "string",
          "modification": "CamelCase"
        }
      ],
      "logic": {}
    }
  ],
  "pagination": {
    "nextCursor": "string",
    "hasMore": true
  }
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Two body shapes are accepted, distinguished by which keys are sent. Quick-create — { allowedEventId, destinationId }. Template fat-create — { entityId, templateId, mappings?, logic?, isEnabled?, name?, insertAfterIdx? }. Sending neither, both, or an incomplete pair returns 400 with a message telling you which variant to complete.

allowedEventId?string

Quick-create variant: allowed event to bind the new mapping to. Required together with destinationId. Mutually exclusive with templateId/entityId.

destinationId?string

Quick-create variant: destination that should receive events matched by this mapping. Required together with allowedEventId.

entityId?string

Template fat-create variant: destination or source id this mapping belongs to. Required together with templateId.

templateId?string

Template fat-create variant: template id from GET /rest/v1/mapping-templates. Picks the property descriptor set used to validate mappings[].property. Required together with entityId.

insertAfterIdx?integer

Template fat-create only. Zero-based position in the destination/source priority order to insert this mapping after. Omit to append at the end.

name?|

Template fat-create only. Override the auto-generated mapping name.

isEnabled?boolean

Template fat-create only. Initial enabled state. Defaults to true.

logic?

Condition tree gating when this mapping fires. A node is either a leaf condition or a combinator (AND, OR, NOT). Combinator children are themselves logic nodes, so trees nest arbitrarily.

Example leaf: { "condition": { "property": "$event.event", "operator": "Is", "value": "page_view" } }.

Example combinator: { "AND": [{ "condition": ... }, { "OR": [...] }] }.

mappings?array<>

Template fat-create only. Optional initial property mappings. When omitted the mapping is seeded with template defaults for sources and non-default destination templates, and with [] for default destination templates.

Response Body

`application/json`

curl -X POST "https://example.com/rest/v1/mappings" \  -H "Content-Type: application/json" \  -d '{}'

{
  "id": "string",
  "name": "string",
  "updatedAt": "string",
  "isEnabled": true,
  "templateName": "string",
  "templateId": "string",
  "destinationId": "string",
  "sourceId": "string",
  "isDefaultMapping": true,
  "priority": 0,
  "mappings": [
    {
      "property": "string",
      "map": "string",
      "modification": "CamelCase"
    }
  ],
  "logic": {}
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/mappings/string"

{
  "id": "string",
  "name": "string",
  "updatedAt": "string",
  "isEnabled": true,
  "templateName": "string",
  "templateId": "string",
  "destinationId": "string",
  "sourceId": "string",
  "isDefaultMapping": true,
  "priority": 0,
  "mappings": [
    {
      "property": "string",
      "map": "string",
      "modification": "CamelCase"
    }
  ],
  "logic": {}
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string|null

isEnabled?|

Flip the mapping on/off without changing other fields. null is treated as omitted.

mappings?array<>

logic?

Condition tree gating when this mapping fires. A node is either a leaf condition or a combinator (AND, OR, NOT). Combinator children are themselves logic nodes, so trees nest arbitrarily.

Example leaf: { "condition": { "property": "$event.event", "operator": "Is", "value": "page_view" } }.

Example combinator: { "AND": [{ "condition": ... }, { "OR": [...] }] }.

Response Body

`application/json`

curl -X PATCH "https://example.com/rest/v1/mappings/string" \  -H "Content-Type: application/json" \  -d '{}'

{
  "id": "string",
  "name": "string",
  "updatedAt": "string",
  "isEnabled": true,
  "templateName": "string",
  "templateId": "string",
  "destinationId": "string",
  "sourceId": "string",
  "isDefaultMapping": true,
  "priority": 0,
  "mappings": [
    {
      "property": "string",
      "map": "string",
      "modification": "CamelCase"
    }
  ],
  "logic": {}
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X DELETE "https://example.com/rest/v1/mappings/string"

true

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Reassign priority for the supplied mappings. The position in uuids becomes the new priority order: index 0 is highest priority.

uuids*array<string>

Mapping ids in their new priority order, low priority index first. All ids must belong to the same parent entity (source or destination).

Response Body

`application/json`

curl -X POST "https://example.com/rest/v1/mappings/reorder" \  -H "Content-Type: application/json" \  -d '{    "uuids": [      "string"    ]  }'

{
  "entities": [
    {
      "id": "string",
      "name": "string",
      "updatedAt": "string",
      "isEnabled": true,
      "templateName": "string",
      "templateId": "string",
      "destinationId": "string",
      "sourceId": "string",
      "isDefaultMapping": true,
      "priority": 0,
      "mappings": [
        {
          "property": "string",
          "map": "string",
          "modification": "CamelCase"
        }
      ],
      "logic": {}
    }
  ]
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

entityId*string

Destination or source id. Required.

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/mappings/templates?entityId=00000000-0000-0000-0000-000000000000"

{
  "entities": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "isDefault": true,
      "mappings": [
        {
          "property": "string",
          "label": "string",
          "description": "string",
          "kind": "Array",
          "isPII": true,
          "required": true,
          "map": "string",
          "modification": "CamelCase",
          "modificationOptions": [
            "CamelCase"
          ],
          "options": [
            {
              "label": "string",
              "value": "string"
            }
          ],
          "suggestedOptions": [
            {
              "label": "string",
              "value": "string"
            }
          ]
        }
      ]
    }
  ]
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/mappings/default-variables"

{
  "entities": [
    {
      "path": "string",
      "name": "string",
      "examples": [
        "string"
      ],
      "popularity": 0,
      "advancedInfo": "string"
    }
  ]
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/mappings/custom-variables"

{
  "entities": [
    {
      "path": "string",
      "name": "string",
      "examples": [
        "string"
      ],
      "popularity": 0,
      "advancedInfo": "string"
    }
  ]
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/mappings/modifications"

{
  "entities": [
    {
      "value": "CamelCase",
      "label": "string",
      "description": "string"
    }
  ]
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/default-mappings"

{
  "entities": [
    {
      "id": "string",
      "name": "string",
      "updatedAt": "string",
      "isEnabled": true,
      "templateName": "string",
      "templateId": "string",
      "destinationId": "string",
      "sourceId": "string",
      "isDefaultMapping": true,
      "priority": 0,
      "mappings": [
        {
          "property": "string",
          "map": "string",
          "modification": "CamelCase"
        }
      ],
      "logic": {}
    }
  ]
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/default-mappings/string"

{
  "id": "string",
  "name": "string",
  "updatedAt": "string",
  "isEnabled": true,
  "templateName": "string",
  "templateId": "string",
  "destinationId": "string",
  "sourceId": "string",
  "isDefaultMapping": true,
  "priority": 0,
  "mappings": [
    {
      "property": "string",
      "map": "string",
      "modification": "CamelCase"
    }
  ],
  "logic": {}
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Upsert the default mapping for a destination. Default mappings cannot have custom logic (the resolver rejects it), so the field is intentionally omitted here.

mappings*array<>

Property mappings to persist as the destination default. Use GET /rest/v1/mapping-templates?entityId={destinationId} to discover the valid property values.

isEnabled?|

Toggle the default mapping on/off. Defaults to true when omitted. null is treated as omitted.

Response Body

`application/json`

curl -X PUT "https://example.com/rest/v1/default-mappings/string" \  -H "Content-Type: application/json" \  -d '{    "mappings": [      {        "property": "string",        "map": "string"      }    ]  }'

{
  "id": "string",
  "name": "string",
  "updatedAt": "string",
  "isEnabled": true,
  "templateName": "string",
  "templateId": "string",
  "destinationId": "string",
  "sourceId": "string",
  "isDefaultMapping": true,
  "priority": 0,
  "mappings": [
    {
      "property": "string",
      "map": "string",
      "modification": "CamelCase"
    }
  ],
  "logic": {}
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Mappings

Where this fits in the dispatch flow

Two ways to create a mapping

Discovery endpoints

Default mappings

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

400application/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`