Fraud Prevention API

Version 2

The Fraud Prevention API is a set of APIs supporting Fraud detection including managing own fraud rules.

Download OpenAPI Specification

利用可能な業務

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

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

networks

array

Required

List of networks

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

Required

self

object

Required

href

string

Required

URL to the resource

Example Response

{
   "networks": [
      {
         "name": "Vodafone UK",
         "mcc": "234",
         "country_code": "GB",
         "plmns": [
            "23401",
            "23402"
         ]
      }
   ],
   "_links": {
      "self": {
         "href": "string"
      }
   }
}

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

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

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

_embedded

object

Required

rules

array

Required

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

examplereason for blocks

Reason for the traffic rule action

expires_at

string(date-time)

example2025-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

created_at

string(date-time)

Required

example2025-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

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-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

_links

object

Required

object

href

string

Required

URL to the resource

object

href

string

Required

URL to the resource

self

object

Required

href

string

Required

URL to the resource

page

integer

Required

Min1

Current page number

page_size

integer

Required

Min1

Number of items per page

total_items

integer

Required

Total number of elements across all pages

total_pages

integer

Required

Total number of pages

Example Response

{
   "_embedded": {
      "rules": [
         {
            "product": "SMS",
            "mcc": "234",
            "network_name": "Vodafone UK",
            "plmns": [
               "23477",
               "23491"
            ],
            "reason": "reason for blocks",
            "expires_at": "2025-08-01T10:11:22Z",
            "created_at": "2025-07-01T10:11:22Z",
            "ttl": "1d",
            "id": "3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb",
            "archived_at": "2025-07-01T10:11:22Z"
         }
      ]
   },
   "_links": {
      "next": {
         "href": "string"
      },
      "prev": {
         "href": "string"
      },
      "self": {
         "href": "string"
      }
   },
   "page": 1,
   "page_size": 1,
   "total_items": 0,
   "total_pages": 0
}

Create a new traffic rule for a network

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

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

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

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

{
   "product": "SMS",
   "plmn": "23401",
   "reason": "reason for blocks",
   "ttl": "1d"
}

{
   "product": "SMS",
   "plmn": "23401",
   "reason": "reason for blocks",
   "ttl": "1d"
}

Responses
Content Type
application/json

Rule created

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

examplereason for blocks

Reason for the traffic rule action

expires_at

string(date-time)

example2025-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

created_at

string(date-time)

Required

example2025-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

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

{
   "id": "3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb",
   "product": "SMS",
   "mcc": "234",
   "network_name": "Vodafone UK",
   "plmns": [
      "23401"
   ],
   "reason": "reason for blocks",
   "expires_at": "string",
   "created_at": "string",
   "ttl": "1d"
}

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

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

Path Parameters

string(uuid)

Required

example3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb

Request Body
Content Type
application/json

reason

string

Required

examplereason for blocks

Reason for the traffic rule action

Example Request

{
   "reason": "reason for blocks"
}

{
   "reason": "reason for blocks"
}

Responses
Content Type
application/json

Rule updated

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

examplereason for blocks

Reason for the traffic rule action

expires_at

string(date-time)

example2025-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

created_at

string(date-time)

Required

example2025-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

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

{
   "id": "3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb",
   "product": "SMS",
   "mcc": "234",
   "network_name": "Vodafone UK",
   "plmns": [
      "23401"
   ],
   "reason": "reason for blocks",
   "expires_at": "string",
   "created_at": "string",
   "ttl": "1d"
}

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

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

Path Parameters

string(uuid)

Required

example3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb

Responses

Rule archived (no content returned)

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

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

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

self

object

Required

href

string

Required

URL to the resource

Example Response

{
   "rules": [
      {
         "product": "SMS",
         "country_code": "PL"
      }
   ],
   "_links": {
      "self": {
         "href": "string"
      }
   }
}

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

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

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

{
   "rules": [
      {
         "product": "SMS",
         "country_code": "PL"
      }
   ]
}

{
   "rules": [
      {
         "product": "SMS",
         "country_code": "PL"
      }
   ]
}

Responses
Content Type
application/json

Successfully replaced country rules

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

{
   "rules": [
      {
         "product": "SMS",
         "country_code": "PL"
      }
   ]
}

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

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

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

self

object

Required

href

string

Required

URL to the resource

Example Response

{
   "countries": [
      {
         "country_code": "ZM",
         "continent": "AF",
         "risk": "HIGH"
      }
   ],
   "_links": {
      "self": {
         "href": "string"
      }
   }
}

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.

Fraud Prevention API

利用可能な業務

Retrieves all networks

Authentication

Query Parameters

Responses Content Typeapplication/json

Example Response

Retrieve all network traffic rules

Authentication

Query Parameters

Responses Content Typeapplication/json

Example Response

Create a new traffic rule for a network

Authentication

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Update an existing network traffic rule

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Archive a network rule

Authentication

Path Parameters

Responses

Retrieve all country traffic rules

Authentication

Responses Content Typeapplication/json

Example Response

Replace country rules

Authentication

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Retrieve all supported countries

Authentication

Responses Content Typeapplication/json

Example Response

Errors

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

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json