> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact PII Vault (Tokenize + Detokenize)

> Turn sensitive contact identifiers — email, phone, SSN, national ID — into deterministic, tenant-scoped opaque tokens you can segment and activate on, with an optional sealed envelope for authorized recovery.

# 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.

<Info>
  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.
</Info>

## 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:

| Type          | Normalization                                         |
| ------------- | ----------------------------------------------------- |
| `email`       | Trimmed + lower-cased (same contract as ad audiences) |
| `phone`       | Canonicalized to E.164 with a leading `+`             |
| `ssn`         | Exactly 9 digits after stripping separators           |
| `national_id` | Upper-cased, spaces/hyphens stripped, 4–64 `[A-Z0-9]` |

## Tokenize

`POST /api/v1/cdp/pii-vault/tokenize` turns a batch of identifiers into tokens:

```json theme={null}
{
  "records": [
    { "type": "email", "value": "alice@example.com", "ref": "row-1" },
    { "type": "phone", "value": "+1 (415) 555-2671" }
  ],
  "reversible": false
}
```

* `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:

```json theme={null}
{ "sealed": ["enc:v1:…"] }
```

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.

## Related

* [Consent management](/compliance/consent-management) — record the lawful
  basis behind the identifiers you tokenize.
* [DSAR](/compliance/dsar) — erase a contact's data end to end, including the
  envelopes you stored.
* [API reference](/api-reference/cdp) — full request/response schemas for the
  vault endpoints.