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.

Authentication

This request requires an access token, as described in Authenticate.

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

Note that if you are making this request for the first time for a new user account, you need to use the add operation instead of the replace operation to create the redaction path. Update user settings. Once you have established user settings, use the replace operation.

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

Example request - add redaction settings

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

import fetch from 'node-fetch';

const accessToken = '<ACCESS_TOKEN>';
const settings = [
  {
    'op': 'add',
    '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);

For response fields and example, see Response.

Example request - replace redaction 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.

Field	Description
`id`	The static unique ID of your settings.
`redaction`	Contains settings for the Redaction feature.
`redaction.default`	Whether redaction is enabled by default.
`redaction.type`	The 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.custom`	Contains the definitions for custom redaction of detected entities. These values are only used if `redaction.type` is `custom`.
`redaction.custom.default`	The 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.exclude`	An 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"
      }
    }
  }
}