Upsert an actor mapping
Use this endpoint to create or update an actor mapping. Actor mappings associate system actor identifiers with human-readable display names and email addresses for audit log readability.
Authorizations
Bearer token authentication (format: "Bearer {token}")
Headers
A unique identifier for tracing the request across services.
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
The actor identifier to map. Actor ID
Body
Actor mapping payload
Human-readable display name for the actor; optional, but at least one of displayName or email must be provided
"John Doe"
Email address of the actor; optional, but at least one of displayName or email must be provided
"john.doe@example.com"
Response
Actor mapping created or updated.
Opaque actor identifier the PII mapping is keyed on
"user:550e8400-e29b-41d4-a716-446655440000"
Timestamp when the mapping was created, in RFC 3339 format (UTC)
"2026-01-15T10:30:00Z"
Timestamp when the mapping was last updated, in RFC 3339 format (UTC)
"2026-01-15T10:30:00Z"
Human-readable display name for the actor; absent when not set or after pseudonymization
"John Doe"
Email address of the actor; absent when not set or after pseudonymization
"john.doe@example.com"

