Skip to main content

Custom Mappings

Custom Mappings can be used to enforce specific corrections or capitalization for the following purposes:

  • Brand voice: Ensure that a consistent, on-brand style is used in all outward communication.
  • Compliance: If there is a specific way to communicate an issue, or if certain terms should be flagged, custom mappings can help.
  • Other use cases: Company or industry-specific jargon, product names, or unusual capitalization.

Custom Mapping GET​

Request Parameters​

import requests

key = '<api-key>'

url = f'https://api.sapling.ai/api/v1/custom_mapping?key={key}'

try:
    resp = requests.get(url)
    if 200 <= resp.status_code < 300:
        resp_json = resp.json()
        print('Custom mapping: ', resp_json)
    else:
        print('Error: ', str(resp.status_code), resp.text)
except Exception as e:
    print('Error: ', e)

https://api.sapling.ai/api/v1/custom_mapping?key=<key>

HTTP method: GET

<key>: String
32-character API key. Can also be supplied via the Authorization header as a bearer token; if both are provided, the key parameter takes precedence.

Response Parameters​

JSON array of custom mapping entries under key custom_mappings.

Custom mapping entry structure:

{
  "id": <str, UUID>,          // Opaque id, used for deletion
  "entry": <str>,             // Word to match
  "mapping": <str>,           // Word to suggest as replacement
  "description": <str|null>,  // Shown with the suggestion; "" or null when none
  "case_sensitive": <bool>    // true or false
  "created_at": <str, date>   // e.g. "Wed, 07 Oct 2020 21:15:47 GMT"
  "updated_at": <str, date>   // e.g. "Wed, 07 Oct 2020 21:15:47 GMT"
}

Custom Mapping POST​

Request Parameters​

import requests

key = '<api-key>'

url = 'https://api.sapling.ai/api/v1/custom_mapping'
data = {
    'key': key,
    'entry': 'foobazbar',
    'mapping': 'foobarbaz',
    'case_sensitive': False,
}

try:
    resp = requests.post(url, json=data)
    if 200 <= resp.status_code < 300:
        resp_json = resp.json()
        print('Entry: ', str(resp_json))
    else:
        print('Error: ', str(resp.status_code), resp.text)
except Exception as e:
    print('Error: ', e)

https://api.sapling.ai/api/v1/custom_mapping

HTTP method: POST

key: String
32-character API key. Can also be supplied via the Authorization header as a bearer token; if both are provided, the key parameter takes precedence.

entry: String
Word to match.

There are currently a couple types of regular expression-like options:

  • ^ and $ match the start and end of a sentence, respectively. Example: ^the will only match the at the start of a sentence and can be used to enforce capitalization.
  • # will match a number; example: Gate # will match in Boarding is at Gate 5.

mapping: String
Word to suggest for a match.

You can use # in the resulting expression to substitute a number back in.

case_sensitive: Boolean
Whether match is case-sensitive or not. If not case-sensitive, lower case and title case will both match. Defaults to true.

description: Optional String
The description will be shown when the edit is suggested to the end user. If a description field is specified, the user will not have the option to ignore the edit.

Response Parameters​

JSON, Created Custom Mapping Entry Custom Mapping Entry Structure:

{
  "id": <str, UUID>,        // Opaque id, used for deletion
  "entry": <str>,           // Word to match
  "mapping": <str>,         // Word to suggest as replacement
  "description": <str|null>, // Shown with the suggestion; "" or null when none
  "case_sensitive": <bool>  // true or false
  "created_at": <str, date> // e.g. "Wed, 07 Oct 2020 21:15:47 GMT"
  "updated_at": <str, date> // e.g. "Wed, 07 Oct 2020 21:15:47 GMT"
}

Errors​

The API answers 400, with the reason in msg, when:

  • the account already has a mapping for entry (Entry already exists.)
  • entry and mapping are the same
  • entry contains more than two digits
  • case_sensitive is false but entry and mapping differ only in case, e.g. iphone → iPhone. Such a rule must be case-sensitive.

Custom Mapping DELETE​

Request Parameters​

import requests

key = '<api-key>'
entry_id = '<CUSTOM_MAPPING_ID>'

url = f'https://api.sapling.ai/api/v1/custom_mapping/{entry_id}'
data = {
    'key': key,
}

try:
    resp = requests.delete(url, json=data)
    if 200 <= resp.status_code < 300:
        print('Success')
    else:
        print('Error: ', str(resp.status_code), resp.text)
except Exception as e:
    print('Error: ', e)

https://api.sapling.ai/api/v1/custom_mapping/<custom_mapping_id>

HTTP method: DELETE

<custom_mapping_id>: String (UUID)
ID of custom mapping.

key: String
32-character API key. Can also be supplied via the Authorization header as a bearer token; if both are provided, the key parameter takes precedence.

Response Parameters​

Empty, HTTP status code 204.

Custom Filters

Custom Filters allow you to ignore specific edits that match defined patterns during the editing process. This is useful for suppressing certain types of corrections that you don't want to see suggested.

Custom Filter GET​

Request Parameters​

import requests

key = '<api-key>'

url = f'https://api.sapling.ai/api/v1/custom_filter?key={key}'

try:
    resp = requests.get(url)
    if 200 <= resp.status_code < 300:
        resp_json = resp.json()
        print('Custom filters: ', resp_json)
    else:
        print('Error: ', str(resp.status_code), resp.text)
except Exception as e:
    print('Error: ', e)

https://api.sapling.ai/api/v1/custom_filter?key=<key>

HTTP method: GET

<key>: String
32-character API key. Can also be supplied via the Authorization header as a bearer token; if both are provided, the key parameter takes precedence.

Response Parameters​

JSON array of custom filter entries under key custom_filters.

Custom filter entry structure:

{
  "id": <str, UUID>,          // Opaque id, used for deletion
  "created_at": <str, date>,  // e.g. "Wed, 07 Oct 2020 21:15:47 GMT"
  "updated_at": <str, date>,  // e.g. "Wed, 07 Oct 2020 21:15:47 GMT"
  "input": <str>,             // Input text to match (can be empty string for wildcards)
  "output": <str>,            // Output text to match (can be empty string for wildcards)
  "case_sensitive": <bool>    // true or false
}

Custom Filter POST​

Request Parameters​

import requests

key = '<api-key>'

url = 'https://api.sapling.ai/api/v1/custom_filter'
data = {
    'key': key,
    'inp': 'Patient',
    'out': 'The patient',
    'case_sensitive': False,
}

try:
    resp = requests.post(url, json=data)
    if 200 <= resp.status_code < 300:
        resp_json = resp.json()
        print('Filter created: ', resp_json)
    else:
        print('Error: ', str(resp.status_code), resp.text)
except Exception as e:
    print('Error: ', e)

https://api.sapling.ai/api/v1/custom_filter

HTTP method: POST

key: String
32-character API key. Can also be supplied via the Authorization header as a bearer token; if both are provided, the key parameter takes precedence.

inp: String
Input text to match. Can be empty string for wildcards.

out: String
Output text to match. Can be empty string for wildcards.

case_sensitive: Boolean
Whether the filter should be case-sensitive. Defaults to true.

Response Parameters​

JSON, Created Custom Filter Entry Custom Filter Entry Structure:

{
  "id": <str, UUID>,          // Opaque id, used for deletion
  "created_at": <str, date>,  // e.g. "Wed, 07 Oct 2020 21:15:47 GMT"
  "updated_at": <str, date>,  // e.g. "Wed, 07 Oct 2020 21:15:47 GMT"
  "input": <str>,             // Input text to match
  "output": <str>,            // Output text to match
  "case_sensitive": <bool>    // true or false
}

Errors​

The API answers 400, with the reason in msg, when:

  • inp and out are both blank after trimming whitespace
  • inp and out are the same
  • the account already has a filter with this inp and out (Filter already exists.)
  • inp contains more than two digits
  • case_sensitive is false but inp and out differ only in case, e.g. apple → Apple. Such a filter must be case-sensitive.

Custom Filter DELETE​

Request Parameters​

import requests

key = '<api-key>'
filter_id = '<CUSTOM_FILTER_ID>'

url = f'https://api.sapling.ai/api/v1/custom_filter/{filter_id}'
data = {
    'key': key,
}

try:
    resp = requests.delete(url, json=data)
    if 200 <= resp.status_code < 300:
        print('Success')
    else:
        print('Error: ', str(resp.status_code), resp.text)
except Exception as e:
    print('Error: ', e)

https://api.sapling.ai/api/v1/custom_filter/<user_custom_filter_id>

HTTP method: DELETE

<user_custom_filter_id>: String (UUID)
ID of custom filter to delete.

key: String
32-character API key. Can also be supplied via the Authorization header as a bearer token; if both are provided, the key parameter takes precedence.

Response Parameters​

Empty, HTTP status code 204.