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

OK

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

OK

[
  "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.

Responses

200

OK

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

Bad Request

text/plainapplication/jsontext/json

post

/api/Redact

HTTPcURLJavaScriptPython

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

{
  "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": {
      "strings": [],
      "regexes": [
        ".*\\s(disease|syndrom|disorder)"
      ]
    }
  },
  "labelAllowLists": {
    "HEALTHCARE_ID": {
      "strings": [],
      "regexes": [
        "[a-z]{2}\\d{9}"
      ]
    }
  },
  "generatorMetadata": {
    "ANY_ADDITIONAL_PROPERTY": {
      "version": "V1",
      "customGenerator": "Scramble",
      "swaps": {
        "ANY_ADDITIONAL_PROPERTY": "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.

Responses

200

OK

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: 805

{
  "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": {
      "strings": [],
      "regexes": [
        ".*\\s(disease|syndrom|disorder)"
      ]
    }
  },
  "labelAllowLists": {
    "HEALTHCARE_ID": {
      "strings": [],
      "regexes": [
        "[a-z]{2}\\d{9}"
      ]
    }
  },
  "generatorMetadata": {
    "ANY_ADDITIONAL_PROPERTY": {
      "version": "V1",
      "customGenerator": "Scramble",
      "swaps": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  },
  "recordApiRequestOptions": {
    "record": true,
    "retentionTimeInHours": 1,
    "tags": [
      "text"
    ]
  },
  "customPiiEntityIds": [
    "text"
  ],
  "bulkText": [
    "My name is John Smith",
    "Jane Doe lives in Atlanta"
  ]
}

200

OK

{
  "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.

Responses

200

OK

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: 853

{
  "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": {
      "strings": [],
      "regexes": [
        ".*\\s(disease|syndrom|disorder)"
      ]
    }
  },
  "labelAllowLists": {
    "HEALTHCARE_ID": {
      "strings": [],
      "regexes": [
        "[a-z]{2}\\d{9}"
      ]
    }
  },
  "generatorMetadata": {
    "ANY_ADDITIONAL_PROPERTY": {
      "version": "V1",
      "customGenerator": "Scramble",
      "swaps": {
        "ANY_ADDITIONAL_PROPERTY": "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.

Responses

200

OK

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: 880

{
  "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": {
      "strings": [],
      "regexes": [
        ".*\\s(disease|syndrom|disorder)"
      ]
    }
  },
  "labelAllowLists": {
    "HEALTHCARE_ID": {
      "strings": [],
      "regexes": [
        "[a-z]{2}\\d{9}"
      ]
    }
  },
  "generatorMetadata": {
    "ANY_ADDITIONAL_PROPERTY": {
      "version": "V1",
      "customGenerator": "Scramble",
      "swaps": {
        "ANY_ADDITIONAL_PROPERTY": "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.

Responses

200

OK

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: 968

{
  "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": {
      "strings": [],
      "regexes": [
        ".*\\s(disease|syndrom|disorder)"
      ]
    }
  },
  "labelAllowLists": {
    "HEALTHCARE_ID": {
      "strings": [],
      "regexes": [
        "[a-z]{2}\\d{9}"
      ]
    }
  },
  "generatorMetadata": {
    "ANY_ADDITIONAL_PROPERTY": {
      "version": "V1",
      "customGenerator": "Scramble",
      "swaps": {
        "ANY_ADDITIONAL_PROPERTY": "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
    }
  ]
}