Fraud Prevention API

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

Traffic Rules

Operations to manage traffic rules.

Retrieves all networks

Returns a complete list of networks. Supports filtering by name, mcc, country code or PLMN. If both mcc and country_code are provided, mcc takes precedence.

gethttps://api.nexmo.com/v2/fraud-defender/networks

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Query Parameters

name
string
exampleVodafone UK

Filter by network name

mcc
string
example234

Filter by Mobile Country Code (MCC)

country_code
string
exampleGB

Filter by ISO country code - alternative to MCC for identifying country

plmn
string
example23401

Filter by public land mobile network (PLMN)

Responses
Content Type
application/json

Successfully retrieved networks

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
_embedded
object
networks
array
name
string
Required
exampleVodafone UK

Network name

mcc
string
Required
example234

Mobile Country Code

country_code
string
Required
exampleGB

Country code (ISO 3166-1 Alpha-2)

plmns
array
Required

List of all Public Land Mobile Network codes, including primary and all aliases

_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

Retrieve all prefix traffic rules

Returns a paginated list of prefix rules with support for filtering by prefix, action and status. Prefix rules block or allow traffic for phone numbers starting with a given sequence of digits.

gethttps://api.nexmo.com/v2/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
examplesms

Find rules for a specific product. When omitted, rules for all products are returned.

Must be one of:voicesms
prefix
string
Max16
example44

Find rules for a specific phone prefix

action
string
Defaultblock
exampleblock

Find rules with a specific action

Must be one of:blockallow
status
string
exampleactive

Filter rules by status (active or archived). When omitted, rules of any status are returned.

Must be one of:activearchived
traffic_direction
string
Defaultoutbound
exampleoutbound

Find rules for a specific traffic direction

Must be one of:outboundinbound
show_default_rules
boolean
Defaulttrue

Defines whether to display default rules or not

show_custom_rules
boolean
Defaulttrue

Defines whether to display custom rules or not

sort
string
exampleprefix

Sort by product, prefix or traffic, case-insensitively. When omitted, rules are sorted by creation time.

Must be one of:prefixproducttraffic
order
string
Defaultdesc

Sort order (asc or desc), case-insensitively

Must be one of:ascdesc
page
integer
Min1
Default1

Page number.

page_size
integer
Min1
Max150
Default100

Number of items per page

Responses
Content Type
application/json

Successfully retrieved prefix rules

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
page
integer
Required
Min1
Default1
example1

The current page

page_size
integer
Required
Min1
Default10
example20

The size of the page

total_items
integer
Required
example871

The total number of items in the resource list

total_pages
integer
Required
Min1
example42

Total number of pages

_embedded
object
entries
array
id
string
Required
example3efc212bc3f5482db6cdece03325ddc7

Unique ID of the prefix traffic rule

product
string
Required
examplesms

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
prefix
string
Required
Max16
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. A leading + and any whitespace are removed before the rule is stored.

direction
string
Required
exampleto

Part of the traffic the prefix is matched against. to matches the destination number, from matches the originating number. It is derived from the traffic direction of the rule.

Must be one of:tofrom
traffic_direction
string
Required
Defaultoutbound
exampleoutbound

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

Must be one of:outboundinbound
action
string
Required
Defaultblock
exampleblock

Action applied to the traffic matching the rule

Must be one of:blockallow
reason
string
Required
Min1
Max256
examplereason for block

Human readable reason. Commas and new lines are replaced with spaces.

permission
string
Required
exampleedit

What can be done with the rule. edit - the rule can be updated and archived, view - the rule is read-only, locked - the rule is read-only and cannot be overridden by another rule.

Must be one of:editviewlocked
status
string
Required
exampleactive

Status of the prefix traffic rule

Must be one of:activearchived
created_timestamp
string
Required
example2025-07-01T10:11:22

Date and time when the rule was created, in yyyy-MM-dd'T'HH:mm:ss format in UTC timezone

updated_timestamp
string
example2025-07-02T09:15:43

Date and time when the rule was last updated, in yyyy-MM-dd'T'HH:mm:ss format in UTC timezone. Omitted when the rule has never been updated.

archived_timestamp
string
example2025-07-03T14:20:05

Date and time when the rule was archived, in yyyy-MM-dd'T'HH:mm:ss format in UTC timezone. Omitted when the rule is active.

_links
object
Required

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 for page-based paginated collections

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

first
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

prev
object

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

next
object

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

last
object

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

Create a new prefix traffic rule

Creates a new traffic rule based on a phone number prefix. A rule that duplicates an already existing one is rejected with a 409 response.

posthttps://api.nexmo.com/v2/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

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
prefix
string
Required
Max16
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. A leading + and any whitespace are removed before the rule is stored.

reason
string
Required
Min1
Max256
examplereason for block

Human readable reason. Commas and new lines are replaced with spaces.

action
string
Defaultblock
exampleblock

Action applied to the traffic matching the rule

Must be one of:blockallow
traffic_direction
string
Defaultoutbound
exampleoutbound

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

Must be one of:outboundinbound

Example Request

Responses
Content Type
application/json

Rule created

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
id
string
Required
example3efc212bc3f5482db6cdece03325ddc7

Unique ID of the prefix traffic rule

product
string
Required
examplesms

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
prefix
string
Required
Max16
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. A leading + and any whitespace are removed before the rule is stored.

direction
string
Required
exampleto

Part of the traffic the prefix is matched against. to matches the destination number, from matches the originating number. It is derived from the traffic direction of the rule.

Must be one of:tofrom
traffic_direction
string
Required
Defaultoutbound
exampleoutbound

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

Must be one of:outboundinbound
action
string
Required
Defaultblock
exampleblock

Action applied to the traffic matching the rule

Must be one of:blockallow
reason
string
Required
Min1
Max256
examplereason for block

Human readable reason. Commas and new lines are replaced with spaces.

permission
string
Required
exampleedit

What can be done with the rule. edit - the rule can be updated and archived, view - the rule is read-only, locked - the rule is read-only and cannot be overridden by another rule.

Must be one of:editviewlocked
status
string
Required
exampleactive

Status of the prefix traffic rule

Must be one of:activearchived
created_timestamp
string
Required
example2025-07-01T10:11:22

Date and time when the rule was created, in yyyy-MM-dd'T'HH:mm:ss format in UTC timezone

updated_timestamp
string
example2025-07-02T09:15:43

Date and time when the rule was last updated, in yyyy-MM-dd'T'HH:mm:ss format in UTC timezone. Omitted when the rule has never been updated.

archived_timestamp
string
example2025-07-03T14:20:05

Date and time when the rule was archived, in yyyy-MM-dd'T'HH:mm:ss format in UTC timezone. Omitted when the rule is active.

_links
object
Required

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

Retrieve a prefix traffic rule

Returns a specific prefix traffic rule identified by id.

gethttps://api.nexmo.com/v2/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
example3efc212bc3f5482db6cdece03325ddc7

Unique ID of the prefix traffic rule, as returned in the id field when the rule was created.

Responses
Content Type
application/json

Successfully retrieved the prefix rule

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
id
string
Required
example3efc212bc3f5482db6cdece03325ddc7

Unique ID of the prefix traffic rule

product
string
Required
examplesms

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
prefix
string
Required
Max16
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. A leading + and any whitespace are removed before the rule is stored.

direction
string
Required
exampleto

Part of the traffic the prefix is matched against. to matches the destination number, from matches the originating number. It is derived from the traffic direction of the rule.

Must be one of:tofrom
traffic_direction
string
Required
Defaultoutbound
exampleoutbound

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

Must be one of:outboundinbound
action
string
Required
Defaultblock
exampleblock

Action applied to the traffic matching the rule

Must be one of:blockallow
reason
string
Required
Min1
Max256
examplereason for block

Human readable reason. Commas and new lines are replaced with spaces.

permission
string
Required
exampleedit

What can be done with the rule. edit - the rule can be updated and archived, view - the rule is read-only, locked - the rule is read-only and cannot be overridden by another rule.

Must be one of:editviewlocked
status
string
Required
exampleactive

Status of the prefix traffic rule

Must be one of:activearchived
created_timestamp
string
Required
example2025-07-01T10:11:22

Date and time when the rule was created, in yyyy-MM-dd'T'HH:mm:ss format in UTC timezone

updated_timestamp
string
example2025-07-02T09:15:43

Date and time when the rule was last updated, in yyyy-MM-dd'T'HH:mm:ss format in UTC timezone. Omitted when the rule has never been updated.

archived_timestamp
string
example2025-07-03T14:20:05

Date and time when the rule was archived, in yyyy-MM-dd'T'HH:mm:ss format in UTC timezone. Omitted when the rule is active.

_links
object
Required

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

Update an existing prefix traffic rule

Updates the details of a specific prefix traffic rule identified by id. Only the reason for the rule can be modified. Rules with a permission other than edit cannot be modified and are rejected with a 400 response.

patchhttps://api.nexmo.com/v2/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
example3efc212bc3f5482db6cdece03325ddc7

Unique ID of the prefix traffic rule, as returned in the id field when the rule was created.

Request Body
Content Type
application/json

reason
string
Required
Min1
Max256
examplereason for block

Human readable reason. Commas and new lines are replaced with spaces.

Example Request

Responses
Content Type
application/json

Rule updated

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
id
string
Required
example3efc212bc3f5482db6cdece03325ddc7

Unique ID of the prefix traffic rule

product
string
Required
examplesms

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
prefix
string
Required
Max16
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. A leading + and any whitespace are removed before the rule is stored.

direction
string
Required
exampleto

Part of the traffic the prefix is matched against. to matches the destination number, from matches the originating number. It is derived from the traffic direction of the rule.

Must be one of:tofrom
traffic_direction
string
Required
Defaultoutbound
exampleoutbound

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

Must be one of:outboundinbound
action
string
Required
Defaultblock
exampleblock

Action applied to the traffic matching the rule

Must be one of:blockallow
reason
string
Required
Min1
Max256
examplereason for block

Human readable reason. Commas and new lines are replaced with spaces.

permission
string
Required
exampleedit

What can be done with the rule. edit - the rule can be updated and archived, view - the rule is read-only, locked - the rule is read-only and cannot be overridden by another rule.

Must be one of:editviewlocked
status
string
Required
exampleactive

Status of the prefix traffic rule

Must be one of:activearchived
created_timestamp
string
Required
example2025-07-01T10:11:22

Date and time when the rule was created, in yyyy-MM-dd'T'HH:mm:ss format in UTC timezone

updated_timestamp
string
example2025-07-02T09:15:43

Date and time when the rule was last updated, in yyyy-MM-dd'T'HH:mm:ss format in UTC timezone. Omitted when the rule has never been updated.

archived_timestamp
string
example2025-07-03T14:20:05

Date and time when the rule was archived, in yyyy-MM-dd'T'HH:mm:ss format in UTC timezone. Omitted when the rule is active.

_links
object
Required

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

Archive a prefix traffic rule

Marks a specific prefix traffic rule identified by id as archived. Archived rules are no longer active in the fraud detection flow and can be retrieved using the GET endpoint with the filter status=archived. Rules with a permission other than edit and rules that are already archived cannot be archived and are rejected with a 400 response.

deletehttps://api.nexmo.com/v2/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
example3efc212bc3f5482db6cdece03325ddc7

Unique ID of the prefix traffic rule, as returned in the id field when the rule was created.

Responses

Rule archived (no content returned)

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging

Retrieve all network traffic rules

Returns a paginated list of network rules. Network rules define blocking rules for specific mobile networks within countries.

gethttps://api.nexmo.com/v2/fraud-defender/rules/networks

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Query Parameters

product
string
exampleSMS

Find rules for a specific product

Must be one of:SMSVOICE
mcc
string
example234

Find rules for a specific Mobile Country Code (MCC)

country_code
string
exampleGB

Find rules for a specific ISO country code - alternative to MCC for identifying country

network_name
string
exampleVodafone UK

Find rules for a specific network name.

plmn
string
example23401

Find rules for a specific public land mobile network (PLMN). Valid only with status=active, otherwise returns 400 error.

expire_start_date
string(date)
example2025-08-26

Find rules that expire on or after a specific date (YYYY-MM-DD) in UTC timezone. Valid only with status=active, otherwise returns 400 error.

expire_end_date
string(date)
example2025-08-26

Find rules that expire on or before a specific date (YYYY-MM-DD) in UTC timezone. Valid only with status=active, otherwise returns 400 error.

ttl
string
example1d

Find rules by time to live (TTL). Valid only with status=active, otherwise returns 400 error.

Must be one of:PERMANENT1d12h6h3h2h1h
sort
string
Defaultcreated_at
examplecreated_at

Sort by field (product, mcc, country_code, network_name, created_at, expires_at)

Must be one of:productmcccountry_codenetwork_namecreated_atexpires_at
status
string
Defaultactive
exampleactive

Filter by rule status (active or archived).

Must be one of:activearchived
order
string
Defaultdesc

Sort order (asc or desc)

Must be one of:ascdesc
page
integer
Min1
Default1

Page number.

page_size
integer
Min1
Max100
Default10

Number of items per page

Responses
Content Type
application/json

Successfully retrieved network rules

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
_embedded
object
rules
array
Required
id
string(uuid)
Required
example3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb

Unique ID of the traffic rule

product
string
Required
exampleSMS

Product type for the traffic rule

Must be one of:SMSVOICE
mcc
string
Required
example234

Mobile Country Code

network_name
string
Required
exampleVodafone UK

Network name

plmns
array
Required
reason
string
Required
Min1
Max256
examplereason for blocks

Reason for the traffic rule action

expires_at
string(date-time)
example2025-08-01T10:11:22Z

Timestamp when the rule expires (null for permanent rules) in UTC timezone

created_at
string(date-time)
Required
example2025-07-01T10:11:22Z

Timestamp when the rule was created

ttl
string
Required
example1d

Time to live for the traffic rule. After this period, the rule will expire and no longer block traffic.

Must be one of:PERMANENT1d12h6h3h2h1h
archived_at
string(date-time)
example2025-08-02T10:11:22Z

Timestamp when the rule was archived in UTC timezone, null if the rule is active

_links
object
Required

HAL links for page-based paginated collections

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

first
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

prev
object

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

next
object

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

last
object

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
integer
Required
Min1
Default1
example1

The current page

page_size
integer
Required
Min1
Default10
example20

The size of the page

total_items
integer
Required
example871

The total number of items in the resource list

total_pages
integer
Required
Min1
example42

Total number of pages

Example Response

Create a new traffic rule for a network

Create a new traffic rule for a network.

posthttps://api.nexmo.com/v2/fraud-defender/rules/networks

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

Product type for the traffic rule

Must be one of:SMSVOICE
plmn
string
Required
example23401

Unique network identifier consisting of Mobile Country Code (MCC) and Mobile Network Code (MNC) with no separators in between

reason
string
Required
Min1
Max256
examplereason for blocks

Reason for the traffic rule action

ttl
string
Required
example1d

Time to live for the traffic rule. After this period, the rule will expire and no longer block traffic.

Must be one of:PERMANENT1d12h6h3h2h1h

Example Request

Responses
Content Type
application/json

Rule created

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
id
string(uuid)
Required
example3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb

Unique ID of the traffic rule

product
string
Required
exampleSMS

Product type for the traffic rule

Must be one of:SMSVOICE
mcc
string
Required
example234

Mobile Country Code

network_name
string
Required
exampleVodafone UK

Network name

plmns
array
Required
reason
string
Required
Min1
Max256
examplereason for blocks

Reason for the traffic rule action

expires_at
string(date-time)
example2025-08-01T10:11:22Z

Timestamp when the rule expires (null for permanent rules) in UTC timezone

created_at
string(date-time)
Required
example2025-07-01T10:11:22Z

Timestamp when the rule was created

ttl
string
Required
example1d

Time to live for the traffic rule. After this period, the rule will expire and no longer block traffic.

Must be one of:PERMANENT1d12h6h3h2h1h

Example Response

Update an existing network traffic rule

Updates the details of a specific network traffic rule identified by id. Only the reason for the rule can be modified.

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

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

id
string(uuid)
Required
example3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb

Unique ID of the network traffic rule, as returned in the id field when the rule was created.

Request Body
Content Type
application/json

reason
string
Required
Min1
Max256
examplereason for blocks

Reason for the traffic rule action

Example Request

Responses
Content Type
application/json

Rule updated

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
id
string(uuid)
Required
example3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb

Unique ID of the traffic rule

product
string
Required
exampleSMS

Product type for the traffic rule

Must be one of:SMSVOICE
mcc
string
Required
example234

Mobile Country Code

network_name
string
Required
exampleVodafone UK

Network name

plmns
array
Required
reason
string
Required
Min1
Max256
examplereason for blocks

Reason for the traffic rule action

expires_at
string(date-time)
example2025-08-01T10:11:22Z

Timestamp when the rule expires (null for permanent rules) in UTC timezone

created_at
string(date-time)
Required
example2025-07-01T10:11:22Z

Timestamp when the rule was created

ttl
string
Required
example1d

Time to live for the traffic rule. After this period, the rule will expire and no longer block traffic.

Must be one of:PERMANENT1d12h6h3h2h1h

Example Response

Archive a network rule

Archives a specific network traffic rule identified by id. Archived rules become inactive and no longer block traffic. Still, a maximum of 50 archived rules remain accessible during 90 days for record-keeping and can be retrieved using the GET endpoint with the filter status=archived.

deletehttps://api.nexmo.com/v2/fraud-defender/rules/networks/:id

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

id
string(uuid)
Required
example3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb

Unique ID of the network traffic rule, as returned in the id field when the rule was created.

Responses

Rule archived (no content returned)

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging

Retrieve all country traffic rules

Returns a complete list of country rules. Country rules define which country-product combinations should have their traffic blocked.

gethttps://api.nexmo.com/v2/fraud-defender/rules/countries

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Responses
Content Type
application/json

A complete list of country-based traffic rules

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
rules
array
Required

Complete list of country rules defining which country-product combinations should have their traffic blocked.

product
string
Required
exampleSMS

Product type for the traffic rule

Must be one of:SMSVOICE
country_code
string
Required
exampleGB

Country code (ISO 3166-1 Alpha-2)

_links
object
Required

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

Replace country rules

Replaces the country rules with the provided list. Country rules define which country-product combinations should have their traffic blocked. The rules array must always contain a complete list of rules - any existing rules not present in this request will be removed.

puthttps://api.nexmo.com/v2/fraud-defender/rules/countries

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Request Body
Content Type
application/json

rules
array
Required

Complete list of country rules which should block the traffic. Any existing rules not present in this array will be removed.

product
string
Required
exampleSMS

Product type for the traffic rule

Must be one of:SMSVOICE
country_code
string
Required
exampleGB

Country code (ISO 3166-1 Alpha-2)

Example Request

Responses
Content Type
application/json

Successfully replaced country rules

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
rules
array
Required

Complete list of country rules defining which country-product combinations should have their traffic blocked.

product
string
Required
exampleSMS

Product type for the traffic rule

Must be one of:SMSVOICE
country_code
string
Required
exampleGB

Country code (ISO 3166-1 Alpha-2)

Example Response

Retrieve all supported countries

Retrieves all supported countries along with their risk levels for fraud detection.

gethttps://api.nexmo.com/v2/fraud-defender/countries

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Responses
Content Type
application/json

Successfully retrieved country data

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
countries
array
Required

Complete list of supported countries with their risk levels

country_code
string
Required
examplePL

Country code (ISO 3166-1 Alpha-2)

continent
string
Required
exampleEU

Continent code to which the country belongs:

  • AF - Africa
  • AN - Antarctica
  • AS - Asia
  • EU - Europe
  • NA - North America
  • OC - Oceania
  • SA - South America
Must be one of:AFANASEUNAOCSA
risk
string
DefaultNONE
exampleHIGH

Risk level for fraud detection. When not specified, defaults to NONE. Countries with HIGH risk will have their traffic blocked by default.

Must be one of:NONEHIGH
_links
object
Required

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

AIT Protection

Operations to manage AIT Protection.

Get AIT configuration

Retrieve the current AIT protection configuration for a given product.

gethttps://api.nexmo.com/v2/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. Only sms is supported; any other value returns a 400 error.

Must be one of:sms

Responses
Content Type
application/json

AIT protection config response

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
data
object

AIT protection configuration. default_protection_level is required when protection_enabled is true; omitting it returns a 400 error.

protection_enabled
boolean
Required
exampletrue

used to turn on/off AIT protection

default_protection_level
string
examplestandard

Default AIT protection level, used for countries with no specific per-country configuration. Required when protection_enabled is true. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:highstandardnone
protection_level_per_country
array

Per-country AIT protection level overrides. Countries not listed here use default_protection_level.

country
string
Required
exampleUS

Country code in ISO 3166-1 Alpha-2 standard. Must be a supported country.

protection_level
string
Required
examplehigh

AIT protection level for this country. Values are matched case-insensitively; responses always return the lower-case form.

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

Create or update AIT configuration

Enable or modify AIT protection settings globally or per country.

puthttps://api.nexmo.com/v2/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. Only sms is supported; any other value returns a 400 error.

Must be one of:sms

Request Body
Content Type
application/json

data
object
Required

AIT protection configuration. default_protection_level is required when protection_enabled is true; omitting it returns a 400 error.

protection_enabled
boolean
Required
exampletrue

used to turn on/off AIT protection

default_protection_level
string
examplestandard

Default AIT protection level, used for countries with no specific per-country configuration. Required when protection_enabled is true. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:highstandardnone
protection_level_per_country
array

Per-country AIT protection level overrides. Countries not listed here use default_protection_level.

country
string
Required
exampleUS

Country code in ISO 3166-1 Alpha-2 standard. Must be a supported country.

protection_level
string
Required
examplehigh

AIT protection level for this country. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:highstandardnone

Example Request

Responses
Content Type
application/json

AIT protection config response

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
data
object

AIT protection configuration. default_protection_level is required when protection_enabled is true; omitting it returns a 400 error.

protection_enabled
boolean
Required
exampletrue

used to turn on/off AIT protection

default_protection_level
string
examplestandard

Default AIT protection level, used for countries with no specific per-country configuration. Required when protection_enabled is true. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:highstandardnone
protection_level_per_country
array

Per-country AIT protection level overrides. Countries not listed here use default_protection_level.

country
string
Required
exampleUS

Country code in ISO 3166-1 Alpha-2 standard. Must be a supported country.

protection_level
string
Required
examplehigh

AIT protection level for this country. Values are matched case-insensitively; responses always return the lower-case form.

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

Custom Fraud Alerts

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

List custom fraud alerts

Retrieve a paginated list of custom fraud alerts for the product specified by identifier (SMS or VOICE).

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

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

identifier
string
Required
examplesms

Product to list custom fraud alerts for. Matched case-insensitively.

Must be one of:voicesms

Query Parameters

page_size
integer
Min1
Default10
example20

Page size in Integer format

page
integer
Min1
Default1
example1

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

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
page
integer
Required
Min1
Default1
example1

The current page

page_size
integer
Required
Min1
Default10
example20

The size of the page

total_items
integer
Required
example871

The total number of items in the resource list

total_pages
integer
Required
Min1
example42

Total number of pages

_embedded
object
Required
entries
array
Required
country
string
exampleGB
interval
integer(int32)
example60
threshold
integer(int32)
example100
product
string
examplesms

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
id
string(uuid)
exampleabcdef01-2345-6789-abcd-ef0123456789

Unique ID of the custom fraud alert.

_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
Required

HAL links for page-based paginated collections

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

first
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

prev
object

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

next
object

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

last
object

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

Edit custom fraud alert by ID

Replace the custom fraud alert identified by the UUID identifier.

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

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

identifier
string(uuid)
Required
exampleabcdef01-2345-6789-abcd-ef0123456789

Custom fraud alert ID in UUID format.

Request Body
Content Type
application/json

product
string
examplesms

Product type. Values are matched case-insensitively; responses always return the lower-case form.

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

Responses
Content Type
application/json

OK

ヘッダー 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

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
id
string(uuid)
exampleabcdef01-2345-6789-abcd-ef0123456789

Unique ID of the custom fraud alert.

_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

Create custom fraud alert

Create a custom fraud alert for the supplied product, country, threshold, and interval.

posthttps://api.nexmo.com/v2/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. Values are matched case-insensitively; responses always return the lower-case form.

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

Responses
Content Type
application/json

OK

ヘッダー 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

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
id
string(uuid)
exampleabcdef01-2345-6789-abcd-ef0123456789

Unique ID of the custom fraud alert.

_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

Get custom fraud alert by product and id

Retrieve a custom fraud alert by its product and ID.

gethttps://api.nexmo.com/v2/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
examplesms

Product the custom fraud alert belongs to. Matched case-insensitively.

Must be one of:voicesms
id
string(uuid)
Required
exampleabcdef01-2345-6789-abcd-ef0123456789

Custom fraud alert ID in UUID format.

Responses
Content Type
application/json

OK

ヘッダー 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

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
id
string(uuid)
exampleabcdef01-2345-6789-abcd-ef0123456789

Unique ID of the custom fraud alert.

_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

Delete custom fraud alert by ID

Delete a custom fraud alert by its product and ID.

deletehttps://api.nexmo.com/v2/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
examplesms

Product the custom fraud alert belongs to. Matched case-insensitively.

Must be one of:voicesms
id
string(uuid)
Required
exampleabcdef01-2345-6789-abcd-ef0123456789

Custom fraud alert ID in UUID format.

Responses

No Content - Resource successfully deleted

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging

Alert Actions

Operations to manage the configurations that determine how fraud alerts are actioned.

List alert actions

List the alert action configurations.

gethttps://api.nexmo.com/v2/fraud-defender/alerts/actions

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Query Parameters

page
integer
Min1
Default1
example1

Page number in Integer format

page_size
integer
Min1
Default10
example20

Page size in Integer format

Responses
Content Type
application/json

A paginated collection of alert action configurations.

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
page
integer
Required
Min1
Default1
example1

The current page

page_size
integer
Required
Min1
Default10
example20

The size of the page

total_items
integer
Required
example871

The total number of items in the resource list

total_pages
integer
Required
Min1
example42

Total number of pages

_embedded
object

The embedded resources for this page.

entries
array

The alert action configurations contained in this page.

id
string
example4acf401c-91de-47a6-9f36-6e1e8ad4aacc

Unique identifier of the alert action configuration.

fraud_alert_type
string
Required
examplecustom

The type of fraud the configuration applies to.

Must be one of:volumetric_changesait_protectioncustomnetwork_volume
product
string
Required
examplesms

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
value
integer(int64)
Required
example1000

Severity metric threshold from which this configuration applies. When several configurations match an alert, the one with the highest threshold not exceeding the alert severity is used.

monitoring_interval_in_minutes
integer(int64)
Required
example60

Length in minutes of the window over which traffic is aggregated before the threshold is evaluated.

Must be one of:15304560360720
notification_level
string
Defaultnone
examplenormal

The notification level applied to a matching fraud alert. When not specified, defaults to none, meaning no notification is sent. The values low and high are deprecated; they are accepted but applied as normal.

Must be one of:nonelownormalhigh
action_type
string
Required
exampleblock

The action applied to a matching fraud alert. review leaves the alert awaiting a decision by the customer; block blocks the offending traffic automatically; none records the alert without blocking.

Must be one of:noneblockreview
countries
array
Required

Destination countries this configuration applies to, as ISO 3166-1 alpha-2 codes. Use the single value ALL to apply it to every country. A country may only appear in one configuration per combination of fraud_alert_type, product and value.

block_duration
string
example1d

How long a block remains in effect. PERMANENT blocks indefinitely until the customer removes it; other values block for the given duration. Only meaningful for network alerts (fraud_alert_type set to network_volume). Required when action_type is block.

Must be one of:PERMANENT1d12h6h3h2h1h
_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 for page-based paginated collections

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

first
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

prev
object

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

next
object

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

last
object

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": 1,
   "page_size": 20,
   "total_items": 871,
   "total_pages": 42,
   "_embedded": {
      "entries": [
         {
            "id": "4acf401c-91de-47a6-9f36-6e1e8ad4aacc",
            "fraud_alert_type": "custom",
            "product": "sms",
            "value": 1000,
            "monitoring_interval_in_minutes": 60,
            "notification_level": "normal",
            "action_type": "block",
            "countries": [
               "ALL"
            ],
            "block_duration": "1d",
            "_links": {
               "self": {
                  "href": "https://api.vonage.com/v1/resources/abc123",
                  "templated": false,
                  "type": "application/json",
                  "name": "resource-name",
                  "title": "Resource Title"
               }
            }
         }
      ]
   },
   "_links": {
      "first": {
         "href": "https://api.nexmo.com/v2/fraud-defender/alerts/actions?page=1&page_size=100"
      },
      "last": {
         "href": "https://api.nexmo.com/v2/fraud-defender/alerts/actions?page=4&page_size=100"
      },
      "prev": {
         "href": "https://api.nexmo.com/v2/fraud-defender/alerts/actions?page=1&page_size=100"
      },
      "self": null
   }
}

Create an alert action

Create an alert action configuration.

posthttps://api.nexmo.com/v2/fraud-defender/alerts/actions

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Request Body
Content Type
application/json

fraud_alert_type
string
Required
examplecustom

The type of fraud the configuration applies to.

Must be one of:volumetric_changesait_protectioncustomnetwork_volume
product
string
Required
examplesms

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
value
integer(int64)
Required
example1000

Severity metric threshold from which this configuration applies. When several configurations match an alert, the one with the highest threshold not exceeding the alert severity is used.

monitoring_interval_in_minutes
integer(int64)
Required
example60

Length in minutes of the window over which traffic is aggregated before the threshold is evaluated.

Must be one of:15304560360720
notification_level
string
Defaultnone
examplenormal

The notification level applied to a matching fraud alert. When not specified, defaults to none, meaning no notification is sent. The values low and high are deprecated; they are accepted but applied as normal.

Must be one of:nonelownormalhigh
action_type
string
Required
exampleblock

The action applied to a matching fraud alert. review leaves the alert awaiting a decision by the customer; block blocks the offending traffic automatically; none records the alert without blocking.

Must be one of:noneblockreview
countries
array
Required

Destination countries this configuration applies to, as ISO 3166-1 alpha-2 codes. Use the single value ALL to apply it to every country. A country may only appear in one configuration per combination of fraud_alert_type, product and value.

block_duration
string
example1d

How long a block remains in effect. PERMANENT blocks indefinitely until the customer removes it; other values block for the given duration. Only meaningful for network alerts (fraud_alert_type set to network_volume). Required when action_type is block.

Must be one of:PERMANENT1d12h6h3h2h1h

Example Request

Responses
Content Type
application/json

A single alert action configuration.

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
id
string
example4acf401c-91de-47a6-9f36-6e1e8ad4aacc

Unique identifier of the alert action configuration.

fraud_alert_type
string
Required
examplecustom

The type of fraud the configuration applies to.

Must be one of:volumetric_changesait_protectioncustomnetwork_volume
product
string
Required
examplesms

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
value
integer(int64)
Required
example1000

Severity metric threshold from which this configuration applies. When several configurations match an alert, the one with the highest threshold not exceeding the alert severity is used.

monitoring_interval_in_minutes
integer(int64)
Required
example60

Length in minutes of the window over which traffic is aggregated before the threshold is evaluated.

Must be one of:15304560360720
notification_level
string
Defaultnone
examplenormal

The notification level applied to a matching fraud alert. When not specified, defaults to none, meaning no notification is sent. The values low and high are deprecated; they are accepted but applied as normal.

Must be one of:nonelownormalhigh
action_type
string
Required
exampleblock

The action applied to a matching fraud alert. review leaves the alert awaiting a decision by the customer; block blocks the offending traffic automatically; none records the alert without blocking.

Must be one of:noneblockreview
countries
array
Required

Destination countries this configuration applies to, as ISO 3166-1 alpha-2 codes. Use the single value ALL to apply it to every country. A country may only appear in one configuration per combination of fraud_alert_type, product and value.

block_duration
string
example1d

How long a block remains in effect. PERMANENT blocks indefinitely until the customer removes it; other values block for the given duration. Only meaningful for network alerts (fraud_alert_type set to network_volume). Required when action_type is block.

Must be one of:PERMANENT1d12h6h3h2h1h
_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

Get an alert action

Retrieve an alert action configuration by its unique identifier.

gethttps://api.nexmo.com/v2/fraud-defender/alerts/actions/:id

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

id
string
Required
example4acf401c-91de-47a6-9f36-6e1e8ad4aacc

Unique identifier of the alert action configuration.

Responses
Content Type
application/json

A single alert action configuration.

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
id
string
example4acf401c-91de-47a6-9f36-6e1e8ad4aacc

Unique identifier of the alert action configuration.

fraud_alert_type
string
Required
examplecustom

The type of fraud the configuration applies to.

Must be one of:volumetric_changesait_protectioncustomnetwork_volume
product
string
Required
examplesms

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
value
integer(int64)
Required
example1000

Severity metric threshold from which this configuration applies. When several configurations match an alert, the one with the highest threshold not exceeding the alert severity is used.

monitoring_interval_in_minutes
integer(int64)
Required
example60

Length in minutes of the window over which traffic is aggregated before the threshold is evaluated.

Must be one of:15304560360720
notification_level
string
Defaultnone
examplenormal

The notification level applied to a matching fraud alert. When not specified, defaults to none, meaning no notification is sent. The values low and high are deprecated; they are accepted but applied as normal.

Must be one of:nonelownormalhigh
action_type
string
Required
exampleblock

The action applied to a matching fraud alert. review leaves the alert awaiting a decision by the customer; block blocks the offending traffic automatically; none records the alert without blocking.

Must be one of:noneblockreview
countries
array
Required

Destination countries this configuration applies to, as ISO 3166-1 alpha-2 codes. Use the single value ALL to apply it to every country. A country may only appear in one configuration per combination of fraud_alert_type, product and value.

block_duration
string
example1d

How long a block remains in effect. PERMANENT blocks indefinitely until the customer removes it; other values block for the given duration. Only meaningful for network alerts (fraud_alert_type set to network_volume). Required when action_type is block.

Must be one of:PERMANENT1d12h6h3h2h1h
_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

Update an alert action

Replace an alert action configuration.

puthttps://api.nexmo.com/v2/fraud-defender/alerts/actions/:id

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

id
string
Required
example4acf401c-91de-47a6-9f36-6e1e8ad4aacc

Unique identifier of the alert action configuration.

Request Body
Content Type
application/json

fraud_alert_type
string
Required
examplecustom

The type of fraud the configuration applies to.

Must be one of:volumetric_changesait_protectioncustomnetwork_volume
product
string
Required
examplesms

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
value
integer(int64)
Required
example1000

Severity metric threshold from which this configuration applies. When several configurations match an alert, the one with the highest threshold not exceeding the alert severity is used.

monitoring_interval_in_minutes
integer(int64)
Required
example60

Length in minutes of the window over which traffic is aggregated before the threshold is evaluated.

Must be one of:15304560360720
notification_level
string
Defaultnone
examplenormal

The notification level applied to a matching fraud alert. When not specified, defaults to none, meaning no notification is sent. The values low and high are deprecated; they are accepted but applied as normal.

Must be one of:nonelownormalhigh
action_type
string
Required
exampleblock

The action applied to a matching fraud alert. review leaves the alert awaiting a decision by the customer; block blocks the offending traffic automatically; none records the alert without blocking.

Must be one of:noneblockreview
countries
array
Required

Destination countries this configuration applies to, as ISO 3166-1 alpha-2 codes. Use the single value ALL to apply it to every country. A country may only appear in one configuration per combination of fraud_alert_type, product and value.

block_duration
string
example1d

How long a block remains in effect. PERMANENT blocks indefinitely until the customer removes it; other values block for the given duration. Only meaningful for network alerts (fraud_alert_type set to network_volume). Required when action_type is block.

Must be one of:PERMANENT1d12h6h3h2h1h

Example Request

Responses
Content Type
application/json

A single alert action configuration.

ヘッダー Parameters
X-Request-Id
string(uuid)
examplef94b4e56-604e-07e5-e5ad-5a7228618f81
A unique identifier for the request, used for tracking and debugging
id
string
example4acf401c-91de-47a6-9f36-6e1e8ad4aacc

Unique identifier of the alert action configuration.

fraud_alert_type
string
Required
examplecustom

The type of fraud the configuration applies to.

Must be one of:volumetric_changesait_protectioncustomnetwork_volume
product
string
Required
examplesms

Product type. Values are matched case-insensitively; responses always return the lower-case form.

Must be one of:voicesms
value
integer(int64)
Required
example1000

Severity metric threshold from which this configuration applies. When several configurations match an alert, the one with the highest threshold not exceeding the alert severity is used.

monitoring_interval_in_minutes
integer(int64)
Required
example60

Length in minutes of the window over which traffic is aggregated before the threshold is evaluated.

Must be one of:15304560360720
notification_level
string
Defaultnone
examplenormal

The notification level applied to a matching fraud alert. When not specified, defaults to none, meaning no notification is sent. The values low and high are deprecated; they are accepted but applied as normal.

Must be one of:nonelownormalhigh
action_type
string
Required
exampleblock

The action applied to a matching fraud alert. review leaves the alert awaiting a decision by the customer; block blocks the offending traffic automatically; none records the alert without blocking.

Must be one of:noneblockreview
countries
array
Required

Destination countries this configuration applies to, as ISO 3166-1 alpha-2 codes. Use the single value ALL to apply it to every country. A country may only appear in one configuration per combination of fraud_alert_type, product and value.

block_duration
string
example1d

How long a block remains in effect. PERMANENT blocks indefinitely until the customer removes it; other values block for the given duration. Only meaningful for network alerts (fraud_alert_type set to network_volume). Required when action_type is block.

Must be one of:PERMANENT1d12h6h3h2h1h
_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

Delete an alert action

Delete an alert action configuration.

deletehttps://api.nexmo.com/v2/fraud-defender/alerts/actions/:id

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

id
string
Required
example4acf401c-91de-47a6-9f36-6e1e8ad4aacc

Unique identifier of the alert action configuration.

Responses

No Content - Resource successfully deleted

ヘッダー 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.

CodeInformation
http:error:conflict

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

http:error:validation-fail

There was an issue when validating the request. Please refer to the API specs

not-found

No rule was found against the passed rule id

system:error:internal-error

Something went wrong.