Intelligence Exceptions API

Manage static Intelligence exceptions for your account. An exception overrides the risk treatment for a matching phone number, IP address, and/or email address. All requests are scoped to your account, so you can only view and modify your own exceptions.

Base URL

All endpoints are available under the regional base URL:

https://{base-url}/v1

The specific host depends on your data-residency region. See Data residency below.

Data residency

To support regional compliance and data-sovereignty requirements, the API is offered through separate regional endpoints. The region is chosen by the endpoint (base URL) you call. It is not a field in the request body.

Exceptions are stored in the region where they are created and are only accessible through that same regional endpoint. Exceptions are not replicated across regions, so choose the region that matches your requirement and use it consistently.

Region	Scope	URL
ALL	Global - no specific data - residency restriction (default).	`https://static-exceptions.telesign.com/v1`
EU	Data is stored and processed within the European Union.	`https://static-exceptions-eu.telesign.com/v1`
US	Data is stored and processed within the United States.	`https://static-exceptions-us.telesign.com/v1`

Production base URLs for each region will be provided separately.

Authentication

Authenticate each request using the Authorization header. Your account is identified from your credentials at the gateway, so all reads and writes are limited to your own data.

Authorization: Basic <base64(username:password)>
Accept: application/json

The exact authentication scheme (e.g. Basic) will be confirmed during onboarding.

General requirements

Accepts: application/json
Responds with: application/json
Encoding: Accepts only UTF-8 unicode characters as inputs.

Exception object

Returned by all read and write endpoints.

Field	Type	Description
`exception_id`	string (uuid)	Server-assigned identifier.
`org_name`	string \| null	Organization the exception belongs to.
`sub_org_name`	string \| null	Sub-organization the exception belongs to.
`phone_number`	string \| null	Phone number the exception applies to.
`phone_country_iso2`	string \| null	ISO 3166-1 alpha-2 country code for the phone number.
`phone_number_prefix`	string \| null	Phone number prefix.
`ip_address`	string \| null	IP address the exception applies to. Accepts IPv4 or IPv6.
`ip_country_iso2`	string \| null	ISO 3166-1 alpha-2 country code for the IP address.
`email_address`	string \| null	Email address the exception applies to.
`email_domain`	string \| null	Email domain.
`active`	boolean \| null	Whether the exception is currently active.
`valid_from`	string (datetime)	Start of the validity window, UTC. Format `YYYY-MM-DD HH:mm`. Set by the service.
`valid_until`	string (datetime)	End of the validity window, UTC. Format `YYYY-MM-DD HH:mm`. Set by the service.
`exception_type`	integer	The type of exception. `1` = whitelisted by customer, `2` = blacklisted by customer.
`intelligence_score_value`	string	The score value applied by the exception. Set by the service from `exception_type` (`1` for whitelist, `1000` for blacklist).
`comment`	string \| null	Free-text note.
`created_by`	string	Identifier of the creator.
`created_on_utc`	string (datetime)	Creation timestamp, UTC.
`updated_on_utc`	string (datetime)	Last update timestamp, UTC. Empty string if never updated.

List exceptions

GET /v1/intelligence-exceptions

Returns your exceptions, paginated.

Query parameters

Param	Type	Required	Description
`term`	string	optional	Free-text search filter (1–50 characters).
`page`	integer	optional	Page number. Minimum `1`, default `1`.
`size`	integer	optional	Page size. Between `1` and `100`, default `50`.

Example

Request

curl -X GET \
  'https://{base-url}/v1/intelligence-exceptions?page=1&size=50' \
  -H 'Authorization: Basic <base64(username:password)>' \
  -H 'Accept: application/json'

Response (body only) - 200

{
  "items": [
    {
      "exception_id": "f8e579a8-1034-47ed-a62f-2d8358be183d",
      "org_name": "Example Org",
      "sub_org_name": "Example Sub-Org",
      "phone_number": "987652116",
      "phone_country_iso2": "US",
      "phone_number_prefix": "123",
      "ip_address": "192.168.1.1",
      "ip_country_iso2": "US",
      "email_address": "[email protected]",
      "email_domain": "example.com",
      "active": true,
      "valid_from": "2026-06-12 05:32",
      "valid_until": "2028-06-12 05:32",
      "exception_type": 1,
      "intelligence_score_value": "1",
      "comment": "Allowlisted recipient",
      "created_by": "d7b66ac4-30c0-4b68-9fb6-6add83e0aa10",
      "created_on_utc": "2026-06-12 05:32",
      "updated_on_utc": ""
    },
    {
      "exception_id": "b1a1432f-5372-405b-93c9-0eb510003559",
      "org_name": "Example Org",
      "sub_org_name": "Example Sub-Org",
      "phone_number": null,
      "phone_country_iso2": "US",
      "phone_number_prefix": "110",
      "ip_address": "192.168.1.1",
      "ip_country_iso2": "US",
      "email_address": "[email protected]",
      "email_domain": "example.com",
      "active": false,
      "valid_from": "2026-06-12 05:32",
      "valid_until": "2028-06-12 05:32",
      "exception_type": 1,
      "intelligence_score_value": "1",
      "comment": "Disabled exception",
      "created_by": "d7b66ac4-30c0-4b68-9fb6-6add83e0aa10",
      "created_on_utc": "2026-06-12 05:32",
      "updated_on_utc": "2026-06-12 05:32"
    }
  ],
  "total": 158,
  "page": 1,
  "page_size": 50
}

Create an exception

POST /v1/intelligence-exceptions

Provide the fields relevant to what you want to match (phone, IP, and/or email address). Only exception_type is required. The validity window and the applied score value are set by the service and returned in the response.

Body parameters

Field	Type	Required	Constraints	Description
`exception_type`	integer	required	`1` or `2`	The type of exception. `1` = whitelisted by customer, `2` = blacklisted by customer.
`phone_number`	string \| null	optional	max 30 chars	Phone number to match.
`phone_country_iso2`	string \| null	optional	2 chars	ISO 3166-1 alpha-2 country code for the phone number.
`phone_number_prefix`	string \| null	optional	max 30 chars	Phone number prefix to match.
`ip_address`	string \| null	optional		IP address to match. Accepts IPv4 or IPv6.
`ip_country_iso2`	string \| null	optional	2 chars	ISO 3166-1 alpha-2 country code for the IP address.
`email_address`	string \| null	optional		Email address to match.
`email_domain`	string \| null	optional		Email domain to match.
`comment`	string \| null	optional		Free-text note.
`active`	boolean	optional	default `true`	Whether the exception is active on creation.

Fields set automatically by the service

Do not send these, they are populated on creation and returned in the response:

intelligence_score_value - derived from exception_type (1 for a whitelist exception, 1000 for a blacklist exception).
valid_from - set to the creation time.
valid_until - set automatically based on the data provided: 2 years when PII (such as a phone number or email address) is included, 5 years when it is not.

Example

Request

curl -X POST \
  'https://{base-url}/v1/intelligence-exceptions' \
  -H 'Authorization: Basic <base64(username:password)>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "phone_number": "11234567890",
    "phone_country_iso2": "US",
    "phone_number_prefix": "1",
    "ip_address": "192.168.1.1",
    "ip_country_iso2": "US",
    "email_address": "[email protected]",
    "email_domain": "example.com",
    "exception_type": 1,
    "comment": "Customer exception",
    "active": true
  }'

Response (body only) - 200

{
  "exception_id": "b1a1432f-5372-405b-93c9-0eb510003559",
  "org_name": "Example Org",
  "sub_org_name": "Example Sub-Org",
  "phone_number": "11234567890",
  "phone_country_iso2": "US",
  "phone_number_prefix": "1",
  "ip_address": "192.168.1.1",
  "ip_country_iso2": "US",
  "email_address": "[email protected]",
  "email_domain": "example.com",
  "active": true,
  "valid_from": "2026-06-12 05:32",
  "valid_until": "2028-06-12 05:32",
  "exception_type": 1,
  "intelligence_score_value": "1",
  "comment": "Customer exception",
  "created_by": "d7b66ac4-30c0-4b68-9fb6-6add83e0aa10",
  "created_on_utc": "2026-06-12 05:32",
  "updated_on_utc": ""
}

Retrieve an exception

GET /v1/intelligence-exceptions/{exception_id}

Path parameters

Param	Type	Required	Description
`exception_id`	string (uuid)	required	The ID of the exception.

Example

Request

curl -X GET \
  'https://{base-url}/v1/intelligence-exceptions/b1a1432f-5372-405b-93c9-0eb510003559' \
  -H 'Authorization: Basic <base64(username:password)>' \
  -H 'Accept: application/json'

Returns a single exception object (200 OK), in the same shape as the items above.

Update an exception

PUT /v1/intelligence-exceptions/{exception_id}

Fully updates an exception. The request body is identical to Create an exception.

curl -X PUT \
  'https://{base-url}/v1/intelligence-exceptions/b1a1432f-5372-405b-93c9-0eb510003559' \
  -H 'Authorization: Basic <base64(username:password)>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "exception_type": 1,
    "phone_country_iso2": "US",
    "phone_number_prefix": "1",
    "email_address": "[email protected]",
    "email_domain": "example.com",
    "comment": "Updated note",
    "active": true
  }'

Returns the updated exception object (200 OK).

Change exception status

PATCH /v1/intelligence-exceptions/{exception_id}

Activates or deactivates an exception.

Body parameters

Field	Type	Required	Description
`active`	boolean	required	New active status.

curl -X PATCH \
  'https://{base-url}/v1/intelligence-exceptions/b1a1432f-5372-405b-93c9-0eb510003559' \
  -H 'Authorization: Basic <base64(username:password)>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{ "active": false }'

Returns the updated exception object (200 OK).

Response codes

Code	Meaning
`200`	Success.
`401`	Authentication failed or missing credentials.
`404`	The requested exception was not found or is not available to your account.
`422`	Validation error. The response body identifies the offending field(s).
`429`	Rate limit exceeded. Retry after a short delay.
`500`	Unexpected server error; the request was not completed.
`503`	Service temporarily unavailable; retry.

Validation error - 422

{
  "detail": [
    {
      "loc": ["body", "exception_type"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Updated about 1 hour ago

Did this page help you?