Skip to main content
PUT
Upsert an actor mapping

Authorizations

Authorization
string
header
required

Bearer token authentication (format: "Bearer {token}")

Headers

X-Request-Id
string

A unique identifier for tracing the request across services.

X-Idempotency
string

Optional idempotency key for safe retries. Matcher reads the key only from this header, and only when you send one. A request that carries a key only in X-Idempotency-Key or Idempotency-Key is refused with 400 (MTCH-0015), and nothing is processed. If the same key is sent again and the original request was already processed, the stored response is returned with X-Idempotency-Replayed: true. A malformed key returns 400, a key whose first request is still in progress returns 409, and an idempotency storage failure returns 500. These refusals are problem documents.

Path Parameters

actorId
string
required

The actor identifier to map. Actor ID

Body

application/json

Actor mapping payload

displayName
string | null

Human-readable display name for the actor; optional, but at least one of displayName or email must be provided

Example:

"John Doe"

email
string<email> | null

Email address of the actor; optional, but at least one of displayName or email must be provided

Example:

"john.doe@example.com"

Response

Actor mapping created or updated.

actorId
string
required

Opaque actor identifier the PII mapping is keyed on

Example:

"user:550e8400-e29b-41d4-a716-446655440000"

createdAt
string
required

Timestamp when the mapping was created, in RFC 3339 format (UTC)

Example:

"2026-01-15T10:30:00Z"

updatedAt
string
required

Timestamp when the mapping was last updated, in RFC 3339 format (UTC)

Example:

"2026-01-15T10:30:00Z"

displayName
string

Human-readable display name for the actor; absent when not set or after pseudonymization

Example:

"John Doe"

email
string

Email address of the actor; absent when not set or after pseudonymization

Example:

"john.doe@example.com"