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.
  • Consent management — record the lawful basis behind the identifiers you tokenize.
  • DSAR — erase a contact’s data end to end, including the envelopes you stored.
  • API reference — full request/response schemas for the vault endpoints.