Fraud Prevention API

Version 0.1

The Fraud Prevention API is a set of APIs supporting Fraud detection including managing own fraud rules. For more details, please visit the Vonage Developer Center.

Download OpenAPI Specification

Custom Fraud Rules

Operations for managing specific fraud rules per product.

List custom fraud rules

Returns a paginated list of custom fraud rules filtered by product type.

gethttps://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/:product

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Path Parameters

product
string
Required
Must be one of:SMSVOICE

Query Parameters

page_size
integer(int32)
Default100

Page size in Integer format

page
integer(int32)
Default1

Page number in Integer format

threshold
integer(int32)

Threshold value in Integer format

interval
integer(int32)

Interval value in Integer format it will be presented in minutes

countries
array

Array of ISO countries codes

Responses
Content Type
application/json

OK

page
integer(int32)
example1
page_size
integer(int32)
example100
total_pages
integer(int32)
example5
total_items
integer(int32)
example450
_embedded
object
entries
array
country
string
exampleGB
interval
integer(int32)
example60
threshold
integer(int32)
example10
product
string
exampleSMS
id
string
exampleabcdef01-2345-6789-abcd-ef0123456789
_links
object
self
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779

self link

_links
object
first
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=1&size=100

first link of the paginated result set

last
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=4&size=100

last link of the paginated result set

prev
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=1&size=100

previous link of the paginated result set

self
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=1&size=100

self link

Example Response

{
   "page": 1,
   "page_size": 100,
   "total_pages": 5,
   "total_items": 450,
   "_embedded": {
      "entries": [
         {
            "country": "GB",
            "interval": 60,
            "threshold": 10,
            "product": "SMS",
            "id": "abcdef01-2345-6789-abcd-ef0123456789",
            "_links": {
               "self": {
                  "href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779"
               }
            }
         }
      ]
   },
   "_links": {
      "first": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=1&size=100"
      },
      "last": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=4&size=100"
      },
      "prev": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=1&size=100"
      },
      "self": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=1&size=100"
      }
   }
}

Edit custom fraud rule by ID

Update an existing fraud rule configuration using its unique identifier.

puthttps://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/:id

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Path Parameters

id
string
Required
exampleabcdef01-2345-6789-abcd-ef0123456789

Rule ID in UUID format

Request Body
Content Type
application/json

product
string
exampleSMS

Product type (SMS or VOICE)

Must be one of:VOICESMS
country
string
exampleGB

ISO country code

interval
integer(int32)
example60
threshold
integer(int32)
example10

Example Request

{
   "product": "SMS",
   "country": "GB",
   "interval": 60,
   "threshold": 10
}

Responses
Content Type
application/json

OK

country
string
exampleGB
interval
integer(int32)
example60
threshold
integer(int32)
example10
product
string
exampleSMS
id
string
exampleabcdef01-2345-6789-abcd-ef0123456789
_links
object
self
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779

self link

Example Response

{
   "country": "GB",
   "interval": 60,
   "threshold": 10,
   "product": "SMS",
   "id": "abcdef01-2345-6789-abcd-ef0123456789",
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779"
      }
   }
}

Create custom fraud rule

Create a new custom fraud rule for a specific product and country.

posthttps://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Request Body
Content Type
application/json

product
string
exampleSMS

Product type (SMS or VOICE)

Must be one of:VOICESMS
country
string
exampleGB

ISO country code

interval
integer(int32)
example60
threshold
integer(int32)
example10

Example Request

{
   "product": "SMS",
   "country": "GB",
   "interval": 60,
   "threshold": 10
}

Responses
Content Type
application/json

Created

country
string
exampleGB
interval
integer(int32)
example60
threshold
integer(int32)
example10
product
string
exampleSMS
id
string
exampleabcdef01-2345-6789-abcd-ef0123456789
_links
object
self
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779

self link

Example Response

{
   "country": "GB",
   "interval": 60,
   "threshold": 10,
   "product": "SMS",
   "id": "abcdef01-2345-6789-abcd-ef0123456789",
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779"
      }
   }
}

Get custom fraud rule by product and id

Retrieve detailed information for a specific custom fraud rule.

gethttps://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/:product/:id

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Path Parameters

product
string
Required
Must be one of:SMSVOICE
id
string
Required
exampleabcdef01-2345-6789-abcd-ef0123456789

Rule ID in UUID format

Responses
Content Type
application/json

OK

country
string
exampleGB
interval
integer(int32)
example60
threshold
integer(int32)
example10
product
string
exampleSMS
id
string
exampleabcdef01-2345-6789-abcd-ef0123456789
_links
object
self
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779

self link

Example Response

{
   "country": "GB",
   "interval": 60,
   "threshold": 10,
   "product": "SMS",
   "id": "abcdef01-2345-6789-abcd-ef0123456789",
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779"
      }
   }
}

Delete custom fraud rule by ID

Permanently remove a custom fraud rule from the system.

deletehttps://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/:product/:id

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Path Parameters

product
string
Required
Must be one of:SMSVOICE
id
string
Required
exampleabcdef01-2345-6789-abcd-ef0123456789

Rule ID in UUID format

Responses

No Content

AIT protection

Artificial Inflation of Traffic protection configuration.

Get AIT configuration

Retrieve the current AIT protection configuration for a given product.

gethttps://api.nexmo.com/v0.1/fraud-defender/configurations/protections/ait/:product

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Path Parameters

product
string
Required
Defaultsms

product type

Must be one of:sms

Responses
Content Type
application/json

AIT protection config response

data
object
protection_enabled
boolean
Required
exampletrue

used to turn on/off AIT protection

default_protection_level
string
examplestandard

Required if protection_enabled is set to true. Default AIT protection level will be used for countries where no specific per-country configuration exists.

Must be one of:highstandardnone
protection_level_per_country
array

array of specific per-country AIT protection level configurations

country
string
Required
exampleUS

country code in ISO 3166-1 Alpha-2 standard

protection_level
string
Required
examplehigh

AIT protection level

Must be one of:highstandardnone
_links
object
self
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/configurations/protections/ait/SMS

Example Response

{
   "data": {
      "protection_enabled": true,
      "default_protection_level": "standard",
      "protection_level_per_country": [
         {
            "country": "US",
            "protection_level": "standard"
         }
      ],
      "_links": {
         "self": {
            "href": "https://api.nexmo.com/v0.1/fraud-defender/configurations/protections/ait/SMS"
         }
      }
   }
}

Create or update AIT configuration

Enable or modify AIT protection settings globally or per country.

puthttps://api.nexmo.com/v0.1/fraud-defender/configurations/protections/ait/:product

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Path Parameters

product
string
Required
Defaultsms

product type

Must be one of:sms

Request Body
Content Type
application/json

data
object
protection_enabled
boolean
Required
exampletrue

used to turn on/off AIT protection

default_protection_level
string
examplestandard

Required if protection_enabled is set to true. Default AIT protection level will be used for countries where no specific per-country configuration exists.

Must be one of:highstandardnone
protection_level_per_country
array

array of specific per-country AIT protection level configurations

country
string
Required
exampleUS

country code in ISO 3166-1 Alpha-2 standard

protection_level
string
Required
examplehigh

AIT protection level

Must be one of:highstandardnone

Example Request

{
   "data": {
      "protection_enabled": true,
      "default_protection_level": "standard",
      "protection_level_per_country": [
         {
            "country": "US",
            "protection_level": "high"
         }
      ]
   }
}

Responses
Content Type
application/json

AIT protection config response

data
object
protection_enabled
boolean
Required
exampletrue

used to turn on/off AIT protection

default_protection_level
string
examplestandard

Required if protection_enabled is set to true. Default AIT protection level will be used for countries where no specific per-country configuration exists.

Must be one of:highstandardnone
protection_level_per_country
array

array of specific per-country AIT protection level configurations

country
string
Required
exampleUS

country code in ISO 3166-1 Alpha-2 standard

protection_level
string
Required
examplehigh

AIT protection level

Must be one of:highstandardnone
_links
object
self
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/configurations/protections/ait/SMS

Example Response

{
   "data": {
      "protection_enabled": true,
      "default_protection_level": "standard",
      "protection_level_per_country": [
         {
            "country": "US",
            "protection_level": "standard"
         }
      ],
      "_links": {
         "self": {
            "href": "https://api.nexmo.com/v0.1/fraud-defender/configurations/protections/ait/SMS"
         }
      }
   }
}

Rules

General fraud rule management and listing.

Create rule

Create a new fraud rule based on phone number prefixes.

posthttps://api.nexmo.com/v0.1/fraud-defender/rules

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Request Body
Content Type
application/json

product
string
Required
examplesms
Must be one of:voicesms
prefix
string
Required
Max15
example44

The prefix attribute is used to check whether a phone number begins with a particular sequence of digits. It's not related to phone number prefixes.

reason
string
Required
exampleMy custom prefix rule

Human readable reason

action
string
Required
exampleblock
Must be one of:blockallow
status
string
exampleactive
Must be one of:activearchived

Example Request

{
   "product": "sms",
   "prefix": "44",
   "reason": "My custom prefix rule",
   "action": "block",
   "status": "active"
}

Responses
Content Type
application/json

rule operation success

id
string
exampletest-id
product
string
examplesms
Must be one of:voicesms
prefix
string
example44

The prefix attribute is used to check whether a phone number begins with a particular sequence of digits. It's not related to phone number prefixes.

direction
string
examplefrom
Must be one of:fromto
traffic_direction
string
Defaultoutbound
exampleoutbound

Outbound rules apply to traffic generated from you API Key. Inbound rules apply to traffic sent to your phone numbers.

action
string
exampleblock
Must be one of:blockallow
reason
string
exampleMy custom prefix rule

Human readable reason

permission
string
exampleedit
Must be one of:viewedit
status
string
exampleactive
Must be one of:activearchived
created_timestamp
string
example2022-12-09T18:19:26
updated_timestamp
string
example2022-11-09T18:19:26
archived_timestamp
string
example2022-10-09T18:19:26
_links
object
self
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/rules/test-id

Example Response

{
   "id": "test-id",
   "product": "sms",
   "prefix": "44",
   "direction": "from",
   "traffic_direction": "outbound",
   "action": "block",
   "reason": "My custom prefix rule",
   "permission": "edit",
   "status": "active",
   "created_timestamp": "2022-12-09T18:19:26",
   "updated_timestamp": "2022-11-09T18:19:26",
   "archived_timestamp": "2022-10-09T18:19:26",
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/rules/test-id"
      }
   }
}

Listing rules

List all existing fraud rules with support for filtering by prefix, action, and status.

gethttps://api.nexmo.com/v0.1/fraud-defender/rules

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Query Parameters

product
string

if passed, lists rules for that product. if not, gives such for all product types

Must be one of:voicesms
prefix
string

phone prefix filter

reason
string

reason filter

action
string

action filter

rule_type
string

rule type filter (allow, block)

status
string

filter rules by status (active, archived, all)

show_default_rules
boolean
Defaulttrue

defines whether to display default rules or not

show_custom_rules
boolean
Defaulttrue

show custom rules flag

page_size
string
Default150

page size parameter, starts from 1

page
string
Default1

page offset parameter, starts from 1

sort
string

sort by product, prefix or traffic and it's case-insensitive

Must be one of:productprefixtraffic
order
string
Defaultdesc

sort order either asc or desc and it's case-insensitive

Must be one of:ascdesc

Responses
Content Type
application/json

rule listing success

_links
object
first
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=1&page_size=3

first link of the paginated result set

last
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=4&page_size=3

last link of the paginated result set

next
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=3&page_size=3

next link of the paginated result set

prev
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=1&page_size=3

previous link of the paginated result set

self
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=2&page_size=3

self link

page
object
number
number
example2

Page number

size
number
example3

Page size number or 0 if no entries found. Default is 150.

totalElements
number
example11

Total entries for the result set or 0 if no entries found

totalPages
number
example4

Total pages for the paginated result set or 1 if no entries found

_embedded
object
rules
array
id
string
exampletest-id
product
string
examplesms
Must be one of:voicesms
prefix
string
example44

The prefix attribute is used to check whether a phone number begins with a particular sequence of digits. It's not related to phone number prefixes.

direction
string
examplefrom
Must be one of:fromto
traffic_direction
string
Defaultoutbound
exampleoutbound

Outbound rules apply to traffic generated from you API Key. Inbound rules apply to traffic sent to your phone numbers.

action
string
exampleblock
Must be one of:blockallow
reason
string
exampleMy custom prefix rule

Human readable reason

permission
string
exampleedit
Must be one of:viewedit
status
string
exampleactive
Must be one of:activearchived
created_timestamp
string
example2022-12-09T18:19:26
updated_timestamp
string
example2022-11-09T18:19:26
archived_timestamp
string
example2022-10-09T18:19:26
_links
object
self
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/rules/test-id

Example Response

{
   "_links": {
      "first": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=1&page_size=3"
      },
      "last": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=4&page_size=3"
      },
      "next": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=3&page_size=3"
      },
      "prev": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=1&page_size=3"
      },
      "self": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=2&page_size=3"
      }
   },
   "page": {
      "number": 2,
      "size": 3,
      "totalElements": 11,
      "totalPages": 4
   },
   "_embedded": {
      "rules": [
         {
            "id": "test-id",
            "product": "sms",
            "prefix": "44",
            "direction": "from",
            "traffic_direction": "outbound",
            "action": "block",
            "reason": "My custom prefix rule",
            "permission": "edit",
            "status": "active",
            "created_timestamp": "2022-12-09T18:19:26",
            "updated_timestamp": "2022-11-09T18:19:26",
            "archived_timestamp": "2022-10-09T18:19:26",
            "_links": {
               "self": {
                  "href": "https://api.nexmo.com/v0.1/fraud-defender/rules/test-id"
               }
            }
         }
      ]
   }
}

Get rule by id

Retrieve a specific fraud rule by its unique ID.

gethttps://api.nexmo.com/v0.1/fraud-defender/rules/:id

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Path Parameters

id
string
Required
exampleabcdef01-2345-6789-abcd-ef0123456789

Rule ID in UUID format

Responses
Content Type
application/json

rule operation success

id
string
exampletest-id
product
string
examplesms
Must be one of:voicesms
prefix
string
example44

The prefix attribute is used to check whether a phone number begins with a particular sequence of digits. It's not related to phone number prefixes.

direction
string
examplefrom
Must be one of:fromto
traffic_direction
string
Defaultoutbound
exampleoutbound

Outbound rules apply to traffic generated from you API Key. Inbound rules apply to traffic sent to your phone numbers.

action
string
exampleblock
Must be one of:blockallow
reason
string
exampleMy custom prefix rule

Human readable reason

permission
string
exampleedit
Must be one of:viewedit
status
string
exampleactive
Must be one of:activearchived
created_timestamp
string
example2022-12-09T18:19:26
updated_timestamp
string
example2022-11-09T18:19:26
archived_timestamp
string
example2022-10-09T18:19:26
_links
object
self
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/rules/test-id

Example Response

{
   "id": "test-id",
   "product": "sms",
   "prefix": "44",
   "direction": "from",
   "traffic_direction": "outbound",
   "action": "block",
   "reason": "My custom prefix rule",
   "permission": "edit",
   "status": "active",
   "created_timestamp": "2022-12-09T18:19:26",
   "updated_timestamp": "2022-11-09T18:19:26",
   "archived_timestamp": "2022-10-09T18:19:26",
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/rules/test-id"
      }
   }
}

Archive rule by id

Mark a rule as archived. Archived rules are no longer active in the fraud detection flow.

deletehttps://api.nexmo.com/v0.1/fraud-defender/rules/:id

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Path Parameters

id
string
Required
exampleabcdef01-2345-6789-abcd-ef0123456789

Rule ID in UUID format

Responses

No Content

Update rule by id

Update specific fields of an existing fraud rule.

patchhttps://api.nexmo.com/v0.1/fraud-defender/rules/:id

Authentication

KeyDescriptionWhereExample
Authorization

Base64 encoded API key and secret joined by a colon.
Read more

Headers

Basic <base64>

Path Parameters

id
string
Required
exampleabcdef01-2345-6789-abcd-ef0123456789

Rule ID in UUID format

Request Body
Content Type
application/json

reason
string
Required
exampleMy custom prefix rule

Human readable reason

Example Request

{
   "reason": "My custom prefix rule"
}

Responses
Content Type
application/json

rule operation success

id
string
exampletest-id
product
string
examplesms
Must be one of:voicesms
prefix
string
example44

The prefix attribute is used to check whether a phone number begins with a particular sequence of digits. It's not related to phone number prefixes.

direction
string
examplefrom
Must be one of:fromto
traffic_direction
string
Defaultoutbound
exampleoutbound

Outbound rules apply to traffic generated from you API Key. Inbound rules apply to traffic sent to your phone numbers.

action
string
exampleblock
Must be one of:blockallow
reason
string
exampleMy custom prefix rule

Human readable reason

permission
string
exampleedit
Must be one of:viewedit
status
string
exampleactive
Must be one of:activearchived
created_timestamp
string
example2022-12-09T18:19:26
updated_timestamp
string
example2022-11-09T18:19:26
archived_timestamp
string
example2022-10-09T18:19:26
_links
object
self
object
href
string
examplehttps://api.nexmo.com/v0.1/fraud-defender/rules/test-id

Example Response

{
   "id": "test-id",
   "product": "sms",
   "prefix": "44",
   "direction": "from",
   "traffic_direction": "outbound",
   "action": "block",
   "reason": "My custom prefix rule",
   "permission": "edit",
   "status": "active",
   "created_timestamp": "2022-12-09T18:19:26",
   "updated_timestamp": "2022-11-09T18:19:26",
   "archived_timestamp": "2022-10-09T18:19:26",
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v0.1/fraud-defender/rules/test-id"
      }
   }
}

Errors

The following is a non-exhaustive list of error codes that may occur while using this API.

These codes are in addition to any of our generic error codes.

CodeInformation
http:error:conflict

Rule couldn't be added as conflicts with currently existing rules

system:error:internal-error

Something went wrong.