Skip to main content

​
Contact PII Vault

The PII vault lets you segment, join, and activate on opaque tokens instead of raw identifiers. Every derived audience, activation payload, and export that holds a raw email or phone number spreads that cleartext further — the vault’s tokenize primitive keeps the cleartext behind the vault boundary while still letting records for one person collapse to a single stable key. Tokenization is vaultless: tokens are derived by a keyed HMAC over the normalized value, so there is no lookup table to store and nothing to migrate. The deterministic token alone is not reversible. When you need recovery, you ask for a sealed envelope at tokenize time, hold it yourself, and hand it to the detokenize endpoint later — recovery keys stay scoped to your account.
Tokens are scoped per account: the same value tokenizes to a different token under a different account, so a token never reveals whether an identifier exists anywhere else.

​
Identifier types

The vault accepts four identifier types. A value that cannot be normalized for its type is skipped (counted, never echoed), not tokenized into a meaningless digest:

​
Tokenize

POST /api/v1/cdp/pii-vault/tokenize turns a batch of identifiers into tokens:
  • records — 1 to 10,000 entries. Each entry carries a type and value, and an optional ref you choose (a row id, for example) so you can map tokens back to your own records — the response never contains the value itself.
  • reversible — default false, tokens only; the original value is then unrecoverable from what Orbit hands back (the strongest data-minimization posture). Set true to also receive a sealed envelope per token.
Each successful entry returns index, your ref, the type, the token (pii_<type>_…), and a sealed envelope when reversible was set. Skipped entries are returned with index, ref, type, and reason: "unnormalizable". Access: owner, admin, or developer with the contacts:read scope. Up to 20 calls per minute per account.

​
Detokenize

POST /api/v1/cdp/pii-vault/detokenize opens sealed envelopes back to their original values:
Only a sealed envelope (an enc:v1: value) is valid input — a deterministic token alone is not reversible. Anything that is not a valid envelope, or whose envelope fails verification, is reported as opened: false rather than echoed back. Revealing cleartext is deliberately a tighter role set than tokenizing: owner or admin with the contacts:read scope (developers excluded).

​
Privacy + audit model

  • Tokenize never returns the original value — only tokens (and optionally the sealed envelope you asked for).
  • Both endpoints record counts only in the audit log — never an identifier, token, or envelope. Detokenize audits the requested and opened counts; nothing else.
  • The token derivation is salted with your account id, and sealed envelopes open only under the platform key — recovery stays scoped to your account.

​
Policy registry — per-type enablement and modes

The vault endpoints above take the identifier type on every call. A second surface — the per-tenant policy registry at /api/v1/cdp/pii-tokenization — records how your account treats each identifier class, so the policy-driven tokenize endpoint and the dashboard resolve the mode you intended per type instead of repeating it on every request. The registry covers four identifier classes, each with a documented default mode. A class with no override resolves to disabled at its default mode, so a fresh account tokenizes nothing until you opt a class in — identifiers flow through untouched until you enable them: Reversible is right when a downstream system legitimately re-activates the identifier — email sending, dialing, fulfilment handoff. Hash is right when nothing should ever get the raw value back: you still get deterministic, join-safe tokens for segmentation, but detokenize returns an IRREVERSIBLE error for them. The choice is per class and is yours.

​
Read the effective policy

GET /api/v1/cdp/pii-tokenization returns the effective policy for every class, your override registry, the class catalog with its default mode, and a roll-up summary:
Each policy entry carries source — default or override — so you can tell what a class resolves to now versus what the platform would assume on a fresh account. Reads are available to owner, admin, or developer with the contacts:read scope, up to 60 calls per minute per account.

​
Set a class override

PUT /api/v1/cdp/pii-tokenization/:type upserts one class’s override. Send enabled, mode (reversible or hash), and an optional notes string for audit context:
The response returns the class’s effective policy after the write plus the stored override. Writes are merge-scoped to the tokenization subtree of your organization settings — no other setting is touched — and every write is audited. Policy writes require owner, admin, or developer with the contacts:write scope, up to 30 calls per minute per account.

​
Revert a class to the default

DELETE /api/v1/cdp/pii-tokenization/:type removes the override, reverting the class to its documented default mode, disabled:
Existing tokens are unaffected — the delete changes only resolution, nothing already minted. A class with no override returns 404 PII_TOKENIZATION_OVERRIDE_NOT_FOUND.

​
Policy-driven tokenize and detokenize

The registry’s companions are server-to-server batch endpoints, POST /api/v1/cdp/pii-tokenization/tokenize and .../detokenize. Unlike the vault endpoints, each item is { type, value, mode? } and the mode defaults to the class’s effective policy mode — so the same call does the class- appropriate thing once your registry is set (a per-item override is still allowed). Tokenize handles up to 100 items per call at 120 calls per minute per account, requires owner/admin/developer + contacts:read, and never echoes the cleartext back. Detokenize reverses only reversible tokens — owner/admin with contacts:read, 60 per minute — returns an IRREVERSIBLE error per hash-mode token, and enters the audit chain (counts and the classes revealed, never values). These tokens are vaultless and self-contained: the token carries its own ciphertext, and token subkeys are derived from the platform key and your organization id, so a token minted under one account can never be detokenized under — or collide with — another account’s tokens.

​
Normalize-then-tokenize

Canonicalization runs before the token is derived, so equivalent inputs collide to one token and stay joinable downstream: email is trimmed and lower-cased, phone is reduced to a leading + and digits, ssn to digits only, generic is trimmed only. One consequence to design for: detokenize returns the canonical form, not the original bytes — Alice@Example.com comes back as alice@example.com.

​
Which surface for which need

​
Configure it from the dashboard

Operators can run the whole registry without the API: Integrations → CDP → PII tokenization. The tab lists each identifier class with its status (Tokenizing / Off), effective mode, and the platform default. Configure (or Edit policy once an override exists) opens a dialog with the per-class toggle, the mode pick (Reversible (vault) / Irreversible hash), and an optional note; Reset to default removes the override and reverts the class to disabled. The tab governs policy only — tokenize and detokenize stay server-to-server, so no cleartext PII is ever entered or revealed in the browser.

​
Guards and audit posture

Policy reads run at 60 calls per minute per account; policy writes at 30; policy-driven tokenize at 120 and detokenize at 60. Reads and tokenize accept owner, admin, or developer with contacts:read; policy writes require contacts:write; detokenize narrows the role to owner or admin because it reveals cleartext. Mirroring the vault endpoints, the policy surface audits counts only — every policy write and every detokenize enters the audit log recording counts and the classes touched, never an identifier, token, or value.
  • Consent management — record the lawful basis behind the identifiers you tokenize.
  • Retention policy — the sibling per-tenant registry for how long data classes live.
  • DSAR — erase a contact’s data end to end, including the envelopes you stored.
  • API reference — full request/response schemas for the vault and policy-registry endpoints.