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

# STT Redaction: PII, Payment and Health Data

> Redact sensitive text in PyAI speech-to-text results, including stereo calls, speaker diarization, synchronous uploads and live transcription.

Use `redact` to replace detected sensitive text with placeholders such as
`[REDACTED_1]`, `[NAME_1]` and `[EMAIL_ADDRESS_1]`. Redaction is opt-in and
available to every organization when requested with `redact`. It applies to both primary
transcription and automatic recovery.

For ordinary customer calls, start with `redact: ["pii", "pci"]`. Add `"phi"`
when you also want to remove medical information. You do not need `trace: true`
to use STT redaction.

## Choose what to redact

| Selector | What it covers |
| - | - |
| `pii` | Identity and contact details, including names, addresses, email, phone, birth dates, account identifiers and other personal attributes. |
| `pci` | Card numbers, card expiry dates and card security codes. |
| `phi` | Medical conditions, medications, injuries, blood types, procedures and medical measurements. |
| `numbers` or `true` | Numeric entity categories plus sequences of at least three consecutive digits. |
| `aggressive_numbers` | The numeric categories plus every digit sequence, including one- and two-digit values. |
| An entity name | Only that category; for example, `email_address`, `phone_number`, `name` or `credit_card`. |

Contextual entity recognition is for **English**. Digit masking also recognizes
digits in other writing systems. Recognition quality depends on what was
transcribed: a missed or misrecognized word may also be missed by redaction.
Spoken English digit sequences are checked even when `numerals` is off.

## Recorded calls, stereo and speaker diarization

Add `redact` to your normal asynchronous job. Use `channel: true` for stereo, or
`diarize: true` for speaker separation on mono recordings.
The following example assumes the recording contains English speech.

```bash theme={null}
curl https://api.pyai.com/v1/transcription/jobs \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-recording-id" \
  -d '{
    "audio_url": "https://your-storage.example/call.wav",
    "channel": true,
    "transcription_language": "en",
    "redact": ["pii", "pci"],
    "output_formats": ["json", "srt", "vtt"],
    "webhook_url": "https://your-app.example/transcription-ready"
  }'
```

> [!NOTE]
>
> `transcription_language: "en"` selects **English speech**, not English letters.
> For Hindi in English letters, use `transcription_language: "hi"` and
> `output_script: "latin"`. For mixed Hindi–English calls, omit
> `transcription_language` and add `output_script: "latin"`. This preserves the
> spoken words without translating them. See the
> [Hindi, English and mixed-language examples](https://docs.pyai.com/guides/async-transcription-jobs.md#hindi-english-and-mixed-language-examples).

The main text, speaker segments, word text, SRT and VTT all use protected text.
Speaker labels, channel IDs and original timing are retained. Text from both
stereo channels is considered together. Roman-script output is generated after
redaction, so its `source_text` and `source_word` fields are protected too.

Poll the returned job ID or use the signed completion webhook. A completed job's
inline result and `result_url` contain protected output. Recap and completion
integrations receive that same protected transcript. See
[async jobs and callbacks](https://docs.pyai.com/guides/async-transcription-jobs.md) for retry and
signature verification.

Redaction adds processing time after recognition. Use asynchronous jobs for long
recordings; protecting a long transcript can take minutes. If protection cannot
finish within the job's processing budget, the job retries or fails without
publishing an unprotected transcript.

## Synchronous file uploads

Send selectors as a comma-separated multipart field:

```bash theme={null}
curl https://api.pyai.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -F "file=@call.wav" \
  -F "model=pyai-hear" \
  -F "language=en" \
  -F "response_format=verbose_json" \
  -F "redact=pii,pci"
```

`json`, `verbose_json` and `text` responses are protected. A JSON-array string
is also accepted for multipart jobs and synchronous uploads.

## Live transcription

Add selectors to the normal authenticated Hear WebSocket connection:

```text theme={null}
wss://api.pyai.com/v1/audio/transcriptions/stream?protocol=pyai-hear-v1&language=en&redact=pii&redact=pci
```

A protected stream can send one `partial` with `redaction_status: "pending"` and
the fixed text `[REDACTED]` when it receives the first speech draft for an
utterance. Show this as a temporary “Checking speech” indicator. It carries no
recognized words or word times. Replace it with verified text for the same
`utterance_id` and save the corrected `final`. Some turns go straight to the
final. Set `interim_results=false` for finals only.
Requested redaction adds processing time. Keep reading until the stream closes.

If verification is temporarily unavailable for one utterance, the stream emits
`transcript_gap` with its `utterance_id` and `code: "redaction_unavailable"`.
Discard any earlier preview for that ID, mark the gap, and keep reading.
Subsequent protected finals remain usable. The session ends with
`redaction_failed` and close code `1011`. Treat the call transcript as
incomplete. Automatic Recap is skipped for a call with a gap.

When [live word timestamps](https://docs.pyai.com/guides/streaming-stt.md#word-timestamps-and-two-speaker-calls)
are available, each final word retains its original `start` and `end` time
in seconds from the start of the stream. A multiword entity may have the same
placeholder on several word intervals. Display `text` as the readable sentence
and use `words` for timing and speaker ordering.

Recent utterances provide context for the next final. Repeated detected values
reuse their placeholder within the session where the entity category and value
match. Contextual checks can use the general `[REDACTED_n]` label; do not infer
an entity category from every placeholder. Placeholders are not identifiers
you should join across separate calls.

See [streaming STT](https://docs.pyai.com/guides/streaming-stt.md) for audio framing,
finalization and error handling.

## Failure behavior

| Outcome | What your application receives |
| - | - |
| Invalid selector | HTTP `400`; correct `redact` before retrying. |
| Redaction temporarily unavailable | HTTP `403`, `redaction_unavailable`. |
| Sync protection fails | HTTP `503`, `redaction_failed`; no raw transcript. |
| Async protection fails | The job retries within its normal attempt limit, then becomes `failed`; no transcript artifact is published. |
| Live protection is temporarily unavailable for one utterance | A text-free `transcript_gap` identifies the withheld utterance. Later protected speech continues. |
| Live protection returns invalid output | The session ends with `redaction_failed` and close code `1011`. |

Redaction changes **returned transcript text**. It does not mute or delete the
source recording, change recording retention, or remove metadata you supplied
such as `customer_name` or `crm_fields`. Keep those under your application's own
data handling policy.

## Individual selectors

The API also accepts these narrower categories. Selecting `name` or `location`
includes its subtypes.

```text theme={null}
account_number, age, bank_account, blood_type, condition, credit_card,
credit_card_expiration, cvv, date, date_interval, dob, drug, email_address,
event, filename, gender_sexuality, healthcare_number, injury, ip_address,
language, location, location_address, location_city, location_coordinate,
location_country, location_state, location_zip, marital_status,
medical_process, money, name, name_given, name_family,
name_medical_professional, numerical_pii, occupation, organization,
origin, passport_number, password, phone_number, physical_attribute,
political_affiliation, religion, routing_number, ssn, statistics, time,
url, username, vehicle_id, zodiac_sign
```

`expiration` is an alias for `credit_card_expiration`; `pin` is an alias for
`password`. Unknown values are rejected instead of silently ignored.

The older `trace: true` option remains a separate compliance add-on with its
existing entitlement and metering. Combining Trace with `redact` retains the
five legacy identity/payment checks as well as your chosen selectors. Use
`redact` for stereo, diarized, sync and live redaction.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.