Kids Chat APIs

1. Overview

The Whitelist is known as the Kids Chat on the frontend. In this document it will still be referred to as the Whitelist.

These APIs allow you to query and modify the Whitelist filter state.

The Whitelist is best understood as a deny first list of words people are allowed to use. Only when a user has matched an allowed word or phrase will the content be permitted. The Whitelist also has its own set of blacklist rules called disallowed phrases that prevent combinations of whitelisted words being used together in ways that could be just as bad as using a blacklisted word.

Allowed Words
Tags
Disallowed Phrases
Advanced Disallowed Phrases

2. Retrieve the Whitelist

This API is used to retrieve the entire Whitelist. You should use this API if you intend to retrieve the entire Whitelist and store it to be used for realtime feedback as a user enters content. If you only intend to send content into CleanSpeak to filter against the Whitelist, use the Filter Content API instead.

2.1. Request

The Whitelist may contain in excess of 10,000 words and disallowed phrases. This API will return the entire list in the response body which may be several megabytes in size.

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist

URI (4.x)

GET /api/filter/whitelist

2.2. Response

Table 1. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 2. Response Body
whitelist [Object]	The Whitelist object.
whitelist.advancedDisallowedEntries [Array]	An array of advanced disallowed entries on the Whitelist.
whitelist.advancedDisallowedEntries`[x]`.parts [Array<String>]	An array of Whitelist tags and optional wild cards that in the order that makes up the advanced disallowed phrase.
whitelist.allowedEntries [Array]	An array of allowed entries on the Whitelist.
whitelist.allowedEntries`[x]`.exclusions [Array<String>]	An array of the inflections to be excluded for this word.
whitelist.allowedEntries`[x]`.inflect [Boolean]	When this value is true it indicates the word has been inflected and the inflections will be returned in the response.
whitelist.allowedEntries`[x]`.inflections [Array<String>]	An array of the inflections for this word.
whitelist.allowedEntries`[x]`.locale [String]	The locale of the word. See Locales.
whitelist.allowedEntries`[x]`.text [String]	The allowed word.
whitelist.disallowedEntries [Array]	An array of disallowed entries on the Whitelist.
whitelist.disallowedEntries`[x]`.parts [Array<String>]	An array of allowed entries in the order that makes up the disallowed phrase.

Example Response JSON

{
  "whitelist": {
    "allowedEntries": [
      {
        "locale": "en",
        "text": "a",
        "inflect": false,
        "tags": [
          "Noun"
        ]
      },
      {
        "text": "dump",
        "inflect": true,
        "inflections": [
          "dumping",
          "dumps",
          "dumped"
        ],
        "tags": [
          "Noun",
          "Verb"
        ],
        "locale": "en"
      },
      {
        "text": "take",
        "tags": [
          "Noun",
          "Verb"
        ],
        "inflections": [
          "took",
          "taken",
          "takes",
          "taking"
        ],
        "inflect": true,
        "locale": "en"
      }
    ],
    "advancedDisallowedEntries": [
      {
        "parts": [
          "Penis-Reference",
          "Preposition",
          "Personal-Pronoun",
          "Vagina-Reference"
        ]
      }
    ],
    "disallowedEntries": [
      {
        "parts": [
          "blue",
          "waffle"
        ]
      },
      {
        "parts": [
          "take",
          "a",
          "dump"
        ]
      }
    ]
  }
}

3. Retrieve an Allowed Word

Retrieve a single allowed word by Id or by Text and Locale.

Available since 3.9.0

3.1. Retrieve by Id

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist/allowed/{id}

URI (4.x)

GET /api/filter/whitelist/allowed/{id}

Table 3. Request Parameters
id [Integer] required	The Id of the entry to retrieve.

3.2. Retrieve by Text and Locale

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist/allowed?text={text}&locale={locale}

URI (4.x)

GET /api/filter/whitelist/allowed?text={text}&locale={locale}

Table 4. Request Parameters
text [String] required	The text of the entry to retrieve
locale [Locale] required	The locale of the entry to retrieve. See Locale.

3.3. Response

Table 5. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
404	The object you requested doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 6. Response Body
entry.exclusions [Array<String>]	An array of words NOT to include on the whitelist. These words are a subset of the inflections of the text.
entry.id [Integer]	A unique Id for the entry.
entry.inflect [Boolean]	A flag to enable all inflections of the word as whitelisted. Exclusions only apply when inflect is true as they only exclude inflections.
entry.locale [String]	The entry locale. See Locale.
entry.status [String]	This will always be `ACTIVE` as this API only operates on the active filter state.
entry.tags [Array<String>]	The associated whitelist tags for this entry.
entry.text [String]	The text for the word.

Example Response JSON

{
  "entry": {
    "exclusions": [
      "towelled",
      "towelling"
    ],
    "id": 42,
    "inflect": true,
    "locale": "en",
    "status": "ACTIVE",
    "tags": [
      "Noun",
      "Verb"
    ],
    "text": "towel"
  }
}

4. Retrieve all Allowed Words

Available since 3.9.0

4.1. Request

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist/allowed?startRow={startRow}&numberOfResults={numberOfResults}&sort[0].field={sort.field}&sort[0].order={sort.order}

URI (4.x)

GET /api/filter/whitelist/allowed?startRow={startRow}&numberOfResults={numberOfResults}&sort[0].field={sort.field}&sort[0].order={sort.order}

Table 7. Request Parameters
startRow [Integer] Optional Defaults to 0	The starting offset of the results.
numberOfResults [Integer] Optional Defaults to 20	The number of results you want returned.
sort [Array] Optional Defaults to sorting by `id` with `asc` order	Sorts allow you to control the order that results should be returned in. This affects how startRow and numberOfResults work, that is why a default sort order is defined.
sort`[x]`.field [String] required	The field to sort the results on. You can sort on multiple fields at a time by using the array offsets. The sort field is required for any sorts you supply. The following values are allowed: `id` `text` `locale`
sort`[x]`.order [String] Optional Defaults to `asc`	The order to sort the field on. Every field can have its own order. Allowed orders: `asc` - Ascending `desc` - Descending

4.2. Response

Table 8. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 9. Response Body
entries`[x]`.exclusions [Array<String>]	An array of words NOT to include on the whitelist. These words are a subset of the inflections of the text.
entries`[x]`.id [Integer]	A unique Id for the entry.
entries`[x]`.inflect [Boolean]	A flag to enable all inflections of the word as whitelisted. Exclusions only apply when inflect is true as they only exclude inflections.
entries`[x]`.locale [String]	The entry locale. See Locale.
entries`[x]`.status [String]	This will always be `ACTIVE` as this API only operates on the active filter state.
entries`[x]`.tags [Array<String>]	The associated whitelist tags for this entry.
entries`[x]`.text [String]	The text for the word
totalResults [Integer]	The total number of results available.

Example Response JSON

{
  "entries": [
    {
      "exclusions": [
        "towelled",
        "towelling"
      ],
      "id": 42,
      "inflect": true,
      "locale": "en",
      "status": "ACTIVE",
      "tags": [
        "Noun",
        "Verb"
      ],
      "text": "towel"
    },
    {
      "exclusions": [],
      "id": 43,
      "inflect": false,
      "locale": "en",
      "status": "ACTIVE",
      "tags": [
        "Noun",
        "Verb"
      ],
      "text": "guide"
    }
  ],
  "totalResults": 3
}

5. Search for Allowed Words

Available since 3.11.0

5.1. Request

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist/allowed/search?text={text}&startRow={startRow}&numberOfResults={numberofResults}

URI (4.x)

GET /api/filter/whitelist/allowed/search?text={text}&startRow={startRow}&numberOfResults={numberofResults}

Only a select few options are shown in the example url above. See below for all options.

Table 10. Request Parameters
locale [String] Optional Defaults to any locale	Restricts results to a specific set of locales. If no locales are supplied then all will be returned. Locales can be provided more than once to filter on several at once. In addition to the locales listed at Locales you can use `none` to include words without a locale.
numberOfResults [Integer] Optional Defaults to `20`	The number of results to return in the response. Used for paging.
sort [Array] Optional	An array of sort options. Defaults to sorting on `id` and `asc`. Sorts are applied recursively in order.
sort`[x]`.field [String] required	The field to sort on. This is required for any sort supplied.
sort`[x]`.order [String] Optional Defaults to `asc`	The order to sort this field.
startRow [Integer] Optional Defaults to `0`	The offset of the desired results. Used for paging.
tag [String] Optional Defaults to any tag	Restricts results to a specific tag. If no tags are supplied then all will be returned. Tags can be provided more than once to filter on several at once. `none` is allowed as a tag alias for no tag. Note: The tag must exist or the request will fail.
text [String] Optional	Text to match in the allowed words. Use stars for wildcards.

5.2. Response

Table 11. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 12. Response Body
entries`[x]`.exclusions [Array<String>]	An array of words NOT to include on the whitelist. These words are a subset of the inflections of the text.
entries`[x]`.id [Integer]	A unique Id for the entry.
entries`[x]`.inflect [Boolean]	A flag to enable all inflections of the word as whitelisted. Exclusions only apply when inflect is true as they only exclude inflections.
entries`[x]`.locale [String]	The entry locale. See Locale.
entries`[x]`.status [String]	This will always be `ACTIVE` as this API only operates on the active filter state.
entries`[x]`.tags [Array<String>]	The associated whitelist tags for this entry.
entries`[x]`.text [String]	The text for the word
totalResults [Integer]	The total number of results available.

Example Response JSON

{
  "entries": [
    {
      "exclusions": [
        "towelled",
        "towelling"
      ],
      "id": 42,
      "inflect": true,
      "locale": "en",
      "status": "ACTIVE",
      "tags": [
        "Noun",
        "Verb"
      ],
      "text": "towel"
    },
    {
      "exclusions": [],
      "id": 43,
      "inflect": false,
      "locale": "en",
      "status": "ACTIVE",
      "tags": [
        "Noun",
        "Verb"
      ],
      "text": "guide"
    }
  ],
  "totalResults": 3
}

6. Delete an Allowed Word

Available since 3.9.0

6.1. Delete by Id

URI (3.x, deprecated in 4.0.0)

DELETE /filter/whitelist/allowed/{id}

URI (4.x)

DELETE /api/filter/whitelist/allowed/{id}

Table 13. Request Parameters
id [Integer] required	The Id of the entry to delete.

6.2. Response

Table 14. Response Codes
Code	Description
200	The request was successful. The response will be empty.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
404	The object you are trying to delete doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

7. Create an Allowed Word

Available since 3.9.0

7.1. Request

URI (3.x, deprecated in 4.0.0)

POST /filter/whitelist/allowed

URI (4.x)

POST /api/filter/whitelist/allowed

Table 15. Request Body
entry.exclusions [Array<String>] Optional	An array of words NOT to include on the whitelist. These words are a subset of the inflections of the text.
entry.inflect [Boolean] Optional defaults to `false`	A flag to enable automatic inflections of a word. Ex: `agree` → `agreed`, `agreeing`, `agrees`. This must be enabled to use exclusions.
entry.locale [String] required	The entry locale. See Locale.
entry.tags [Array<String>] Optional	The associated whitelist tags for this entry.
entry.text [String] required	The text for the word

Request Body JSON Example

{
  "entry": {
    "exclusions": [
      "towelled",
      "towelling"
    ],
    "inflect": true,
    "locale": "en",
    "tags": [
      "Noun",
      "Verb"
    ],
    "text": "towel"
  }
}

7.2. Response

Table 16. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 17. Response Body
entry.exclusions [Array<String>]	An array of words NOT to include on the whitelist. These words are a subset of the inflections of the text.
entry.id [Integer]	A unique Id for the entry.
entry.inflect [Boolean]	A flag to enable all inflections of the word as whitelisted. Exclusions only apply when inflect is true as they only exclude inflections.
entry.locale [String]	The entry locale. See Locale.
entry.status [String]	This will always be `ACTIVE` as this API only operates on the active filter state.
entry.tags [Array<String>]	The associated whitelist tags for this entry.
entry.text [String]	The text for the word.

Example Response JSON

{
  "entry": {
    "exclusions": [
      "towelled",
      "towelling"
    ],
    "id": 42,
    "inflect": true,
    "locale": "en",
    "status": "ACTIVE",
    "tags": [
      "Noun",
      "Verb"
    ],
    "text": "towel"
  }
}

8. Update an Allowed Word

Available since 3.9.0

8.1. Request

URI (3.x, deprecated in 4.0.0)

PUT /filter/whitelist/allowed/{id}

URI (4.x)

PUT /api/filter/whitelist/allowed/{id}

Table 18. Request Parameters
id [Integer] required	The Id of the entry you are updating.

Table 19. Request Body
entry.exclusions [Array<String>] Optional	An array of words NOT to include on the whitelist. These words are a subset of the inflections of the text.
entry.inflect [Boolean] Optional defaults to `false`	A flag to enable automatic inflections of a word. Ex: `agree` → `agreed`, `agreeing`, `agrees`. This must be enabled to use exclusions.
entry.locale [String] required	The entry locale. See Locale.
entry.tags [Array<String>] Optional	The associated whitelist tags for this entry.
entry.text [String] required	The text for the word

Request Body JSON Example

{
  "entry": {
    "exclusions": [
      "towelled",
      "towelling"
    ],
    "inflect": true,
    "locale": "en",
    "tags": [
      "Noun",
      "Verb"
    ],
    "text": "towel"
  }
}

8.2. Response

Table 20. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
404	The object you are trying to update doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 21. Response Body
entry.exclusions [Array<String>]	An array of words NOT to include on the whitelist. These words are a subset of the inflections of the text.
entry.id [Integer]	A unique Id for the entry.
entry.inflect [Boolean]	A flag to enable all inflections of the word as whitelisted. Exclusions only apply when inflect is true as they only exclude inflections.
entry.locale [String]	The entry locale. See Locale.
entry.status [String]	This will always be `ACTIVE` as this API only operates on the active filter state.
entry.tags [Array<String>]	The associated whitelist tags for this entry.
entry.text [String]	The text for the word.

Example Response JSON

{
  "entry": {
    "exclusions": [
      "towelled",
      "towelling"
    ],
    "id": 42,
    "inflect": true,
    "locale": "en",
    "status": "ACTIVE",
    "tags": [
      "Noun",
      "Verb"
    ],
    "text": "towel"
  }
}

9. Retrieve a Tag

Available since 3.9.0

9.1. Retrieve by Id

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist/tag/{id}

URI (4.x)

GET /api/filter/whitelist/tag/{id}

Table 22. Request Parameters
id [Integer] required	The Id of the tag you want.

9.2. Retrieve by Name

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist/tag?name={name}

URI (4.x)

GET /api/filter/whitelist/tag?name={name}

Table 23. Request Parameters
name [String] required	The name of the tag you want.

9.3. Response

Table 24. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
404	The object you requested doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 25. Response Body
tag.id [Integer]	The Id for the tag.
tag.name [String]	The name of the tag.

Response Body Example JSON

{
  "tag": {
    "id": 3,
    "name": "Noun"
  }
}

10. Retrieve all Tags

Available since 3.9.0

10.1. Request

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist/tag

URI (4.x)

GET /api/filter/whitelist/tag

10.2. Response

Table 26. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 27. Response Body
tags`[x]`.id [Integer]	The Id of the tag.
tags`[x]`.name [String]	The name of the tag.

Response Body Example JSON

{
  "tags": [
    {
      "id": 3,
      "name": "Noun"
    },
    {
      "id": 4,
      "name": "Verb"
    }
  ]
}

11. Delete a Tag

Available since 3.9.0

11.1. Request

URI (3.x, deprecated in 4.0.0)

DELETE /filter/whitelist/tag/{id}

URI (4.x)

DELETE /api/filter/whitelist/tag/{id}

11.2. Response

Table 28. Response Codes
Code	Description
200	The request was successful. The response will be empty.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
404	The object you are trying to delete doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

12. Create a Tag

Available since 3.9.0

12.1. Request

URI (3.x, deprecated in 4.0.0)

POST /filter/whitelist/tag

URI (4.x)

POST /api/filter/whitelist/tag

Table 29. Request Body
tag.name [String] required	The name of the new tag. Must not already exist.

Request Body Example JSON

{
  "tag": {
    "name": "Conjunction"
  }
}

12.2. Response

Table 30. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 31. Response Body
tag.id [Integer]	The Id for the tag.
tag.name [String]	The name of the tag.

Response Body Example JSON

{
  "tag": {
    "id": 3,
    "name": "Noun"
  }
}

13. Retrieve a Disallowed Phrase

13.1. Retrieve by Id

Retrieve a disallowed phrase by Id.

Available since 3.10.0

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist/disallowed-phrase/{id}

URI (4.x)

GET /api/filter/whitelist/disallowed-phrase/{id}

Table 32. Request Parameters
id [Integer] required	The Id of the entry to retrieve.

13.2. Response

Table 33. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
404	The object you requested doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 34. Response Body
phrase.id [Integer]	The Id of the phrase.
phrase.parts [Array<String>]	The associated allowed words for the phrase.
phrase.status [String]	The status of the phrase. This will always be `ACTIVE` as the APIs only operate on the active filter state.

Example Resonse JSON

{
  "phrase": {
    "id": 42,
    "parts": ["do", "not", "panic"],
    "status": "ACTIVE"
  }
}

14. Retrieve all Disallowed Phrases

Available since 3.10.0

This API retrieves all of the disallowed phrases at once.

14.1. Request

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist/disallowed-phrase

URI (4.x)

GET /api/filter/whitelist/disallowed-phrase

14.2. Response

Table 35. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 36. Response Body
phrases`[x]`.id [Integer]	The Id of the entry
phrases`[x]`.parts [Array<String>]	The parts that make up the disallowed phrase.
phrases`[x]`.status [String]	The status will always be `ACTIVE` as these APIs only operate on the active filter state.

Example Response JSON

{
  "phrases": [
    {
      "id": 42,
      "parts": ["do", "not", "panic"],
      "status": "ACTIVE"
    },
    {
      "id": 1337,
      "parts": ["do", "you", "even", "lift"],
      "status": "ACTIVE"
    }
  ]
}

15. Delete a Disallowed Phrase

Available since 3.10.0

15.1. Request

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist/disallowed-phrase/{id}

URI (4.x)

GET /api/filter/whitelist/disallowed-phrase/{id}

id [Integer] required

The id of the entry to delete.

15.2. Response

Table 37. Response Codes
Code	Description
200	The request was successful. The response will be empty.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
404	The object you are trying to delete doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

16. Create a Disallowed Phrase

Available since 3.10.0

16.1. Request

URI (3.x, deprecated in 4.0.0)

POST /filter/whitelist/disallowed-phrase

URI (4.x)

POST /api/filter/whitelist/disallowed-phrase

Table 38. Request Body
phrase.parts [Array<String>] required	The allowed words of a disallowed phrase to create. At least one is required and the allowed words must already exist.

Example Request JSON

{
  "phrase": {
    "parts": ["do", "not", "panic"]
  }
}

16.2. Response

Table 39. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 40. Response Body
phrase.id [Integer]	The Id of the phrase.
phrase.parts [Array<String>]	The associated allowed words for the phrase.
phrase.status [String]	The status of the phrase. This will always be `ACTIVE` as the APIs only operate on the active filter state.

Example Resonse JSON

{
  "phrase": {
    "id": 42,
    "parts": ["do", "not", "panic"],
    "status": "ACTIVE"
  }
}

17. Retrieve an Advanced Disallowed Phrase

Available since 3.10.0

17.1. Retrieve by Id

Retrieve a single advanced disallowed phrase by id.

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist/disallowed-phrase/advanced/{id}

URI (4.x)

GET /api/filter/whitelist/disallowed-phrase/advanced/{id}

Table 41. Request Parameters
id [Integer] required	The Id of the entry to retrieve.

17.2. Response

Table 42. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
404	The object you requested doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 43. Response Body
phrase.id [Integer]	The Id of the phrase.
phrase.parts [Array<String>]	The whitelist tags that make up the phrase.
phrase.status [String]	The status will always be `ACTIVE` as these APIs only operate on the active filter state.

Response Body Example JSON

{
  "phrase": {
    "id": 1,
    "parts": ["Drug-Verb", "Drug-Adjective"],
    "status": "ACTIVE"
  }
}

18. Retrieve all Advanced Disallowed Phrases

Available since 3.10.0

Retrieves all of the advanced disallowed phrases.

18.1. Request

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist/disallowed-phrase/advanced

URI (4.x)

GET /api/filter/whitelist/disallowed-phrase/advanced

18.2. Response

Table 44. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 45. Response Body
phrases`[x]`.id [Integer]	The Id of the phrase.
phrases`[x]`.parts [Array<String>]	The whitelist tags associated with the phrase.
phrases`[x]`.status [String]	The status will always be `ACTIVE` as these APIs only operate on the active filter state.

Example Response JSON

{
  "phrases": [
    {
      "id": 1,
      "parts": ["Drug-Verb", "Drug-Noun"],
      "status": "ACTIVE"
    },
    {
      "id": 2,
      "parts": ["Penis-Reference", "*", "Vagina-Reference"],
      "status": "ACTIVE"
    }
  ]
}

19. Delete an Advanced Disallowed Phrase

Available since 3.10.0

19.1. Request

URI (3.x, deprecated in 4.0.0)

GET /filter/whitelist/disallowed-phrase/advanced/{id}

URI (4.x)

GET /api/filter/whitelist/disallowed-phrase/advanced/{id}

19.2. Response

Table 46. Response Codes
Code	Description
200	The request was successful. The response will be empty.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
404	The object you are trying to delete doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

20. Create an Advanced Disallowed Phrase

Available since 3.10.0

20.1. Request

URI (3.x, deprecated in 4.0.0)

POST /filter/whitelist/disallowed-phrase/advanced

URI (4.x)

POST /api/filter/whitelist/disallowed-phrase/advanced

Table 47. Request Body
phrase.parts [Array<String>] required	The list of whitelist tags to create the phrase with. At least one is required and the whitelist tag must already exist.

Example Request JSON

{
  "phrase": {
    "parts": ["Drug-Verb", "Drug-Reference"]
  }
}

20.2. Response

Table 48. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 49. Response Body
phrase.id [Integer]	The Id of the phrase.
phrase.parts [Array<String>]	The whitelist tags that make up the phrase.
phrase.status [String]	The status will always be `ACTIVE` as these APIs only operate on the active filter state.

Response Body Example JSON

{
  "phrase": {
    "id": 1,
    "parts": ["Drug-Verb", "Drug-Adjective"],
    "status": "ACTIVE"
  }
}