For AI agents: a documentation index is available at /llms.txt. Markdown versions of all pages can be requested by appending `.md` to the URL, or by setting the `Accept` header to `text/markdown`.
Skip to main content
Speech to TextFeatures

PII Redaction

Remove personal, health, and payment card information from Batch transcripts.

Available in: Batch. Not available in Realtime or Agent STT.

PII Redaction removes sensitive data, such as names, dates of birth, health conditions, and credit card numbers, from a Batch transcript. Each redacted value is replaced with a label for its entity class, such as [name_given].

Enable PII Redaction​

To enable PII Redaction, set enable_redaction to true and list what to redact in redaction_config.entity_classes:

{
"type": "transcription",
"transcription_config": {
"language": "en",
"enable_redaction": true,
"redaction_config": {
"entity_classes": ["gdpr"]
}
}
}

This Python example submits a job with PII Redaction enabled and prints the redacted results:

from speechmatics.models import ConnectionSettings
from speechmatics.batch_client import BatchClient
from httpx import HTTPStatusError

API_KEY = "YOUR_API_KEY"
PATH_TO_FILE = "example.wav"
LANGUAGE = "en" # Transcription language

settings = ConnectionSettings(
url="https://eu1.asr.api.speechmatics.com/v2",
auth_token=API_KEY,
)

# Define transcription parameters
conf = {
"type": "transcription",
"transcription_config": {
"language": LANGUAGE,
"enable_redaction": True,
"redaction_config": {"entity_classes": ["gdpr"]},
},
}

# Open the client using a context manager
with BatchClient(settings) as client:
try:
job_id = client.submit_job(
audio=PATH_TO_FILE,
transcription_config=conf,
)
print(f"job {job_id} submitted successfully, waiting for transcript")

# Note that in production, you should set up notifications instead of polling.
# Notifications are described here: https://docs.speechmatics.com/speech-to-text/batch/notifications
transcript = client.wait_for_completion(job_id, transcription_format="json-v2")
print(transcript["results"]) # print the redacted results
except HTTPStatusError as e:
if e.response.status_code == 401:
print("Invalid API key - Check your API_KEY at the top of the code!")
elif e.response.status_code == 400:
print(e.response.json()["detail"])
else:
raise e

Choose what to redact​

Each value in redaction_config.entity_classes is either an entity class group or a specific entity class. You can mix both in one list. Start with the regulation group that matches your compliance requirements, then add or remove specific entity classes to match your own data handling guidelines.

  • Regulation groups: gdpr, gdpr_sensitive, hipaa_safe_harbor, cpra, quebec_privacy_act, appi, and appi_sensitive. Each covers the entity classes a regulation treats as personal or sensitive data.
  • Data type groups: health (protected health information), pci (payment card information), and pii (personally identifiable information).
  • Specific entity classes: for example name_given, dob, or credit_card. A general class such as name or location also redacts its subclasses, such as name_given or location_city.

pii is broad. It covers every class in the PII table, including dates, times, amounts of money, and organization names, so it redacts much more than the values that identify a person. Use it only when you want all of these removed.

For example, this configuration redacts everything covered by GDPR, plus given names and credit card numbers:

{
"type": "transcription",
"transcription_config": {
"language": "en",
"enable_redaction": true,
"redaction_config": {
"entity_classes": ["gdpr", "name_given", "credit_card"]
}
}
}

If enable_redaction is true and redaction_config.entity_classes is missing, the job is rejected.

For every entity class and the groups that include it, see Entity Detection classes.

Redacted output​

For the utterance "Mark was born on the 25th of July 2000.", the redacted JSON transcript looks like this (timings omitted):

{
"results": [
{ "type": "word", "alternatives": [{ "content": "[name_given]", "speaker": "S1" }] },
{ "type": "word", "alternatives": [{ "content": "was", "speaker": "S1" }] },
{ "type": "word", "alternatives": [{ "content": "born", "speaker": "S1" }] },
{ "type": "word", "alternatives": [{ "content": "on", "speaker": "S1" }] },
{ "type": "word", "alternatives": [{ "content": "the", "speaker": "S1" }] },
{ "type": "word", "alternatives": [{ "content": "[dob]", "speaker": "S1" }] },
{ "type": "punctuation", "alternatives": [{ "content": ".", "speaker": "S1" }] }
]
}

PII Redaction removes the original values throughout the JSON transcript.

Use PII Redaction with Entity Detection​

PII Redaction works on its own. To also label each detected value with its entity class, enable Entity Detection in the same job. Redacted values are then returned as entity results with an entity_class.

If enable_entities is true in a job with PII Redaction, entities_config.detect_advanced_entities must also be true. Otherwise, the job is rejected. PII Redaction can't be combined with smart formatting entities.

When PII Redaction is enabled, the transcript has no spoken_form or written_form.

Supported languages for PII Redaction​

PII Redaction supports all transcription languages, except:

  • Bashkir
  • Basque
  • Esperanto
  • Galician
  • Interlingua
  • Irish
  • Maltese
  • Marathi
  • Mongolian
  • Urdu
  • Uyghur
  • Welsh

For Mandarin, use the Simplified output locale (cmn-Hans, the default). PII Redaction of Traditional characters (cmn-Hant) isn't supported yet.

Next steps​