---
title: "Encode Text"
method: POST
path: "/api/scanner/encode"
tags: ["Encoding"]
---

# Encode Text

`POST /api/scanner/encode`

Detect PII in text and replace it with Privacy Twins. Returns the encoded text, a continuation ID for later decoding, and details of each transformation applied.

**Supported entity types:** `PERSON`, `EMAIL_ADDRESS`, `PHONE_NUMBER`, `US_SSN`, `DATE_TIME`, `LOCATION`, `CREDIT_CARD`, `IP_ADDRESS`, `IBAN_CODE`, `US_PASSPORT`, `US_DRIVER_LICENSE`, `NRP`, `MEDICAL_LICENSE`, `URL`

**Detection profiles:** detection policy is resolved server-side from the authenticated account.
Enterprise accounts use the `standard` profile. Accounts on the Family plane automatically use the
`family` profile, which additionally protects `SCHOOL` names and city-level geography. There is no
request parameter for the profile; client-supplied values are ignored by design.

**SDK Usage:**
```typescript
const result = await client.encode({
  data: 'John Doe, SSN: 123-45-6789, email: john@company.com',
  sourceContainer: 'customer_db.users',
  scoreThreshold: 0.35
});
```

## Request body

- EncodeRequest
  - `data` string, required — Input text containing potential PII
  - `sourceContainer` string — Source identifier (e.g., database table name)
  - `sourceElement` string — Element identifier (e.g., column name)
  - `metadata` EncodingMetadata — Arbitrary metadata attached to the encoding for audit trail purposes
    - `rowId` string
    - `sourceTable` string
    - `sourceColumn` string
    - `recordType` string
    - `source` string
    - `sourceDataType` string
    - `sourceDataKey` string
    - `sourceDataOutlet` string
  - `scoreThreshold` number, double — PII detection confidence threshold. Lower values detect more entities but may produce false positives.
  - `language` string — Language code for PII detection
  - `continuationId` string — Optional correlation ID to group related encoding operations

## Response `200`

Text encoded successfully

- EncodeResponse
  - `success` boolean
  - `encodedData` string — Text with PII replaced by Privacy Twins
  - `continuationId` string — Unique ID for decoding this data later
  - `transformations` Transformation[]
    - `originalHash` string — Cryptographic hash of the original value
    - `twinHash` string — Cryptographic hash of the twin value
    - `entityType` 'PERSON' | 'EMAIL_ADDRESS' | 'PHONE_NUMBER' | 'US_SSN' | 'DATE_TIME' | 'LOCATION' | 'CREDIT_CARD' | 'IP_ADDRESS' | 'IBAN_CODE' | 'US_PASSPORT' | 'US_DRIVER_LICENSE' | 'NRP' | 'MEDICAL_LICENSE' | 'URL' — Type of PII entity detected
    - `catalogItemId` string — Internal catalog item identifier
    - `position` object
      - `start` integer — Start character index in the original text
      - `end` integer — End character index in the original text
    - `score` number, double — Detection confidence score (0.0–1.0)
    - `original` string — Original PII value (available for local decoding)
    - `twin` string — Synthetic Privacy Twin value
    - `components` TransformationComponent[] — Sub-part breakdowns (e.g., first name, last name)
      - `original` string — Original sub-part value
      - `twin` string — Twin sub-part value
      - `type` 'FIRST_NAME' | 'LAST_NAME' | 'CITY' | 'STATE' | 'DATE_FULL_FORMAT' | 'MONTH_NAME' | 'DAY' | 'YEAR' — Component type
  - `statistics` EncodingStatistics
    - `originalLength` integer — Character count of original input
    - `encodedLength` integer — Character count of encoded output
    - `piiEntitiesDetected` integer — Number of PII entities found
    - `transformationsApplied` integer — Number of transformations applied
    - `processingTimeMs` number — Server-side processing time in milliseconds
  - `message` string

## Other responses

- `401` — Authentication failed or token expired
- `403` — Trial expired or subscription required

## Changes

- **2026-08-20** `0e1db3b6bc7c` — 2 breaking, 14 info
  - the `statistics` response's property type/format changed from ``/`` to `object`/`` for status `200`
  - the `transformations/items/` response's property type/format changed from ``/`` to `object`/`` for status `200`
  - added the optional property `statistics/encodedLength` to the response with the `200` status
  - added the optional property `statistics/originalLength` to the response with the `200` status
  - …12 more
- **2026-03-07** `f19009a654f5` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/privacypal/apis/privacypal-api/changes/api/scanner/encode/post.md)

---

[API](https://skmtc.dev/privacypal/apis/privacypal-api.md) · [All operations](https://skmtc.dev/privacypal/apis/privacypal-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/privacypal/privacypal-api/revisions/0e1db3b6bc7c/schema)