Settings for redaction

This page describes the user settings available for the Redaction feature using the Management API. With the User settings of the Management API, you can configure the default behavior of the Redaction feature.

For more general information, see Redaction.

For more information about user settings, see User settings.


Settings for redaction - Management API

This section provides a basic example of how to update your user settings for redaction using the Management API.

To update user settings for redaction with the Management API, use the following operation:

PATCH https://api.symbl.ai/v1/manage/settings

For more information about this operation, such as details about the request body, see Update user settings.

When you update user settings for redaction, use the following path: /redaction. This path supports the replace operation.

[
  {
    "op": "replace",
    "path": "/redaction",
    "value": {
      "default": boolean,
      "type": string,
      "exclude": array,
      "custom": {
        "default": string,
        "<ENTITY_NAME>": string,
        ...
    }
  }
]

The following table describes the settings that Symbl.ai supports for redaction.

SettingDescription
defaultValid values are true and false.

Whether redaction should be enabled by default.

The default value is false.
typeValid values are default, obfuscation, and custom.

Determines how detected entities are redacted.

When set to default, redacted entities are replaced with the name of the managed entity. For example, the sentence My name is Tony Stark becomes My name is [PERSON_NAME].

When set to obfuscation, redacted entities are replaced with asterisks. For example, the sentence My name is Tony Stark becomes My name is [****].

When set to custom, redacted entities are replaced with custom values that you specify. For example, the sentence My name is Tony Stark can become My name is [John_Doe].

The default value is default.
excludeValid value is an array of strings. The strings must correspond to the names of managed entities or custom entities and the strings must be in all capital letters. For example, ["PERSON_NAME"].

Excludes the specified managed entities from redaction. For example, if you wanted to include the names of individuals and cities in your transcripts while redacting all other detected entities, you would set exclude to ["PERSON_NAME", "LOCATION_CITY"].

If you use the exclude optional query parameter when you get messages, the value for the query parameter overrides your user settings.

No managed entities are excluded by default.
customThis object is required only if type is set to custom.

Contains specific values used to replace detected entities. The object must have a default property. The object can also have any number of additional properties that correspond to the names of managed entities.
custom.defaultValid values are default and obfuscation.

Determines how a detected entity is redacted if no custom value is provided for that entity.
custom.<ENTITY_SUBTYPE><ENTITY_SUBTYPE> must be the subtype of a managed or custom entity. The value must be in all capital letters. For example, PERSON_NAME.

Valid value is a string. For example, "PERSON_NAME": "John Doe".

Contains the specific value to use for redaction when the corresponding entity is detected.

Authentication

These requests require an access token, as described in Authenticate.

Example request - update settings

The following example demonstrates how to update your redaction settings. For more information about the request, see Update User Settings.

This example enables redaction by default, excludes the PERSON_NAME and EMAIL_ADDRESS entities from being redacted, and specifies custom redaction values for the SSN and DRIVERS_LICENSE entities. Remember to use ALL CAPS for excluded entities.

import fetch from 'node-fetch';

const accessToken = '<ACCESS_TOKEN>';
const settings = [
  {
    'op': 'replace',
    'path': '/redaction',
    'value': {
      'default': true,
      'type': 'custom',
      'exclude': ['PERSON_NAME', 'EMAIL_ADDRESS'],
      'custom': {
        'SSN': 'Social Security Number',
        'DRIVERS_LICENSE': 'Personal ID',
        'default': 'obfuscation'
      }
    }
  }
]

const fetchResponse = await fetch(`https://api.symbl.ai/v1/manage/settings`, {
  method: patch,
  body: JSON.stringify(settings),
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

const responseBody = await fetchResponse.json();

console.log(responseBody);

Where:

  • <ACCESS_TOKEN> is a valid API access token.

Response

The following table describes the response body that is returned by this request.

FieldDescription
idThe static unique ID of your settings.
redactionContains settings for the Redaction feature.
redaction.defaultWhether redaction is enabled by default.
redaction.typeThe type of redaction that is used by default.

If the value is default, redacted entities are replaced with the name of the managed entity. For example, the sentence My name is Tony Stark becomes My name is [PERSON_NAME].

If the value is obfuscation, redacted entities are replaced with asterisks. For example, the sentence My name is Tony Stark becomes My name is [****].

If the value is custom, redacted entities are replaced with custom values specified in the custom object. For example, the sentence My name is Tony Stark can become My name is [John_Doe].
redaction.customContains the definitions for custom redaction of detected entities. These values are only used if redaction.type is custom.
redaction.custom.defaultThe type of redaction that is used if no custom definition for a detected entity is found.
redaction.custom.<ENTITY_SUBTYPE>The replacement value for the corresponding entity if detected and redaction is enabled. There may be zero or more replacement definitions in the custom object.
redaction.excludeAn array of entity subtypes. These entities are excluded from redaction, if redaction is enabled.

Example response

{
  "settings": {
    "id": "1234567891011121",
    "redaction": {
      "default": true,
      "type": "custom",
      "exclude": [
        "PERSON_NAME",
        "EMAIL_ADDRESS"
      ],
      "custom": {
        "SSN": "Social Security Number",
        "DRIVERS_LICENSE": "Personal ID",
        "default": "obfuscation"
      }
    }
  }
}