Blacklist APIs

1. Overview

This page contains all of the APIs for managing Blacklist Dictionary Entries and Tags.

Blacklist APIs Available Since Version 3.8.0

The following APIs only operate on the active filter state. The active filter state includes all dictionary and Blacklist entries excluding pending modifications. Use the management interface to manage pending modifications. There is no approval process for the APIs and everything will be immediately added to the active filter state.

Dictionary Entries

Tags

Filter Entries

Phrases

Whitelist

2. Retrieve a Dictionary Entry

2.1. Retrieve by Id

Retrieve a dictionary entry by Id

URI

GET /filter/blacklist/dictionary/{id}

Table 1. Request Parameters

id [Integer] required

The unique Id of the dictionary entry to retrieve.

2.2. Retrieve by text and locale

Retrieve a dictionary entry by its unique text and locale

URI

GET /filter/blacklist/dictionary?text={text}&locale={locale}

Table 2. Request Parameters

locale [String] required

The locale of the dictionary entry to retrieve. See Locales.

text [String] required

The text of the dictionary entry to retrieve.

2.3. Response

Table 3. 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 4. Response Body

entry.id [Integer]

The Id of the dictionary entry.

entry.locale [String]

The locale of the dictionary entry text. See Locales.

entry.status [String]

The status of the dictionary entry. The status of an entry will always be ACTIVE.

entries[x].tags [Array<String>] Available since 3.12.0

A list of Blacklist Tags, used in a whitelist behavior during filtering.

During filtering, if a word is EXACTLY matched against a dictionary word and both it and your filter configuration have the tag then the match will be removed as if it didn’t find it.

entry.text [String]

The text value of a dictionary entry.

Example Response JSON
{
  "entry": {
    "id": 1,
    "locale": "en",
    "status": "ACTIVE",
    "tags": [ "whitelist" ],
    "text": "beer"
  }
}

3. Search for Dictionary Entries

3.1. Request

Use known attributes of entries to find a set of dictionary entries.

URI

GET /filter/blacklist/dictionary/search?startRow={startRow}&numberOfResults={numberOfResults}&locale={locale}&sort[0].field={field}&sort[0].order={order}

Table 5. Request Parameters

locale [String] Optional

The Locales you would like to filter your results to. More than one can be used by repeating the parameter.

numberOfResults [Integer] Optional Defaults to 20

The number of search results to return. Used for paginating through a large result set.

sort [Array] Optional Defaults to id and asc

An array of sort orders. Each sort order contains a field and order.

sort[x].field [String] Required

The name of the field to sort. This field is required when specifying a sort order. Available fields:

  • text

  • id

  • status

  • locale

sort[x].order [String] Optional Defaults to asc

The order to sort the specified field. Possible values are:

  • asc - Ascending

  • desc - Descending.

startRow [Integer] Optional Defaults to 0

The start row within the search results to return. Used for paginating through a large result set.

3.2. Response

Table 6. 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 7. Response Body

totalResults [Integer] Available since 3.8.1

How many total results are available.

entries[x].id [Integer]

The unique Id of the dictionary entry.

entries[x].locale [String]

The locale of the dictionary entry text. See Locales.

entries[x].status [String]

The status of the dictionary entry. The status will always be ACTIVE.

entries[x].tags [Array<String>] Available since 3.12.0

A list of Blacklist Tags, used in a whitelist behavior during filtering.

During filtering, if a word is EXACTLY matched against a dictionary word and both it and your filter configuration have the tag then the match will be removed as if it didn’t find it.

entries[x].text [String]

The text value of a dictionary entry.

Example Response JSON
{
  "totalResults": 3,
  "entries": [
    {
      "id": 1,
      "locale": "en",
      "status": "ACTIVE",
      "text": "hi"
    },
    {
      "id": 2,
      "locale": "en_CA",
      "status": "ACTIVE",
      "text": "ey"
    },
    {
      "id": 3,
      "locale": "en_GB",
      "status": "ACTIVE",
      "tags": [ "whitelist" ],
      "text": "oi"
    }
  ]
}

4. Create a Dictionary Entry

This API is used to create dictionary entries. Creating a dictionary entry using this API bypasses the approval process.

4.1. Request

URI

POST /filter/blacklist/dictionary

Table 8. Request Body

entry.locale [String] required

The locale of the dictionary entry text. See Locales.

tags [Array<String>] Available since 3.12.0

A list of Blacklist Tags, used in a whitelist behavior during filtering.

During filtering, if a word is EXACTLY matched against a dictionary word and both it and your filter configuration have the tag then the match will be removed as if it didn’t find it.

entry.text [String] required

The text value of the dictionary entry.

Example Request JSON
{
  "entry": {
    "locale": "en",
    "tags": [ "whitelist" ],
    "text": "beer"
  }
}

4.2. Response

Table 9. 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 10. Response Body

entry.id [Integer]

The Id of the dictionary entry.

entry.locale [String]

The locale of the dictionary entry text. See Locales.

entry.status [String]

The status of the dictionary entry. The status of an entry will always be ACTIVE.

entries[x].tags [Array<String>] Available since 3.12.0

A list of Blacklist Tags, used in a whitelist behavior during filtering.

During filtering, if a word is EXACTLY matched against a dictionary word and both it and your filter configuration have the tag then the match will be removed as if it didn’t find it.

entry.text [String]

The text value of a dictionary entry.

Example Response JSON
{
  "entry": {
    "id": 1,
    "locale": "en",
    "status": "ACTIVE",
    "tags": [ "whitelist" ],
    "text": "beer"
  }
}

5. Update a Dictionary Entry

This API is used to update dictionary entries. This will bypass the approval process.

Available since 3.12.0

5.1. Request

URI

PUT /filter/blacklist/dictionary/{id}

Table 11. Request Parameters

id [Integer] required

The unique Id of the dictionary entry to update.

Table 12. Request Body

entry.locale [String] required

The locale of the dictionary entry text. See Locales.

tags [Array<String>] Available since 3.12.0

A list of Blacklist Tags, used in a whitelist behavior during filtering.

During filtering, if a word is EXACTLY matched against a dictionary word and both it and your filter configuration have the tag then the match will be removed as if it didn’t find it.

entry.text [String] required

The text value of the dictionary entry.

Example Request JSON
{
  "entry": {
    "locale": "en",
    "tags": [ "whitelist" ],
    "text": "beer"
  }
}

6. Delete a Dictionary Entry

Allows you to delete a dictionary entry by Id. Deleting a dictionary entry using this API bypasses the approval process.

URI

DELETE /filter/blacklist/dictionary/{id}

6.1. Request

Table 13. Request Parameters

id [Integer] required

The unique Id of the dictionary 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. Bulk Delete Dictionary Entries by Locale

This API is potentially catastrophically destructive and cannot be undone. Use this API with care.

This API has been available since 3.11.0

7.1. Request

URI

DELETE /filter/blacklist/dictionary/bulk?locale={locale}

This request deletes ALL Dictionary Entries of a given locale.

locale [String] required

The locale to delete.

7.2. Response

Table 15. 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.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

8. Retrieve a Tag

8.1. Retrieve by Id

URI

GET /filter/blacklist/tag/{id}

Table 16. Request Parameters

id [Integer] required

The Id of the tag to retrieve.

8.2. Retrieve by name

URI

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

Table 17. Request Parameters

name [String] required

The name of the tag to retrieve.

8.3. Response

Table 18. 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 19. Response Body

tag.id [Integer]

The unique Id of the tag.

tag.name [String]

The name of the tag.

Example Response JSON
{
  "tag": {
    "id": 1,
    "name": "Vulgarity"
  }
}

9. Retrieve all Tags

9.1. Request

URI

GET /filter/blacklist/tag

9.2. Response

Table 20. 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 21. Response Body

tag[x].id [Integer]

The unique Id of the tag.

tag[x].name [String]

The value of the tag.

Example Response JSON
{
  "tags": [
    {
      "id": 1,
      "name": "Vulgarity"
    },
    {
      "id": 2,
      "name": "Sexual"
    }
  ]
}

10. Create a Tag

URI

POST /filter/blacklist/tag

10.1. Request

Table 22. Request Body

tag.name [String] required

The unique name of the tag.

Example Request JSON
{
  "tag": {
    "name": "Vulgarity"
  }
}

10.2. Response

Table 23. 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 24. Response Body

tag.id [Integer]

The unique Id of the tag.

tag.name [String]

The name of the tag.

Example Response JSON
{
  "tag": {
    "id": 1,
    "name": "Vulgarity"
  }
}

11. Delete a Tag

URI

DELETE /filter/blacklist/tag/{id}

Table 25. Request Parameters

id [Integer] required

The Id of the tag to delete.

11.1. Response

Table 26. Response Codes
Code Description

200

The request was successful. The response will be empty.

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. Retrieve a Filter Entry

Available since 3.9.0

12.1. Retrieve by Id

URI

GET /filter/blacklist/entry/{id}

Table 27. Request Parameters

id [Integer] required

The Id of the entry to retrieve.

12.2. Retrieve by text and locale

URI

GET /filter/blacklist/entry?text={text}&locale={locale}

Table 28. Request Parameters

locale [String] required

The locale of the entry to retrieve. See Locale.

text [String] required

The text of the entry to retrieve.

12.3. Response

Table 29. 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 30. Response Body

entry.adjective [Boolean]

A flag to mark if the entry can be used as an adjective.

entry.adverb [Boolean]

A flag to mark if the entry can be used as an adverb.

entry.collapseDoubles [Boolean]

A flag to mark if the filter should collapse doubles. (Ex dd, dd. - except vowels)

entry.definition [String]

A dictionary style definition of the entry text.

entry.filterMode [String]

A string describing the filter mode this entry is using. Possible values:

  • exactMatch

  • embeddable

  • nonEmbeddable

  • distinguishable

See Filter Mode for details.

entry.id [Integer]

The unique Id of the entry.

entry.ignores [Array<String>]

A list of ignores for the entry.

entry.locale [String]

The locale of the entry. See Locale.

entry.noun [Boolean]

A flag to determine if the entry can be used as a noun.

entry.replacePhonetics [Boolean]

A flag informing the filter if it should try phonetic replacements to match this entry.

entry.severity [String]

A string representing the associated severity of the words usage. Possible values are:

  • mild - The entry is generally not offensive in most situations

  • medium - The entry is sometimes offensive but generally okay to use in professional situations.

  • high - The entry is always offensive but sometimes still used in professional situations.

  • severe - The entry is always offensive and never used in professional situations.

entry.status [String]

A string representing the approval status of the entry. This will always be ACTIVE because these APIs only operate on the active filter state.

entry.tags [Array<String>]

A list of associated blacklist tags.

entry.text [String]

The entry text/word.

entry.variations [Array<String>]

A list of possible variations of the entry text.

entry.verb [Boolean]

A flag to tell the filter if this entry can be used as a verb.

Example Response JSON
{
  "entry": {
    "adjective": false,
    "adverb": false,
    "collapseDoubles": true,
    "filterMode": "embeddable",
    "id": 1337,
    "locale": "en",
    "noun": false,
    "replacePhonetics": true,
    "severity": "medium",
    "status": "ACTIVE",
    "tags": [
      "Grooming"
    ],
    "text": "your mom",
    "variations": [
      "ur dad",
      "ur mom",
      "your dad"
    ],
    "verb": false
  }
}

13. Search for Filter Entries

Available since 3.9.0

13.1. Request

URI

GET /filter/blacklist/entry/search?text={text}&startRow={startRow}&numberOfResults={numberOfResults}

Not all parameters are shown in this URI, see the table below for the full list.

Table 31. Request Parameters

adjective [Boolean] Optional

Allow/Restrict adjective results. If true, only adjectives will be returned, if false only non adjectives will be returned, and if absent both will be returned.

adverb [Boolean] Optional

Allow/Restrict adverb results. If true, only adverbs will be returned, if false only non adverbs will be returned, and if absent both will be returned.

collapseDoubles [Boolean] Optional

Allow/Restrict collapseDoubles results. If true, only collapseDoubless will be returned, if false only non collapseDoubless will be returned, and if absent both will be returned.

filterMode [String] Optional

If supplied, restricts results to the filterModes provided. This parameter can be supplied more than once. Available Options:

  • exactMatch

  • embeddable

  • nonEmbeddable

  • distinguishable

See Filter Mode for details.

locale [String] Optional

If supplied, restricts results to the locales provided. This parameter can be supplied more than once. See Locale.

noun [Boolean] Optional

Allow/Restrict noun results. If true, only nouns will be returned, if false only non nouns will be returned, and if absent both will be returned.

numberOfResults [Integer] Optional Defaults to 20

Sets how many results to return. Must be equal to or greater than 1.

repalcePhonetics [Boolean] Optional

Allow/Restrict repalcePhonetics results. If true, only repalcePhoneticss will be returned, if false only non repalcePhoneticss will be returned, and if absent both will be returned.

severity [String] Optional

If supplied, restricts results to the severity provided. This parameter can be supplied more than once. Available options:

  • mild - The entry is generally not offensive in most situations

  • medium - The entry is sometimes offensive but generally okay to use in professional situations.

  • high - The entry is always offensive but sometimes still used in professional situations.

  • severe - The entry is always offensive and never used in professional situations.

startRow [Integer] Optional Defaults to 0

Sets the beginning row to return in the results. Must be equal to or greater than 0.

tag [String] Optional

If supplied, restricts results to the tag provided. This parameter can be supplied more than once. Note: The tag MUST exist or call will fail.

text [String] Optional

Used for flexible searching on the text value of an entry. Use * for wildcards.

verb [Boolean] Optional

Allow/Restrict verb results. If true, only verbs will be returned, if false only non verbs will be returned, and if absent both will be returned.

13.2. Response

Table 32. 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 33. Response Body

entries[x].adjective [Boolean]

A flag to mark if the entry can be used as an adjective.

entries[x].adverb [Boolean]

A flag to mark if the entry can be used as an adverb.

entries[x].collapseDoubles [Boolean]

A flag to mark if the filter should collapse doubles. (Ex dd, dd. - except vowels)

entries[x].definition [String]

A dictionary style definition of the entry text.

entries[x].filterMode [String]

A string describing the filter mode this entry is using. Possible values:

  • exactMatch

  • embeddable

  • nonEmbeddable

  • distinguishable

See Filter Mode for details.

entries[x].id [Integer]

The unique Id of the entry.

entries[x].ignores [Array<String>]

A list of ignores for the entry.

entries[x].locale [String]

The locale of the entry. See Locale.

entries[x].noun [Boolean]

A flag to determine if the entry can be used as a noun.

entries[x].replacePhonetics [Boolean]

A flag informing the filter if it should try phonetic replacements to match this entry.

entries[x].severity [String]

A string representing the associated severity of the words usage. Possible values are:

  • mild - The entry is generally not offensive in most situations

  • medium - The entry is sometimes offensive but generally okay to use in professional situations.

  • high - The entry is always offensive but sometimes still used in professional situations.

  • severe - The entry is always offensive and never used in professional situations.

entries[x].status [String]

A string representing the approval status of the entry. This will always be ACTIVE because these APIs only operate on the active filter state.

entries[x].tags [Array<String>]

A list of associated blacklist tags.

entries[x].text [String]

The entry text/word.

entries[x].variations [Array<String>]

A list of possible variations of the entry text.

entries[x].verb [Boolean]

A flag to tell the filter if this entry can be used as a verb.

Example Response JSON
{
  "entries": [
    {
      "adjective":false,
      "adverb":false,
      "collapseDoubles":true,
      "filterMode":"embeddable",
      "id": 1,
      "locale":"en",
      "noun":false,
      "replacePhonetics":true,
      "severity":"medium",
      "status": "ACTIVE",
      "tags":[
        "Grooming"
      ],
      "text":"your mom",
      "variations":[
        "ur dad",
        "ur mom",
        "your dad"
      ],
      "verb":false
    },
    {
      "adjective":false,
      "adverb":false,
      "collapseDoubles":true,
      "definition":"slang for marijuana",
      "filterMode":"embeddable",
      "id": 2,
      "locale":"en",
      "noun":true,
      "replacePhonetics":true,
      "severity":"medium",
      "status": "ACTIVE",
      "tags":[
        "Alcohol-Drug"
      ],
      "text":"splif",
      "verb":false
    },
    {
      "adjective":true,
      "adverb":false,
      "collapseDoubles":true,
      "definition":"A woman who sleeps with lots of people, male or female or both.",
      "filterMode":"embeddable",
      "id": 3,
      "locale":"en",
      "noun":true,
      "replacePhonetics":true,
      "severity":"medium",
      "status": "ACTIVE",
      "tags":[
        "Vulgarity"
      ],
      "text":"slut",
      "variations":[
        "slutee",
        "sluty"
      ],
      "verb":false
    }
  ],
  "totalResults": 3
}

14. Create a Filter Entry

Available since 3.9.0

14.1. Request

URI

POST /filter/blacklist/entry

Table 34. Request Body

entry.adjective [Boolean] Optional defaults to false

A flag to mark if the entry can be used as an adjective.

entry.adverb [Boolean] Optional defaults to false

A flag to mark if the entry can be used as an adverb.

entry.collapseDoubles [Boolean] Optional defaults to false

A flag to mark if the filter should collapse doubles. (Ex dd, dd. - except vowels)

entry.definition [String] Optional

A dictionary style definition of the entry text.

entry.filterMode [String] required

A string describing the filter mode this entry is using. Possible values:

  • exactMatch

  • embeddable

  • nonEmbeddable

  • distinguishable

See Filter Mode for details.

entry.ignores [Array<String>] Optional

A list of ignores for the entry.

entry.locale [String] required

The locale of the entry. See Locale.

entry.noun [Boolean] Optional defaults to false

A flag to determine if the entry can be used as a noun.

entry.replacePhonetics [Boolean] Optional defaults to false

A flag informing the filter if it should try phonetic replacements to match this entry.

entry.severity [String] required

A string representing the associated severity of the words usage. Possible values are:

  • mild - The entry is generally not offensive in most situations

  • medium - The entry is sometimes offensive but generally okay to use in professional situations.

  • high - The entry is always offensive but sometimes still used in professional situations.

  • severe - The entry is always offensive and never used in professional situations.

entry.text [String] required

The entry text/word.

entry.verb [Boolean] Optional defaults to false

A flag to tell the filter if this entry can be used as a verb.

entry.variations [Array<String>] Optional

A list of possible variations of the entry text.

entry.tags [Array<String>] required

A list of associated blacklist tags. If a tag does not already exist, it will be created with the same locale as the entry. At least one tag must be supplied.

Request Body Example JSON
{
  "entry": {
    "adjective": false,
    "adverb": false,
    "collapseDoubles": true,
    "filterMode": "embeddable",
    "locale": "en",
    "noun": false,
    "replacePhonetics": true,
    "severity": "medium",
    "tags": [
      "Grooming"
    ],
    "text": "your mom",
    "variations": [
      "ur dad",
      "ur mom",
      "your dad"
    ],
    "verb": false
  }
}

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

entry.adjective [Boolean]

A flag to mark if the entry can be used as an adjective.

entry.adverb [Boolean]

A flag to mark if the entry can be used as an adverb.

entry.collapseDoubles [Boolean]

A flag to mark if the filter should collapse doubles. (Ex dd, dd. - except vowels)

entry.definition [String]

A dictionary style definition of the entry text.

entry.filterMode [String]

A string describing the filter mode this entry is using. Possible values:

  • exactMatch

  • embeddable

  • nonEmbeddable

  • distinguishable

See Filter Mode for details.

entry.id [Integer]

The unique Id of the entry.

entry.ignores [Array<String>]

A list of ignores for the entry.

entry.locale [String]

The locale of the entry. See Locale.

entry.noun [Boolean]

A flag to determine if the entry can be used as a noun.

entry.replacePhonetics [Boolean]

A flag informing the filter if it should try phonetic replacements to match this entry.

entry.severity [String]

A string representing the associated severity of the words usage. Possible values are:

  • mild - The entry is generally not offensive in most situations

  • medium - The entry is sometimes offensive but generally okay to use in professional situations.

  • high - The entry is always offensive but sometimes still used in professional situations.

  • severe - The entry is always offensive and never used in professional situations.

entry.status [String]

A string representing the approval status of the entry. This will always be ACTIVE because these APIs only operate on the active filter state.

entry.tags [Array<String>]

A list of associated blacklist tags.

entry.text [String]

The entry text/word.

entry.variations [Array<String>]

A list of possible variations of the entry text.

entry.verb [Boolean]

A flag to tell the filter if this entry can be used as a verb.

Example Response JSON
{
  "entry": {
    "adjective": false,
    "adverb": false,
    "collapseDoubles": true,
    "filterMode": "embeddable",
    "id": 1337,
    "locale": "en",
    "noun": false,
    "replacePhonetics": true,
    "severity": "medium",
    "status": "ACTIVE",
    "tags": [
      "Grooming"
    ],
    "text": "your mom",
    "variations": [
      "ur dad",
      "ur mom",
      "your dad"
    ],
    "verb": false
  }
}

15. Delete a Filter Entry

Available since 3.9.0

15.1. Request

URI

DELETE /filter/blacklist/entry/{id}

Table 37. Request Parameters

id [Integer] required

The Od of the entry to delete.

15.2. Response

Table 38. 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. Bulk Delete Filter Entries by Locale

This api is potentially catastrophically destructive and cannot be undone. Use care with this API.

This API has been available since 3.11.0

16.1. Request

URI

DELETE /filter/blacklist/entry/bulk?locale={locale}

This request deletes ALL Filter Entries of a given locale.

locale [String] required

The locale to delete.

16.2. Response

Table 39. 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.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

17. Update a Filter Entry

Available since 3.9.0

17.1. Request

URI

PUT /filter/blacklist/entry/{id}

Table 40. Request Paramters

id [Integer] required

The Id of the entry to modify.

Table 41. Request Body

entry.adjective [Boolean] Optional defaults to false

A flag to mark if the entry can be used as an adjective.

entry.adverb [Boolean] Optional defaults to false

A flag to mark if the entry can be used as an adverb.

entry.collapseDoubles [Boolean] Optional defaults to false

A flag to mark if the filter should collapse doubles. (Ex dd, dd. - except vowels)

entry.definition [String] Optional

A dictionary style definition of the entry text.

entry.filterMode [String] required

A string describing the filter mode this entry is using. Possible values:

  • exactMatch

  • embeddable

  • nonEmbeddable

  • distinguishable

See Filter Mode for details.

entry.ignores [Array<String>] Optional

A list of ignores for the entry.

entry.locale [String] required

The locale of the entry. See Locale.

entry.noun [Boolean] Optional defaults to false

A flag to determine if the entry can be used as a noun.

entry.replacePhonetics [Boolean] Optional defaults to false

A flag informing the filter if it should try phonetic replacements to match this entry.

entry.severity [String] required

A string representing the associated severity of the words usage. Possible values are:

  • mild - The entry is generally not offensive in most situations

  • medium - The entry is sometimes offensive but generally okay to use in professional situations.

  • high - The entry is always offensive but sometimes still used in professional situations.

  • severe - The entry is always offensive and never used in professional situations.

entry.text [String] required

The entry text/word.

entry.verb [Boolean] Optional defaults to false

A flag to tell the filter if this entry can be used as a verb.

entry.variations [Array<String>] Optional

A list of possible variations of the entry text.

entry.tags [Array<String>] required

A list of associated blacklist tags. If a tag does not already exist, it will be created with the same locale as the entry. At least one tag must be supplied.

Request Body Example JSON
{
  "entry": {
    "adjective": false,
    "adverb": false,
    "collapseDoubles": true,
    "filterMode": "embeddable",
    "locale": "en",
    "noun": false,
    "replacePhonetics": true,
    "severity": "medium",
    "tags": [
      "Grooming"
    ],
    "text": "your mom",
    "variations": [
      "ur dad",
      "ur mom",
      "your dad"
    ],
    "verb": false
  }
}

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 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 43. Response Body

entry.adjective [Boolean]

A flag to mark if the entry can be used as an adjective.

entry.adverb [Boolean]

A flag to mark if the entry can be used as an adverb.

entry.collapseDoubles [Boolean]

A flag to mark if the filter should collapse doubles. (Ex dd, dd. - except vowels)

entry.definition [String]

A dictionary style definition of the entry text.

entry.filterMode [String]

A string describing the filter mode this entry is using. Possible values:

  • exactMatch

  • embeddable

  • nonEmbeddable

  • distinguishable

See Filter Mode for details.

entry.id [Integer]

The unique Id of the entry.

entry.ignores [Array<String>]

A list of ignores for the entry.

entry.locale [String]

The locale of the entry. See Locale.

entry.noun [Boolean]

A flag to determine if the entry can be used as a noun.

entry.replacePhonetics [Boolean]

A flag informing the filter if it should try phonetic replacements to match this entry.

entry.severity [String]

A string representing the associated severity of the words usage. Possible values are:

  • mild - The entry is generally not offensive in most situations

  • medium - The entry is sometimes offensive but generally okay to use in professional situations.

  • high - The entry is always offensive but sometimes still used in professional situations.

  • severe - The entry is always offensive and never used in professional situations.

entry.status [String]

A string representing the approval status of the entry. This will always be ACTIVE because these APIs only operate on the active filter state.

entry.tags [Array<String>]

A list of associated blacklist tags.

entry.text [String]

The entry text/word.

entry.variations [Array<String>]

A list of possible variations of the entry text.

entry.verb [Boolean]

A flag to tell the filter if this entry can be used as a verb.

Example Response JSON
{
  "entry": {
    "adjective": false,
    "adverb": false,
    "collapseDoubles": true,
    "filterMode": "embeddable",
    "id": 1337,
    "locale": "en",
    "noun": false,
    "replacePhonetics": true,
    "severity": "medium",
    "status": "ACTIVE",
    "tags": [
      "Grooming"
    ],
    "text": "your mom",
    "variations": [
      "ur dad",
      "ur mom",
      "your dad"
    ],
    "verb": false
  }
}

18. Retrieve a Phrase

Available since 3.18.0

18.1. Retrieve by Id

URI

GET /filter/blacklist/phrase/{id}

Table 44. Request Parameters

id [Integer] required

The Id of the phrase to retrieve.

18.2. Response

Table 45. 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 46. Response Body

phrase.id [Integer]

The Id of the phrase.

phrases.locale [String]

The locale of the phrase. See Locales.

phrases.pattern [String]

A regex pattern that can optionally include blacklist tags to match on blacklist entry matches. Tags are of the form %TagName% in a regex.

phrase.severity [String]

The severity of the phrase. A severity can be any of the following:

  • mild

  • medium

  • high

  • severe

phrase.status [String]

The status of the phrase in the filter. The API always returns ACTIVE entries as the APIs only operate on the active filter state.

phrases.tags [Array<String>]

A list of blacklist tag names that this phrase should be associated to.

Example Response JSON
{
  "phrase": {
    "id": 1,
    "locale": "en",
    "parts": "%Purchase%.+%Company%",
    "severity": "mild",
    "status": "ACTIVE",
    "tags": [ "Phrase" ]
  }
}

18.3. Retrieve all Phrases

URI

GET /filter/blacklist/phrase

18.4. Response

Table 47. 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.

phrases[x].id [Integer]

The Id of the phrase.

phrases[x].locale [String]

The locale of the phrase. See Locales.

phrases[x].pattern [String]

A regex pattern that can optionally include blacklist tags to match on blacklist entry matches. Tags are of the form %TagName% in a regex.

phrases[x].severity [String]

The severity of the phrase. A severity can be any of the following:

  • mild

  • medium

  • high

  • severe

phrases[x].status [String]

The status of the phrase. The status will always be ACTIVE as the APIs only operate on the active filter state.

phrases[x].tags [Array<String>]

A list of blacklist tag names that this phrase should be associated to.

Example Response JSON
{
  "phrases": [
    {
      "id": 1,
      "locale": "en",
      "pattern": "%Purchase%.+%Company%",
      "severity": "mild",
      "status": "ACTIVE",
      "tags": [ "Phrase" ]
    },
    {
      "id": 2,
      "locale": "en",
      "pattern": "%Purchase%.+%Social-Like%\\s+%Company%",
      "severity": "mild",
      "status": "ACTIVE",
      "tags": [ "Phrase" ]
    }
  ]
}

19. Create a Phrase

Available since 3.18.0

19.1. Request

URI

POST /filter/blacklist/phrase

Example Request JSON
{
  "phrase": {
    "locale": "en",
    "pattern": "%Purchase%.+%Company%",
    "severity": "mild",
    "tags": [ "Phrase" ]
  }
}
Table 48. Request Body

phrase.locale [String] required

The locale of the pattern/phrase. See Locales.

phrase.pattern [String] requried

A regex pattern that can optionally include blacklist tags to match on blacklist entry matches. Tags are of the form %TagName% in a regex.

phrase.severity [String] required

The severity of the phrase. A severity can be any of the following:

  • mild

  • medium

  • high

  • severe

phrases.tags [Array<String>] required

A list of blacklist tag names that this phrase should be associated to. At least one tag is required.

19.2. Response

Table 49. 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 50. Response Body

phrase.id [Integer]

The Id of the phrase.

phrases.locale [String]

The locale of the phrase. See Locales.

phrases.pattern [String]

A regex pattern that can optionally include blacklist tags to match on blacklist entry matches. Tags are of the form %TagName% in a regex.

phrase.severity [String]

The severity of the phrase. A severity can be any of the following:

  • mild

  • medium

  • high

  • severe

phrase.status [String]

The status of the phrase in the filter. The API always returns ACTIVE entries as the APIs only operate on the active filter state.

phrases.tags [Array<String>]

A list of blacklist tag names that this phrase should be associated to.

Example Response JSON
{
  "phrase": {
    "id": 1,
    "locale": "en",
    "parts": "%Purchase%.+%Company%",
    "severity": "mild",
    "status": "ACTIVE",
    "tags": [ "Phrase" ]
  }
}

20. Update a Phrase

Available since 3.18.0

20.1. Request

URI

PUT /filter/blacklist/phrase/{id}

Table 51. Request Parameters

id [Integer] required

The unique Id of the phrase to update.

Example Request JSON
{
  "phrase": {
    "locale": "en",
    "pattern": "%Purchase%.+%Company%",
    "severity": "mild",
    "tags": [ "Phrase" ]
  }
}
Table 52. Request Body

phrase.locale [String] required

The locale of the pattern/phrase. See Locales.

phrase.pattern [String] requried

A regex pattern that can optionally include blacklist tags to match on blacklist entry matches. Tags are of the form %TagName% in a regex.

phrase.severity [String] required

The severity of the phrase. A severity can be any of the following:

  • mild

  • medium

  • high

  • severe

phrases.tags [Array<String>] required

A list of blacklist tag names that this phrase should be associated to. At least one tag is required.

20.2. Response

Table 53. 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 54. Response Body

phrase.id [Integer]

The Id of the phrase.

phrases.locale [String]

The locale of the phrase. See Locales.

phrases.pattern [String]

A regex pattern that can optionally include blacklist tags to match on blacklist entry matches. Tags are of the form %TagName% in a regex.

phrase.severity [String]

The severity of the phrase. A severity can be any of the following:

  • mild

  • medium

  • high

  • severe

phrase.status [String]

The status of the phrase in the filter. The API always returns ACTIVE entries as the APIs only operate on the active filter state.

phrases.tags [Array<String>]

A list of blacklist tag names that this phrase should be associated to.

Example Response JSON
{
  "phrase": {
    "id": 1,
    "locale": "en",
    "parts": "%Purchase%.+%Company%",
    "severity": "mild",
    "status": "ACTIVE",
    "tags": [ "Phrase" ]
  }
}

21. Delete a Phrase

Available since 3.18.0

21.1. Request

URI

DELETE /filter/blacklist/phrase/{id}

Table 55. Request Parameters

id [Integer] required

The Id of the phrase to delete.

21.2. Response

Table 56. 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.

22. Retrieve a Whitelist Entry

Available since 3.23.0

22.1. Request

URI

GET /filter/blacklist/whitelist/{id}

id [Integer] required

The Id of the entry to retrieve.

22.2. Response

Table 57. 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 58. Response Body

entry.id [Integer]

The Id of the entry

entry.pattern [String]

A regular expression that defines text that should never contain blacklist matches.

entry.status [String]

Always will be ACTIVE.

Example Response JSON
{
  "entry": {
    "pattern": "example"
  }
}

23. Retrieve all Whitelist Entries

23.1. Request

URI

GET /filter/blacklist/whitelist/

23.2. Response

Table 59. 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 60. Response Body

entries[x].id [Integer]

The Id of the entry

entries[x].pattern [String]

A regular expression that defines text that should never contain blacklist matches.

entries[x].status [String]

Always will be ACTIVE.

Example Response JSON
{
  "entries": [
    {
      "id": 42,
      "pattern": "example",
      "status": "ACTIVE"
    },
    {
      "id": 43,
      "pattern": "Time: \\d{2}:\\d{2}",
      "status": "ACTIVE"
    }
  ]
}

24. Create a Whitelist Entry

24.1. Request

URI

POST /filter/blacklist/whitelist/

Table 61. Response Body

entry.pattern [String]

A regular expression that defines text that should never contain blacklist matches.

Example Response JSON
{
  "entry": {
    "pattern": "example"
  }
}

24.2. Response

Table 62. 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 63. Response Body

entry.id [Integer]

The Id of the entry

entry.pattern [String]

A regular expression that defines text that should never contain blacklist matches.

entry.status [String]

Always will be ACTIVE.

Example Response JSON
{
  "entry": {
    "pattern": "example"
  }
}

25. Update a Whitelist Entry

25.1. Request

URI

PUT /filter/blacklist/whitelist/{id}

id [Integer] required

The Id of the entry to update.

Table 64. Response Body

entry.pattern [String]

A regular expression that defines text that should never contain blacklist matches.

Example Response JSON
{
  "entry": {
    "pattern": "example"
  }
}

25.2. Response

Table 65. 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 66. Response Body

entry.id [Integer]

The Id of the entry

entry.pattern [String]

A regular expression that defines text that should never contain blacklist matches.

entry.status [String]

Always will be ACTIVE.

Example Response JSON
{
  "entry": {
    "pattern": "example"
  }
}

26. Delete a Whitelist Entry

26.1. Request

URI

DELETE /filter/blacklist/whitelist/{id}

id [Integer] required

The Id of the entry to delete.

26.2. Response

Table 67. 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.