Fraud Prevention API

Versão 2

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

Baixar a especificação OpenAPI
Operações disponíveis

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Consulta Parâmetros

name
string
exemploVodafone UK

Filter by network name

mcc
string
exemplo234

Filter by Mobile Country Code (MCC)

country_code
string
exemploGB

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

plmn
string
exemplo23401

Filter by public land mobile network (PLMN)

Respostas
Tipo de conteúdo
application/json

Successfully retrieved networks

networks
array
Obrigatório

List of networks

name
string
Obrigatório
exemploVodafone UK

Network name

mcc
string
Obrigatório
exemplo234

Mobile Country Code

country_code
string
Obrigatório
exemploGB

Country code (ISO 3166-1 Alpha-2)

plmns
array
Obrigatório

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

_links
object
Obrigatório
self
object
Obrigatório
href
string
Obrigatório

URL to the resource

Exemplo Resposta

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Consulta Parâmetros

product
string
exemploSMS

Find rules for a specific product

Deve ser uma das seguintes opções:SMSVOICE
mcc
string
exemplo234

Find rules for a specific Mobile Country Code (MCC)

country_code
string
exemploGB

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

network_name
string
exemploVodafone UK

Find rules for a specific network name.

plmn
string
exemplo23401

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

expire_start_date
string(date)
exemplo2025-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)
exemplo2025-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
exemplo1d

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

Deve ser uma das seguintes opções:PERMANENT1d12h6h3h2h1h
sort
string
Padrãocreated_at
exemplocreated_at

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

Deve ser uma das seguintes opções:productmcccountry_codenetwork_namecreated_atexpires_at
status
string
Padrãoactive
exemploactive

Filter by rule status (active or archived).

Deve ser uma das seguintes opções:activearchived
order
string
Padrãodesc

Sort order (asc or desc)

Deve ser uma das seguintes opções:ascdesc
page
integer
Mín.1
Padrão1

Page number.

page_size
integer
Mín.1
Max100
Padrão10

Number of items per page

Respostas
Tipo de conteúdo
application/json

Successfully retrieved network rules

_embedded
object
Obrigatório
rules
array
Obrigatório
id
string(uuid)
Obrigatório
exemplo3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb

Unique ID of the traffic rule

product
string
Obrigatório
exemploSMS

Product type for the traffic rule

Deve ser uma das seguintes opções:SMSVOICE
mcc
string
Obrigatório
exemplo234

Mobile Country Code

network_name
string
Obrigatório
exemploVodafone UK

Network name

plmns
array
Obrigatório
reason
string
Obrigatório
exemploreason for blocks

Reason for the traffic rule action

expires_at
string(date-time)
exemplo2025-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

created_at
string(date-time)
Obrigatório
exemplo2025-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

ttl
string
Obrigatório
exemplo1d

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

Deve ser uma das seguintes opções:PERMANENT1d12h6h3h2h1h
archived_at
string(date-time)
exemplo2025-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

_links
object
Obrigatório
next
object
href
string
Obrigatório

URL to the resource

prev
object
href
string
Obrigatório

URL to the resource

self
object
Obrigatório
href
string
Obrigatório

URL to the resource

page
integer
Obrigatório
Mín.1

Current page number

page_size
integer
Obrigatório
Mín.1

Number of items per page

total_items
integer
Obrigatório

Total number of elements across all pages

total_pages
integer
Obrigatório

Total number of pages

Exemplo Resposta

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Corpo da solicitação
Tipo de conteúdo
application/json

product
string
Obrigatório
exemploSMS

Product type for the traffic rule

Deve ser uma das seguintes opções:SMSVOICE
plmn
string
Obrigatório
exemplo23401

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

reason
string
Obrigatório
exemploreason for blocks

Reason for the traffic rule action

ttl
string
Obrigatório
exemplo1d

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

Deve ser uma das seguintes opções:PERMANENT1d12h6h3h2h1h

Exemplo Solicitação

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

Respostas
Tipo de conteúdo
application/json

Rule created

id
string(uuid)
Obrigatório
exemplo3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb

Unique ID of the traffic rule

product
string
Obrigatório
exemploSMS

Product type for the traffic rule

Deve ser uma das seguintes opções:SMSVOICE
mcc
string
Obrigatório
exemplo234

Mobile Country Code

network_name
string
Obrigatório
exemploVodafone UK

Network name

plmns
array
Obrigatório
reason
string
Obrigatório
exemploreason for blocks

Reason for the traffic rule action

expires_at
string(date-time)
exemplo2025-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

created_at
string(date-time)
Obrigatório
exemplo2025-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

ttl
string
Obrigatório
exemplo1d

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

Deve ser uma das seguintes opções:PERMANENT1d12h6h3h2h1h

Exemplo Resposta

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Caminho Parâmetros

id
string(uuid)
Obrigatório
exemplo3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb

Corpo da solicitação
Tipo de conteúdo
application/json

reason
string
Obrigatório
exemploreason for blocks

Reason for the traffic rule action

Exemplo Solicitação

{
   "reason": "reason for blocks"
}
{
   "reason": "reason for blocks"
}

Respostas
Tipo de conteúdo
application/json

Rule updated

id
string(uuid)
Obrigatório
exemplo3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb

Unique ID of the traffic rule

product
string
Obrigatório
exemploSMS

Product type for the traffic rule

Deve ser uma das seguintes opções:SMSVOICE
mcc
string
Obrigatório
exemplo234

Mobile Country Code

network_name
string
Obrigatório
exemploVodafone UK

Network name

plmns
array
Obrigatório
reason
string
Obrigatório
exemploreason for blocks

Reason for the traffic rule action

expires_at
string(date-time)
exemplo2025-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

created_at
string(date-time)
Obrigatório
exemplo2025-07-01T10:11:22Z

ISO 8601 datetime string in UTC timezone

ttl
string
Obrigatório
exemplo1d

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

Deve ser uma das seguintes opções:PERMANENT1d12h6h3h2h1h

Exemplo Resposta

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Caminho Parâmetros

id
string(uuid)
Obrigatório
exemplo3f8208fb-9aa3-4ea4-9a3f-de52a81e36bb

Respostas

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Respostas
Tipo de conteúdo
application/json

A complete list of country-based traffic rules

rules
array
Obrigatório

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

product
string
Obrigatório
exemploSMS

Product type for the traffic rule

Deve ser uma das seguintes opções:SMSVOICE
country_code
string
Obrigatório
exemploGB

Country code (ISO 3166-1 Alpha-2)

_links
object
Obrigatório
self
object
Obrigatório
href
string
Obrigatório

URL to the resource

Exemplo Resposta

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Corpo da solicitação
Tipo de conteúdo
application/json

rules
array
Obrigatório

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

product
string
Obrigatório
exemploSMS

Product type for the traffic rule

Deve ser uma das seguintes opções:SMSVOICE
country_code
string
Obrigatório
exemploGB

Country code (ISO 3166-1 Alpha-2)

Exemplo Solicitação

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

Respostas
Tipo de conteúdo
application/json

Successfully replaced country rules

rules
array
Obrigatório

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

product
string
Obrigatório
exemploSMS

Product type for the traffic rule

Deve ser uma das seguintes opções:SMSVOICE
country_code
string
Obrigatório
exemploGB

Country code (ISO 3166-1 Alpha-2)

Exemplo Resposta

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

Autenticação

ChaveDescriçãoOndeExemplo
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Respostas
Tipo de conteúdo
application/json

Successfully retrieved country data

countries
array
Obrigatório

Complete list of supported countries with their risk levels

country_code
string
Obrigatório
exemploPL

Country code (ISO 3166-1 Alpha-2)

continent
string
Obrigatório
exemploEU

Continent code to which the country belongs:

  • AF - Africa
  • AN - Antarctica
  • AS - Asia
  • EU - Europe
  • NA - North America
  • OC - Oceania
  • SA - South America
Deve ser uma das seguintes opções:AFANASEUNAOCSA
risk
string
PadrãoNONE
exemploHIGH

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

Deve ser uma das seguintes opções:NONEHIGH
_links
object
Obrigatório
self
object
Obrigatório
href
string
Obrigatório

URL to the resource

Exemplo Resposta

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

Erros

A seguir, apresentamos uma lista não exaustiva de códigos de erro que podem ocorrer durante o uso desta API.

Esses códigos são adicionais aos que constam em nosso site códigos de erro genéricos.

CódigoInformações
http:error:conflict

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

system:error:internal-error

Something went wrong.