Fraud Defender API

Version 1

The Fraud Defender 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

Traffic Rules

Operations to manage traffic rules.

Available Operations

Create rule

Create a new fraud rule based on phone number prefixes.

posthttps://api.nexmo.com/v1/fraud-defender/rules

Authentication

Key	Description	Where	Example
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:activearchivedall

Example Request

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

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

Responses
Content Type
application/json

rule operation success

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string

exampletest-id

product

string

examplesms

Must be one of:voicesms

prefix

string

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.

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:activearchivedall

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

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

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/v1/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/v1/fraud-defender/rules

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Query Parameters

product

string

examplesms

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

Must be one of:voicesms

prefix

string

Max15

example44

phone prefix filter

reason

string

exampleMy custom prefix rule

reason filter

action

string

exampleblock

action filter

Must be one of:blockallow

rule_type

string

rule type filter (allow, block)

Must be one of:allowblock

status

string

exampleactive

filter rules by status (active, archived, all)

Must be one of:activearchivedall

show_default_rules

boolean

Defaulttrue

defines whether to display default rules or not

show_custom_rules

boolean

Defaulttrue

show custom rules flag

page_size

integer

example10

Page size in Integer format

page

integer

Min1

example2

Page number in Integer format

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

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

links

object

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

page

object

page_size

integer

example10

Items per page

page

integer

Min1

example2

Page Offset

total_pages

integer

Min1

example100

Number of pages in the entire result set

total_items

integer

example100

Number of items in the entire result set

_embedded

object

rules

array

string

exampletest-id

product

string

examplesms

Must be one of:voicesms

prefix

string

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.

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:activearchivedall

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

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

{
   "links": {
      "first": {
         "href": "https://api.nexmo.com/v1/fraud-defender/rules?order=asc&page=1&page_size=3"
      },
      "last": {
         "href": "https://api.nexmo.com/v1/fraud-defender/rules?order=asc&page=4&page_size=3"
      },
      "next": {
         "href": "https://api.nexmo.com/v1/fraud-defender/rules?order=asc&page=3&page_size=3"
      },
      "prev": {
         "href": "https://api.nexmo.com/v1/fraud-defender/rules?order=asc&page=1&page_size=3"
      },
      "self": {
         "href": "https://api.nexmo.com/v1/fraud-defender/rules?order=asc&page=2&page_size=3"
      }
   },
   "page": {
      "page_size": 10,
      "page": 2,
      "total_pages": 100,
      "total_items": 100
   },
   "_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/v1/fraud-defender/rules/test-id"
               }
            }
         }
      ]
   }
}

Get rule by id

Retrieve a specific fraud rule by its unique ID.

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

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

string

Required

exampleabcdef01-2345-6789-abcd-ef0123456789

Rule ID in UUID format

Responses
Content Type
application/json

rule operation success

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string

exampletest-id

product

string

examplesms

Must be one of:voicesms

prefix

string

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.

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:activearchivedall

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

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

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/v1/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/v1/fraud-defender/rules/:id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

string

Required

exampleabcdef01-2345-6789-abcd-ef0123456789

Rule ID in UUID format

Responses

No Content - Resource successfully deleted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

Update rule by id

Update specific fields of an existing fraud rule.

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

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

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"
}

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

Responses
Content Type
application/json

rule operation success

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string

exampletest-id

product

string

examplesms

Must be one of:voicesms

prefix

string

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.

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:activearchivedall

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

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

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/v1/fraud-defender/rules/test-id"
      }
   }
}

AIT Protection

Operations to manage AIT Protection.

Available Operations

Get AIT configuration

Retrieve the current AIT protection configuration for a given product.

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

Authentication

Key	Description	Where	Example
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

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

data

object

protection_enabled

boolean

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

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

{
   "data": {
      "protection_enabled": true,
      "default_protection_level": "standard",
      "protection_level_per_country": [
         {
            "country": "US",
            "protection_level": "high"
         }
      ],
      "_links": {
         "self": {
            "href": "https://api.nexmo.com/v1/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/v1/fraud-defender/configurations/protections/ait/:product

Authentication

Key	Description	Where	Example
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

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"
         }
      ]
   }
}

{
   "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

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

data

object

protection_enabled

boolean

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

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

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

SMS Burst Protection

Operations to manage limits on SMS traffic bursts to prevent fraud.

Available Operations

List SMS Burst Protection entries

Retrieve a paginated list of all SMS Burst Protection configurations.

gethttps://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Query Parameters

page

integer

Min1

example2

Page number in Integer format

page_size

integer

example10

Page size in Integer format

Responses
Content Type
application/json

Successful operation

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

page

object

page_size

integer

example10

Items per page

page

integer

Min1

example2

Page Offset

total_pages

integer

Min1

example100

Number of pages in the entire result set

total_items

integer

example100

Number of items in the entire result set

_embedded

object

entries

array

string

exampleabcdef01-2345-6789-abcd-ef0123456789

Internal ID, to be used as the ID when updating or deleting a record

destination_countries

array

List of destination countries

Available Values:

DZ,AZ,BD,BB,BY,BJ,BG,EG,SV,GH,KZ,KG,LA,MV,MM,NG,PH,PK,PS,RU,LK,SD,SY,TJ,AE,UZ,BH,IR,IQ,IL,JO,KW,LB,OM,QA,SA,YE

block_value

integer

example1

Number of messages allowed in the 10 minutes time period, after which messages will be blocked.

_links

object

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

links

object

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

{
   "page": {
      "page_size": 10,
      "page": 2,
      "total_pages": 100,
      "total_items": 100
   },
   "_embedded": {
      "entries": [
         {
            "id": "abcdef01-2345-6789-abcd-ef0123456789",
            "destination_countries": [
               "DZ"
            ],
            "block_value": 1,
            "_links": {
               "self": {
                  "href": "https://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst/abcdef01-2345-6789-abcd-ef0123456789"
               }
            }
         }
      ]
   },
   "links": {
      "first": {
         "href": "https://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst?page=1&size=100"
      },
      "last": {
         "href": "https://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst?page=4&size=100"
      },
      "prev": {
         "href": "https://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst?page=1&size=100"
      },
      "self": {
         "href": "https://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst?page=1&size=100"
      }
   }
}

Create new SMS Burst Protection entity

Defines a new burst protection limit for a specific set of destination countries.

posthttps://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Request Body
Content Type
application/json

destination_countries

array

Required

Available Values:

DZ,AZ,BD,BB,BY,BJ,BG,EG,SV,GH,KZ,KG,LA,MV,MM,NG,PH,PK,PS,RU,LK,SD,SY,TJ,AE,UZ,BH,IR,IQ,IL,JO,KW,LB,OM,QA,SA,YE

block_value

integer

Required

example1

Number of messages allowed in the 10 minutes time period, after which messages will be blocked.

Example Request

{
   "destination_countries": [
      "DZ"
   ],
   "block_value": 1
}

{
   "destination_countries": [
      "DZ"
   ],
   "block_value": 1
}

Responses
Content Type
application/json

Successful operation

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string

exampleabcdef01-2345-6789-abcd-ef0123456789

Internal ID, to be used as the ID when updating or deleting a record

destination_countries

array

List of destination countries

Available Values:

DZ,AZ,BD,BB,BY,BJ,BG,EG,SV,GH,KZ,KG,LA,MV,MM,NG,PH,PK,PS,RU,LK,SD,SY,TJ,AE,UZ,BH,IR,IQ,IL,JO,KW,LB,OM,QA,SA,YE

block_value

integer

example1

Number of messages allowed in the 10 minutes time period, after which messages will be blocked.

_links

object

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

{
   "id": "abcdef01-2345-6789-abcd-ef0123456789",
   "destination_countries": [
      "DZ"
   ],
   "block_value": 1,
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst/abcdef01-2345-6789-abcd-ef0123456789"
      }
   }
}

Get SMS Burst Protection rule by ID

Fetch a specific burst protection entry using its unique identifier.

gethttps://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst/:id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

string

Required

exampleabcdef01-2345-6789-abcd-ef0123456789

Rule ID in UUID format

Responses
Content Type
application/json

Successful operation

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string

exampleabcdef01-2345-6789-abcd-ef0123456789

Internal ID, to be used as the ID when updating or deleting a record

destination_countries

array

List of destination countries

Available Values:

DZ,AZ,BD,BB,BY,BJ,BG,EG,SV,GH,KZ,KG,LA,MV,MM,NG,PH,PK,PS,RU,LK,SD,SY,TJ,AE,UZ,BH,IR,IQ,IL,JO,KW,LB,OM,QA,SA,YE

block_value

integer

example1

Number of messages allowed in the 10 minutes time period, after which messages will be blocked.

_links

object

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

{
   "id": "abcdef01-2345-6789-abcd-ef0123456789",
   "destination_countries": [
      "DZ"
   ],
   "block_value": 1,
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst/abcdef01-2345-6789-abcd-ef0123456789"
      }
   }
}

Edit an existing SMS Burst Protection rule

puthttps://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst/:id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

string

Required

exampleabcdef01-2345-6789-abcd-ef0123456789

Rule ID in UUID format

Request Body
Content Type
application/json

destination_countries

array

Required

Available Values:

DZ,AZ,BD,BB,BY,BJ,BG,EG,SV,GH,KZ,KG,LA,MV,MM,NG,PH,PK,PS,RU,LK,SD,SY,TJ,AE,UZ,BH,IR,IQ,IL,JO,KW,LB,OM,QA,SA,YE

block_value

integer

Required

example1

Number of messages allowed in the 10 minutes time period, after which messages will be blocked.

Example Request

{
   "destination_countries": [
      "DZ"
   ],
   "block_value": 1
}

{
   "destination_countries": [
      "DZ"
   ],
   "block_value": 1
}

Responses
Content Type
application/json

Successful operation

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

string

exampleabcdef01-2345-6789-abcd-ef0123456789

Internal ID, to be used as the ID when updating or deleting a record

destination_countries

array

List of destination countries

Available Values:

DZ,AZ,BD,BB,BY,BJ,BG,EG,SV,GH,KZ,KG,LA,MV,MM,NG,PH,PK,PS,RU,LK,SD,SY,TJ,AE,UZ,BH,IR,IQ,IL,JO,KW,LB,OM,QA,SA,YE

block_value

integer

example1

Number of messages allowed in the 10 minutes time period, after which messages will be blocked.

_links

object

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

{
   "id": "abcdef01-2345-6789-abcd-ef0123456789",
   "destination_countries": [
      "DZ"
   ],
   "block_value": 1,
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst/abcdef01-2345-6789-abcd-ef0123456789"
      }
   }
}

Delete SMS Burst Protection entity by id

Remove an SMS burst protection entry from the system.

deletehttps://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst/:id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

string

Required

exampleabcdef01-2345-6789-abcd-ef0123456789

Rule ID in UUID format

Responses

No Content - Resource successfully deleted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

Custom Fraud Alerts

Operations to manage thresholds and intervals for custom fraud detection logic.

Available Operations

List custom fraud alerts

gethttps://api.nexmo.com/v1/fraud-defender/configuration/custom-rules/:identifier

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

identifier

string

Required

Must be one of:SMSVOICE

Query Parameters

page_size

integer

example10

Page size in Integer format

page

integer

Min1

example2

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

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

page

object

page_size

integer

example10

Items per page

page

integer

Min1

example2

Page Offset

total_pages

integer

Min1

example100

Number of pages in the entire result set

total_items

integer

example100

Number of items in the entire result set

_embedded

object

entries

array

country

string

exampleGB

interval

integer(int32)

example60

threshold

integer(int32)

example100

product

string

examplesms

Must be one of:voicesms

string

exampleabcdef01-2345-6789-abcd-ef0123456789

_links

object

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

links

object

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

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

Edit custom fraud alert by ID

puthttps://api.nexmo.com/v1/fraud-defender/configuration/custom-rules/:identifier

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

identifier

string

Required

Request Body
Content Type
application/json

product

string

examplesms

Must be one of:voicesms

country

string

exampleGB

ISO country code

interval

integer(int32)

example360

Interval in minutes. Supported values:

1 min: 1
5 min: 5
10 min: 10
15 min: 15
30 min: 30
45 min: 45
1 hour: 60
6 hour: 360
12 hour: 720
One day: 1440

Must be one of:1510153045603607201440

threshold

integer(int32)

example100

Example Request

{
   "product": "sms",
   "country": "GB",
   "interval": 360,
   "threshold": 100
}

{
   "product": "sms",
   "country": "GB",
   "interval": 360,
   "threshold": 100
}

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

country

string

exampleGB

interval

integer(int32)

example60

threshold

integer(int32)

example100

product

string

examplesms

Must be one of:voicesms

string

exampleabcdef01-2345-6789-abcd-ef0123456789

_links

object

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

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

Create custom fraud alert

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

Authentication

Key	Description	Where	Example
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

Must be one of:voicesms

country

string

exampleGB

ISO country code

interval

integer(int32)

example360

Interval in minutes. Supported values:

1 min: 1
5 min: 5
10 min: 10
15 min: 15
30 min: 30
45 min: 45
1 hour: 60
6 hour: 360
12 hour: 720
One day: 1440

Must be one of:1510153045603607201440

threshold

integer(int32)

example100

Example Request

{
   "product": "sms",
   "country": "GB",
   "interval": 360,
   "threshold": 100
}

{
   "product": "sms",
   "country": "GB",
   "interval": 360,
   "threshold": 100
}

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

country

string

exampleGB

interval

integer(int32)

example60

threshold

integer(int32)

example100

product

string

examplesms

Must be one of:voicesms

string

exampleabcdef01-2345-6789-abcd-ef0123456789

_links

object

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

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

Get custom fraud alert by product and id

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

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

product

string

Required

examplesms

Must be one of:voicesms

string

Required

exampleabcdef01-2345-6789-abcd-ef0123456789

Rule ID in UUID format

Responses
Content Type
application/json

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

country

string

exampleGB

interval

integer(int32)

example60

threshold

integer(int32)

example100

product

string

examplesms

Must be one of:voicesms

string

exampleabcdef01-2345-6789-abcd-ef0123456789

_links

object

HAL Links object

self

object

Required

A single HAL link object

href

string

Required

examplehttps://api.vonage.com/v1/resources/abc123

The URL for the resource

templated

boolean

Indicates if the href is a URI template

type

string

exampleapplication/json

Media type hint for the target resource

name

string

exampleresource-name

Secondary key for selecting link objects

title

string

exampleResource Title

Human-readable title for the link

Example Response

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

Delete custom fraud alert by ID

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

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

product

string

Required

examplesms

Must be one of:voicesms

string

Required

exampleabcdef01-2345-6789-abcd-ef0123456789

Rule ID in UUID format

Responses

No Content - Resource successfully deleted

Header Parameters

X-Request-Id

string(uuid)

examplef94b4e56-604e-07e5-e5ad-5a7228618f81

A unique identifier for the request, used for tracking and debugging

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.

Code	Information
http:error:conflict	Rule couldn't be added as conflicts with currently existing rules
system:error:internal-error	Something went wrong.
http:error:validation-fail	There was an issue when validating fields. Please refer to the API specs
http:error:bad-request	Bad Request. Please refer to the API specs

Fraud Defender API

Traffic Rules

Available Operations

Create rule

Authentication

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Header Parameters

Example Response

Listing rules

Authentication

Query Parameters

Responses Content Typeapplication/json

Header Parameters

Example Response

Get rule by id

Authentication

Path Parameters

Responses Content Typeapplication/json

Header Parameters

Example Response

Archive rule by id

Authentication

Path Parameters

Responses

Header Parameters

Update rule by id

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Header Parameters

Example Response

AIT Protection

Available Operations

Get AIT configuration

Authentication

Path Parameters

Responses Content Typeapplication/json

Header Parameters

Example Response

Create or update AIT configuration

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Header Parameters

Example Response

SMS Burst Protection

Available Operations

List SMS Burst Protection entries

Authentication

Query Parameters

Responses Content Typeapplication/json

Header Parameters

Example Response

Create new SMS Burst Protection entity

Authentication

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Header Parameters

Example Response

Get SMS Burst Protection rule by ID

Authentication

Path Parameters

Responses Content Typeapplication/json

Header Parameters

Example Response

Edit an existing SMS Burst Protection rule

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Header Parameters

Example Response

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json