Redact text strings

You can use the Tonic Textual REST API to redact text strings, including:

• Plain text

• JSON

• XML

• HTML

Textual provides a specific endpoint for each format. For JSON, XML, and HTML, Textual only redacts the text values. It preserves the underlying structure.

List entity types

get

Returns the full list of built-in entity types that the redaction engine can detect and transform.

Responses

200

Returns all supported entity types

application/json

The type of personally identifiable information (PII) detected, such as NAME_GIVEN, EMAIL_ADDRESS, or CREDIT_CARD.

itemsstring · enumOptional

The type of personally identifiable information (PII) detected, such as NAME_GIVEN, EMAIL_ADDRESS, or CREDIT_CARD.

Possible values:

get

/api/Redact/pii_types

HTTPcURLJavaScriptPython

GET /api/Redact/pii_types HTTP/1.1
Accept: */*

200

Returns all supported entity types

[
  "NUMERIC_VALUE"
]

Plain text

post

Returns a modified version of the provided text string that redacts or synthesizes the detected entity values.

Body

application/json

Request to redact PII from plain text.

generatorDefaultstring · enumOptional

Possible values:

• Off: Ignore the PII type
• Synthesis: Synthesize a new, realistic entity
• Redaction: Tokenize the entity, e.g. [NAME_GIVEN_ssys5]
• GroupingSynthesis: Synthesize entities using consistent grouping across the document
• ReplacementSynthesis: Replace entities with LLM generated values. ReplacementSynthesis is no longer used

Possible values:

docXImagePolicystring · enumOptional

Possible values:

• Redact: Run images through OCR and redact sensitive text
• Ignore: Leave images alone
• Remove: Cover image with opaque black box

Possible values:

docXCommentPolicystring · enumOptional

Possible values:

• Remove: Remove all comments for file
• Ignore: Leave comments alone

Possible values:

pdfSignaturePolicystring · enumOptional

Possible values:

• Redact: Cover signature with opaque black box
• Ignore: Do not attempt to detect signature

Possible values:

pdfSynthModePolicystring · enumOptional

Possible values:

• V1: Original mode with incorrect font, size and style
• V2: New mode

Possible values:

docXTablePolicystring · enumOptional

Possible values:

• Redact: Treat table content normally, feed into redaction process.
• Remove: Replace all characters and symbols in table with a placeholder.

Possible values:

llmClassificationPolicystring · enumOptional

Possible values:

• Disabled: Do not use LLM for structured data classification
• Enabled: Use LLM to classify structured data for PII detection

Possible values:

llmTableClassificationPolicystring · enumOptional

Possible values:

• Disabled: Do not use LLM for structured data classification
• Enabled: Use LLM to classify structured data for PII detection

Possible values:

customPiiEntityIdsstring[] · nullableOptional

A list of custom Pii Entity names to use for NER

textstringOptional

The plain text to redact

Example: My name is John Smith

Responses

200

Returns the redacted text

application/json

The result of a redaction operation, containing the original text, redacted text, and details of each entity replacement.

originalTextstringOptional

The original input text before redaction.

redactedTextstringOptional

The text after redaction has been applied.

usageinteger · int64Optional

The number of words processed.

400

Invalid request parameters

text/plainapplication/jsontext/json

post

/api/Redact

HTTPcURLJavaScriptPython

POST /api/Redact HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 768

{
  "generatorConfig": {
    "NAME_GIVEN": "Redaction",
    "NAME_FAMILY": "Redaction"
  },
  "generatorDefault": "Off",
  "docXImagePolicy": "Redact",
  "docXCommentPolicy": "Remove",
  "pdfSignaturePolicy": "Redact",
  "pdfSynthModePolicy": "V1",
  "docXTablePolicy": "Redact",
  "llmClassificationPolicy": "Disabled",
  "llmTableClassificationPolicy": "Disabled",
  "labelBlockLists": {
    "NAME_FAMILY": {
      "regexes": [
        ".*\\s(disease|syndrom|disorder)"
      ]
    }
  },
  "labelAllowLists": {
    "HEALTHCARE_ID": {
      "regexes": [
        "[a-z]{2}\\d{9}"
      ]
    }
  },
  "generatorMetadata": {
    "ANY_ADDITIONAL_PROPERTY": {
      "version": "V1",
      "customGenerator": "Scramble",
      "swaps": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "constantValue": "text"
    }
  },
  "recordApiRequestOptions": {
    "record": true,
    "retentionTimeInHours": 1,
    "tags": [
      "text"
    ]
  },
  "customPiiEntityIds": [
    "text"
  ],
  "text": "My name is John Smith"
}

{
  "originalText": "text",
  "redactedText": "text",
  "usage": 1,
  "deIdentifyResults": [
    {
      "start": 1,
      "end": 1,
      "newStart": 1,
      "newEnd": 1,
      "label": "text",
      "text": "text",
      "newText": "text",
      "score": 1,
      "language": "text",
      "exampleRedaction": "text",
      "jsonPath": "text",
      "xmlPath": "text",
      "idx": 1
    }
  ]
}

Bulk plain text

post

Returns a modified version of the provided text strings that redacts or synthesizes the detected entity values. Processes multiple text strings in parallel.

Body

application/json

Request model for bulk plain text redaction.

generatorDefaultstring · enumOptional

Possible values:

• Off: Ignore the PII type
• Synthesis: Synthesize a new, realistic entity
• Redaction: Tokenize the entity, e.g. [NAME_GIVEN_ssys5]
• GroupingSynthesis: Synthesize entities using consistent grouping across the document
• ReplacementSynthesis: Replace entities with LLM generated values. ReplacementSynthesis is no longer used

Possible values:

docXImagePolicystring · enumOptional

Possible values:

• Redact: Run images through OCR and redact sensitive text
• Ignore: Leave images alone
• Remove: Cover image with opaque black box

Possible values:

docXCommentPolicystring · enumOptional

Possible values:

• Remove: Remove all comments for file
• Ignore: Leave comments alone

Possible values:

pdfSignaturePolicystring · enumOptional

Possible values:

• Redact: Cover signature with opaque black box
• Ignore: Do not attempt to detect signature

Possible values:

pdfSynthModePolicystring · enumOptional

Possible values:

• V1: Original mode with incorrect font, size and style
• V2: New mode

Possible values:

docXTablePolicystring · enumOptional

Possible values:

• Redact: Treat table content normally, feed into redaction process.
• Remove: Replace all characters and symbols in table with a placeholder.

Possible values:

llmClassificationPolicystring · enumOptional

Possible values:

• Disabled: Do not use LLM for structured data classification
• Enabled: Use LLM to classify structured data for PII detection

Possible values:

llmTableClassificationPolicystring · enumOptional

Possible values:

• Disabled: Do not use LLM for structured data classification
• Enabled: Use LLM to classify structured data for PII detection

Possible values:

customPiiEntityIdsstring[] · nullableOptional

A list of custom Pii Entity names to use for NER

bulkTextstring[]Optional

An array of text strings to redact. Null entries are preserved as null in the response.

Example: ["My name is John Smith","Jane Doe lives in Atlanta"]

Responses

200

Returns the bulk redacted text

application/json

The result of a bulk redaction operation, containing the original texts, redacted texts, and details of each entity replacement.

bulkTextstring[]Optional

The original input texts before redaction.

bulkRedactedTextstring[]Optional

The texts after redaction has been applied.

usageinteger · int64Optional

The total number of words processed across all texts.

post

/api/Redact/bulk

HTTPcURLJavaScriptPython

POST /api/Redact/bulk HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 802

{
  "generatorConfig": {
    "NAME_GIVEN": "Redaction",
    "NAME_FAMILY": "Redaction"
  },
  "generatorDefault": "Off",
  "docXImagePolicy": "Redact",
  "docXCommentPolicy": "Remove",
  "pdfSignaturePolicy": "Redact",
  "pdfSynthModePolicy": "V1",
  "docXTablePolicy": "Redact",
  "llmClassificationPolicy": "Disabled",
  "llmTableClassificationPolicy": "Disabled",
  "labelBlockLists": {
    "NAME_FAMILY": {
      "regexes": [
        ".*\\s(disease|syndrom|disorder)"
      ]
    }
  },
  "labelAllowLists": {
    "HEALTHCARE_ID": {
      "regexes": [
        "[a-z]{2}\\d{9}"
      ]
    }
  },
  "generatorMetadata": {
    "ANY_ADDITIONAL_PROPERTY": {
      "version": "V1",
      "customGenerator": "Scramble",
      "swaps": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "constantValue": "text"
    }
  },
  "recordApiRequestOptions": {
    "record": true,
    "retentionTimeInHours": 1,
    "tags": [
      "text"
    ]
  },
  "customPiiEntityIds": [
    "text"
  ],
  "bulkText": [
    "My name is John Smith",
    "Jane Doe lives in Atlanta"
  ]
}

200

Returns the bulk redacted text

{
  "bulkText": [
    "text"
  ],
  "bulkRedactedText": [
    "text"
  ],
  "usage": 1,
  "deIdentifyResults": [
    {
      "start": 1,
      "end": 1,
      "newStart": 1,
      "newEnd": 1,
      "label": "text",
      "text": "text",
      "newText": "text",
      "score": 1,
      "language": "text",
      "exampleRedaction": "text",
      "jsonPath": "text",
      "xmlPath": "text",
      "idx": 1
    }
  ]
}

JSON

post

Returns a modified version of the JSON that redacts or synthesizes the detected entity values. The redacted JSON has the same structure as the input JSON. Only the primitive JSON values, such as strings and numbers, are modified. Optionally, provide an array of JSONPath expressions in jsonPathIgnorePaths to exclude specific values from redaction.

Body

application/json

Request to redact PII from a JSON document.

generatorDefaultstring · enumOptional

Possible values:

• Off: Ignore the PII type
• Synthesis: Synthesize a new, realistic entity
• Redaction: Tokenize the entity, e.g. [NAME_GIVEN_ssys5]
• GroupingSynthesis: Synthesize entities using consistent grouping across the document
• ReplacementSynthesis: Replace entities with LLM generated values. ReplacementSynthesis is no longer used

Possible values:

docXImagePolicystring · enumOptional

Possible values:

• Redact: Run images through OCR and redact sensitive text
• Ignore: Leave images alone
• Remove: Cover image with opaque black box

Possible values:

docXCommentPolicystring · enumOptional

Possible values:

• Remove: Remove all comments for file
• Ignore: Leave comments alone

Possible values:

pdfSignaturePolicystring · enumOptional

Possible values:

• Redact: Cover signature with opaque black box
• Ignore: Do not attempt to detect signature

Possible values:

pdfSynthModePolicystring · enumOptional

Possible values:

• V1: Original mode with incorrect font, size and style
• V2: New mode

Possible values:

docXTablePolicystring · enumOptional

Possible values:

• Redact: Treat table content normally, feed into redaction process.
• Remove: Replace all characters and symbols in table with a placeholder.

Possible values:

llmClassificationPolicystring · enumOptional

Possible values:

• Disabled: Do not use LLM for structured data classification
• Enabled: Use LLM to classify structured data for PII detection

Possible values:

llmTableClassificationPolicystring · enumOptional

Possible values:

• Disabled: Do not use LLM for structured data classification
• Enabled: Use LLM to classify structured data for PII detection

Possible values:

customPiiEntityIdsstring[] · nullableOptional

A list of custom Pii Entity names to use for NER

jsonTextstring · min: 1Required

The JSON body to redact

Example: {"Name": "John Smith", "Description": "John lives in Atlanta, Ga."}

jsonPathIgnorePathsstring[] · nullableOptional

Optional array of JSONPath expressions for values that should not be redacted. Any JSON element matching these paths will be left unchanged in the output.

Example: ["$.id","$.metadata.timestamp"]

Responses

200

Returns the redacted JSON

application/json

The result of a redaction operation, containing the original text, redacted text, and details of each entity replacement.

originalTextstringOptional

The original input text before redaction.

redactedTextstringOptional

The text after redaction has been applied.

usageinteger · int64Optional

The number of words processed.

400

Invalid JSON input

text/plainapplication/jsontext/json

post

/api/Redact/json

HTTPcURLJavaScriptPython

POST /api/Redact/json HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 850

{
  "generatorConfig": {
    "NAME_GIVEN": "Redaction",
    "NAME_FAMILY": "Redaction"
  },
  "generatorDefault": "Off",
  "docXImagePolicy": "Redact",
  "docXCommentPolicy": "Remove",
  "pdfSignaturePolicy": "Redact",
  "pdfSynthModePolicy": "V1",
  "docXTablePolicy": "Redact",
  "llmClassificationPolicy": "Disabled",
  "llmTableClassificationPolicy": "Disabled",
  "labelBlockLists": {
    "NAME_FAMILY": {
      "regexes": [
        ".*\\s(disease|syndrom|disorder)"
      ]
    }
  },
  "labelAllowLists": {
    "HEALTHCARE_ID": {
      "regexes": [
        "[a-z]{2}\\d{9}"
      ]
    }
  },
  "generatorMetadata": {
    "ANY_ADDITIONAL_PROPERTY": {
      "version": "V1",
      "customGenerator": "Scramble",
      "swaps": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "constantValue": "text"
    }
  },
  "customPiiEntityIds": [
    "text"
  ],
  "jsonText": "{\"Name\": \"John Smith\", \"Description\": \"John lives in Atlanta, Ga.\"}",
  "jsonPathAllowLists": {
    "NAME_GIVEN": [
      "$.name.first"
    ]
  },
  "jsonPathIgnorePaths": [
    "$.id",
    "$.metadata.timestamp"
  ]
}

{
  "originalText": "text",
  "redactedText": "text",
  "usage": 1,
  "deIdentifyResults": [
    {
      "start": 1,
      "end": 1,
      "newStart": 1,
      "newEnd": 1,
      "label": "text",
      "text": "text",
      "newText": "text",
      "score": 1,
      "language": "text",
      "exampleRedaction": "text",
      "jsonPath": "text",
      "xmlPath": "text",
      "idx": 1
    }
  ]
}

XML

post

Returns a modified version of the XML that redacts or synthesizes the detected entity values. The redacted XML has the same structure as the input XML. Only the XML inner text and attribute values are modified.

Body

application/json

Request to redact PII from an XML document.

generatorDefaultstring · enumOptional

Possible values:

• Off: Ignore the PII type
• Synthesis: Synthesize a new, realistic entity
• Redaction: Tokenize the entity, e.g. [NAME_GIVEN_ssys5]
• GroupingSynthesis: Synthesize entities using consistent grouping across the document
• ReplacementSynthesis: Replace entities with LLM generated values. ReplacementSynthesis is no longer used

Possible values:

docXImagePolicystring · enumOptional

Possible values:

• Redact: Run images through OCR and redact sensitive text
• Ignore: Leave images alone
• Remove: Cover image with opaque black box

Possible values:

docXCommentPolicystring · enumOptional

Possible values:

• Remove: Remove all comments for file
• Ignore: Leave comments alone

Possible values:

pdfSignaturePolicystring · enumOptional

Possible values:

• Redact: Cover signature with opaque black box
• Ignore: Do not attempt to detect signature

Possible values:

pdfSynthModePolicystring · enumOptional

Possible values:

• V1: Original mode with incorrect font, size and style
• V2: New mode

Possible values:

docXTablePolicystring · enumOptional

Possible values:

• Redact: Treat table content normally, feed into redaction process.
• Remove: Replace all characters and symbols in table with a placeholder.

Possible values:

llmClassificationPolicystring · enumOptional

Possible values:

• Disabled: Do not use LLM for structured data classification
• Enabled: Use LLM to classify structured data for PII detection

Possible values:

llmTableClassificationPolicystring · enumOptional

Possible values:

• Disabled: Do not use LLM for structured data classification
• Enabled: Use LLM to classify structured data for PII detection

Possible values:

customPiiEntityIdsstring[] · nullableOptional

A list of custom Pii Entity names to use for NER

xmlTextstringOptional

The XML document redact

Example: <note> <to>Tove</to> <from>Jani</from> <heading>Reminder</heading> <body>Don't forget me this weekend!</body> </note>

Responses

200

Returns the redacted XML

application/json

The result of a redaction operation, containing the original text, redacted text, and details of each entity replacement.

originalTextstringOptional

The original input text before redaction.

redactedTextstringOptional

The text after redaction has been applied.

usageinteger · int64Optional

The number of words processed.

400

Invalid XML input

text/plainapplication/jsontext/json

post

/api/Redact/xml

HTTPcURLJavaScriptPython

POST /api/Redact/xml HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 877

{
  "generatorConfig": {
    "NAME_GIVEN": "Redaction",
    "NAME_FAMILY": "Redaction"
  },
  "generatorDefault": "Off",
  "docXImagePolicy": "Redact",
  "docXCommentPolicy": "Remove",
  "pdfSignaturePolicy": "Redact",
  "pdfSynthModePolicy": "V1",
  "docXTablePolicy": "Redact",
  "llmClassificationPolicy": "Disabled",
  "llmTableClassificationPolicy": "Disabled",
  "labelBlockLists": {
    "NAME_FAMILY": {
      "regexes": [
        ".*\\s(disease|syndrom|disorder)"
      ]
    }
  },
  "labelAllowLists": {
    "HEALTHCARE_ID": {
      "regexes": [
        "[a-z]{2}\\d{9}"
      ]
    }
  },
  "generatorMetadata": {
    "ANY_ADDITIONAL_PROPERTY": {
      "version": "V1",
      "customGenerator": "Scramble",
      "swaps": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "constantValue": "text"
    }
  },
  "customPiiEntityIds": [
    "text"
  ],
  "xmlText": "\n            <note>\n            <to>Tove</to>\n            <from>Jani</from>\n            <heading>Reminder</heading>\n            <body>Don't forget me this weekend!</body>\n            </note>\n            "
}

{
  "originalText": "text",
  "redactedText": "text",
  "usage": 1,
  "deIdentifyResults": [
    {
      "start": 1,
      "end": 1,
      "newStart": 1,
      "newEnd": 1,
      "label": "text",
      "text": "text",
      "newText": "text",
      "score": 1,
      "language": "text",
      "exampleRedaction": "text",
      "jsonPath": "text",
      "xmlPath": "text",
      "idx": 1
    }
  ]
}

HTML

post

Returns a modified version of the HTML that redacts or synthesizes the detected entity values. The redacted HTML has the same structure as the input HTML. Only the text contained in the HTML elements is modified.

Body

application/json

Request to redact PII from an HTML document.

generatorDefaultstring · enumOptional

Possible values:

• Off: Ignore the PII type
• Synthesis: Synthesize a new, realistic entity
• Redaction: Tokenize the entity, e.g. [NAME_GIVEN_ssys5]
• GroupingSynthesis: Synthesize entities using consistent grouping across the document
• ReplacementSynthesis: Replace entities with LLM generated values. ReplacementSynthesis is no longer used

Possible values:

docXImagePolicystring · enumOptional

Possible values:

• Redact: Run images through OCR and redact sensitive text
• Ignore: Leave images alone
• Remove: Cover image with opaque black box

Possible values:

docXCommentPolicystring · enumOptional

Possible values:

• Remove: Remove all comments for file
• Ignore: Leave comments alone

Possible values:

pdfSignaturePolicystring · enumOptional

Possible values:

• Redact: Cover signature with opaque black box
• Ignore: Do not attempt to detect signature

Possible values:

pdfSynthModePolicystring · enumOptional

Possible values:

• V1: Original mode with incorrect font, size and style
• V2: New mode

Possible values:

docXTablePolicystring · enumOptional

Possible values:

• Redact: Treat table content normally, feed into redaction process.
• Remove: Replace all characters and symbols in table with a placeholder.

Possible values:

llmClassificationPolicystring · enumOptional

Possible values:

• Disabled: Do not use LLM for structured data classification
• Enabled: Use LLM to classify structured data for PII detection

Possible values:

llmTableClassificationPolicystring · enumOptional

Possible values:

• Disabled: Do not use LLM for structured data classification
• Enabled: Use LLM to classify structured data for PII detection

Possible values:

customPiiEntityIdsstring[] · nullableOptional

A list of custom Pii Entity names to use for NER

htmlTextstringOptional

The HTML document redact

Example: <!DOCTYPE html> <html> <body> <h1>Account Information</h1> <p>Account Holder: John Smith</p> </body> </html>

Responses

200

Returns the redacted HTML

application/json

The result of a redaction operation, containing the original text, redacted text, and details of each entity replacement.

originalTextstringOptional

The original input text before redaction.

redactedTextstringOptional

The text after redaction has been applied.

usageinteger · int64Optional

The number of words processed.

400

Invalid HTML input

text/plainapplication/jsontext/json

post

/api/Redact/html

HTTPcURLJavaScriptPython

POST /api/Redact/html HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 965

{
  "generatorConfig": {
    "NAME_GIVEN": "Redaction",
    "NAME_FAMILY": "Redaction"
  },
  "generatorDefault": "Off",
  "docXImagePolicy": "Redact",
  "docXCommentPolicy": "Remove",
  "pdfSignaturePolicy": "Redact",
  "pdfSynthModePolicy": "V1",
  "docXTablePolicy": "Redact",
  "llmClassificationPolicy": "Disabled",
  "llmTableClassificationPolicy": "Disabled",
  "labelBlockLists": {
    "NAME_FAMILY": {
      "regexes": [
        ".*\\s(disease|syndrom|disorder)"
      ]
    }
  },
  "labelAllowLists": {
    "HEALTHCARE_ID": {
      "regexes": [
        "[a-z]{2}\\d{9}"
      ]
    }
  },
  "generatorMetadata": {
    "ANY_ADDITIONAL_PROPERTY": {
      "version": "V1",
      "customGenerator": "Scramble",
      "swaps": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "constantValue": "text"
    }
  },
  "recordApiRequestOptions": {
    "record": true,
    "retentionTimeInHours": 1,
    "tags": [
      "text"
    ]
  },
  "customPiiEntityIds": [
    "text"
  ],
  "htmlText": "\n            <!DOCTYPE html>\n            <html>\n            <body>\n            <h1>Account Information</h1>\n            <p>Account Holder: John Smith</p>\n            </body>\n            </html>\n            "
}

{
  "originalText": "text",
  "redactedText": "text",
  "usage": 1,
  "deIdentifyResults": [
    {
      "start": 1,
      "end": 1,
      "newStart": 1,
      "newEnd": 1,
      "label": "text",
      "text": "text",
      "newText": "text",
      "score": 1,
      "language": "text",
      "exampleRedaction": "text",
      "jsonPath": "text",
      "xmlPath": "text",
      "idx": 1
    }
  ]
}