Request Parameters

The params argument to mask() is a VARIANT (typically built with OBJECT_CONSTRUCT) that controls detection, operators, output format, and document handling.

Every parameter is optional. Calling mask(text) with no params uses the defaults shown below.

Detection

detection_mode

"accurate" (default) prioritizes recall. "fast" prioritizes lower latency and may miss entities that accurate finds.

OBJECT_CONSTRUCT('detection_mode', 'fast')

threshold

Minimum confidence score 0.0 to 1.0. Default 0.5. Lower catches more entities (more false positives); higher is more precise but misses ambiguous mentions. Overridable per entity in entity_config.

entities

Array of entity types to detect. When set, all other types are ignored. Default null (use the default entity set). Mutually exclusive with exclude_entity_types.

OBJECT_CONSTRUCT('entities', ARRAY_CONSTRUCT('PERSON', 'US_SSN'))

exclude_entity_types

Array of entity types to subtract from the default set — “detect everything except these.” Default null. Mutually exclusive with entities.

OBJECT_CONSTRUCT('exclude_entity_types', ARRAY_CONSTRUCT('DATE_TIME', 'LOCATION'))

language

Two-letter supported language code. Default "en". See Languages.

allow_list

Array of regex patterns for values that should not be flagged as PII. Default null. Plain strings behave like exact matches unless they contain regex metacharacters.

OBJECT_CONSTRUCT('allow_list', ARRAY_CONSTRUCT('Blue Cross PPO', 'Acme Corp'))

Each entry can be a plain string pattern or an object with a pattern and optional entity_types scope:

OBJECT_CONSTRUCT('allow_list', ARRAY_CONSTRUCT(
  'Acme Corp',
  OBJECT_CONSTRUCT('pattern', 'support@acme\\.com', 'entity_types', ARRAY_CONSTRUCT('EMAIL_ADDRESS'))
))

key_filter

Object that limits detection to specific JSON keys, or excludes specific JSON keys from detection. Default null. Applies when the input is valid JSON.

Use mode: "include" to keep detections only in matching keys:

OBJECT_CONSTRUCT(
  'key_filter', OBJECT_CONSTRUCT(
    'mode', 'include',
    'keys', ARRAY_CONSTRUCT('patient.name', 'patient.contact.*', 'notes.[*].text')
  )
)

Use mode: "exclude" to mask everything except matching keys:

OBJECT_CONSTRUCT(
  'key_filter', OBJECT_CONSTRUCT(
    'mode', 'exclude',
    'keys', ARRAY_CONSTRUCT('audit.**', 'source_system')
  )
)

Path rules:

• Bare keys such as name match that key at any depth.
• Dot paths such as patient.name are anchored from the JSON root.
• * matches exactly one object key or array segment.
• ** matches the rest of a subtree and must be the last segment.
• [*] matches one array index.

entity_collapse

Float 0.0 to 1.0 enables identity resolution: “Chen”, “Sarah Chen”, and “Dr. Chen” share one placeholder. Default -1 (disabled). Lower values require stronger evidence that mentions refer to the same identity; higher values merge more aggressively. See Identity Resolution for tuning and examples.

extend_word_boundaries

Boolean. Default true. Extends detections to full word boundaries; prevents artifacts like [PERSON_1]ith.

Operators & entity configuration

entity_config

Object keyed by entity type. Each value specifies the operator and optional params. A DEFAULT key sets the fallback for entities not explicitly configured. Default {} (all entities use type_numbered).

OBJECT_CONSTRUCT(
  'entity_config', OBJECT_CONSTRUCT(
    'DEFAULT', OBJECT_CONSTRUCT('operator', 'type_numbered'),
    'PERSON', OBJECT_CONSTRUCT('operator', 'faker', 'threshold', 0.7),
    'US_SSN', OBJECT_CONSTRUCT(
      'operator', 'mask',
      'operator_params', OBJECT_CONSTRUCT('masking_char', '*')
    )
  )
)

Custom entities defined with description or expressions fields go here too. See Operators, Custom Entities (Description), and Custom Entities (Regex).

Use value_filter when a broad entity type should only transform a narrower kind of value. The filter runs before the operator, so ignored values stay in the text and do not create ledger entries.

Entity	value_filter	Transformed	Ignored
DATE_TIME	absolute_date	Calendar dates and date-like partials: March 14, 2026, 2026-03-14T09:30:00Z, July 12, 07/12, March 2026, 2020.	Relative phrases and time-only values: next month, in two weeks, today, Monday, 9:30 AM.

Example: mask calendar dates while leaving incidental temporal language alone.

OBJECT_CONSTRUCT(
  'entity_config', OBJECT_CONSTRUCT(
    'DATE_TIME', OBJECT_CONSTRUCT(
      'operator', 'mask',
      'value_filter', 'absolute_date'
    )
  )
)

Response control

include_entity_ledger

Boolean. Default true. Set false to omit the entity_ledger array when you only need columns[].deidentified_text.

include_analyzer_results

Boolean. Default true. Controls whether columns[].analyzer_results includes detected spans and confidence scores.

Document processing

include_redacted_document

Boolean. Default false. When true and the input supports file redaction, the response includes a redacted_document field with the de-identified file (base64-encoded, zlib-compressed). PDF, image, and DICOM inputs support visual redaction; DOCX and RTF return de-identified text.

include_redaction_metadata

Boolean. Default false. Returns pixel-coordinate bounding boxes for PDF, image, and DICOM visual redactions.

include_searchable_text_layer

Boolean. Default false. Adds an invisible text layer to returned redacted PDFs so they remain searchable.

pdf_mode

"redact" (default) blacks out detected PII; "annotate" highlights PII in place without redacting. See PDF.

document_extraction_mode

"simple" (default) fast text extraction; "structured" uses structured extraction and exports the modified text in structured_output_format. Used for PDF and DOCX text output; it does not return an edited .docx file.

structured_output_format

"markdown" (default), "html", "text", or "json". Output format when document_extraction_mode: "structured".

dicom_metadata_mode

Controls what happens to PHI inside DICOM metadata tags. Text burned into image pixels is handled by visual redaction regardless of this setting.

Mode	Behavior
"strip" (default)	Delete metadata tags that commonly carry PHI (PatientName, Birth Date, Institution, etc.). The file remains valid DICOM but loses identifying metadata.
"anonymize"	Replace PHI tag values with placeholders ("REDACTED" for names, "19000101" for dates, "000000" for times, hash-derived values for UIDs). Preserves tag presence for downstream systems that require specific fields.
"none"	Skip all metadata scrubbing. Only text burned into image pixels is redacted. Use when PHI exposure in metadata is managed separately.

redaction_fill_color

RGB tuple. Default [0, 0, 0] (black). Fill color for redaction boxes in PDFs and images.

redaction_text_color

RGB tuple. Default [255, 255, 255] (white). Color of the redaction placeholder text overlay.