Fraud Prevention API

Version 1

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

Download OpenAPI Specification

SMS Burst Protection

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

利用可能な業務

List SMS Burst Protection entries

Retrieve a paginated list of all SMS Burst Protection configurations.

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

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Query Parameters

page
integer
Default1

page offset parameter, starts from 1

page_size
integer
Default150

page size parameter, starts from 1

Responses
Content Type
application/json

Successful operation

page
object
number
number
example2

Page number

size
number
example3

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

totalElements
number
example11

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

totalPages
number
example4

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

_embedded
object
entries
array
id
string
exampleabcdef01-2345-6789-abcd-ef0123456789

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

destination_countries
array

List of destination countries

利用可能な値：
DZ,AZ,BD,BB,BY,BJ,BG,EG,SV,GH,KZ,KG,LA,MV,MM,NG,PH,PK,PS,RU,LK,SD,SY,TJ,AE,UZ,BH,IR,IQ,IL,JO,KW,LB,OM,QA,SA,YE
block_value
integer
example1

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

_links
object
self
object
href
string
examplehttps://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst/abcdef01-2345-6789-abcd-ef0123456789

link to fetch this individual entity directly

_links
object
first
object
href
string
examplehttps://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst?page=1&size=100

first link of the paginated result set

last
object
href
string
examplehttps://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst?page=4&size=100

last link of the paginated result set

prev
object
href
string
examplehttps://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst?page=1&size=100

previous link of the paginated result set

self
object
href
string
examplehttps://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst?page=1&size=100

Example Response

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

Create new SMS Burst Protection entity

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

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

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Request Body
Content Type
application/json

destination_countries
array
Required
利用可能な値：
DZ,AZ,BD,BB,BY,BJ,BG,EG,SV,GH,KZ,KG,LA,MV,MM,NG,PH,PK,PS,RU,LK,SD,SY,TJ,AE,UZ,BH,IR,IQ,IL,JO,KW,LB,OM,QA,SA,YE
block_value
integer
Required
example1

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

Example Request

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

Responses
Content Type
application/json

Successful operation

id
string
exampleabcdef01-2345-6789-abcd-ef0123456789

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

destination_countries
array

List of destination countries

利用可能な値：
DZ,AZ,BD,BB,BY,BJ,BG,EG,SV,GH,KZ,KG,LA,MV,MM,NG,PH,PK,PS,RU,LK,SD,SY,TJ,AE,UZ,BH,IR,IQ,IL,JO,KW,LB,OM,QA,SA,YE
block_value
integer
example1

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

_links
object
self
object
href
string
examplehttps://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst/abcdef01-2345-6789-abcd-ef0123456789

link to fetch this individual entity directly

Example Response

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

Get SMS Burst Protection rule by ID

Fetch a specific burst protection entry using its unique identifier.

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

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

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

The ID of the entry to be fetched/modified/deleted, this id can be retrieved from the list of entries and use the field called id.

Responses
Content Type
application/json

Successful operation

id
string
exampleabcdef01-2345-6789-abcd-ef0123456789

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

destination_countries
array

List of destination countries

利用可能な値：
DZ,AZ,BD,BB,BY,BJ,BG,EG,SV,GH,KZ,KG,LA,MV,MM,NG,PH,PK,PS,RU,LK,SD,SY,TJ,AE,UZ,BH,IR,IQ,IL,JO,KW,LB,OM,QA,SA,YE
block_value
integer
example1

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

_links
object
self
object
href
string
examplehttps://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst/abcdef01-2345-6789-abcd-ef0123456789

link to fetch this individual entity directly

Example Response

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

Edit an existing SMS Burst Protection rule

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

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

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

The ID of the entry to be fetched/modified/deleted, this id can be retrieved from the list of entries and use the field called id.

Request Body
Content Type
application/json

destination_countries
array
Required
利用可能な値：
DZ,AZ,BD,BB,BY,BJ,BG,EG,SV,GH,KZ,KG,LA,MV,MM,NG,PH,PK,PS,RU,LK,SD,SY,TJ,AE,UZ,BH,IR,IQ,IL,JO,KW,LB,OM,QA,SA,YE
block_value
integer
Required
example1

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

Example Request

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

Responses
Content Type
application/json

Successful operation

id
string
exampleabcdef01-2345-6789-abcd-ef0123456789

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

destination_countries
array

List of destination countries

利用可能な値：
DZ,AZ,BD,BB,BY,BJ,BG,EG,SV,GH,KZ,KG,LA,MV,MM,NG,PH,PK,PS,RU,LK,SD,SY,TJ,AE,UZ,BH,IR,IQ,IL,JO,KW,LB,OM,QA,SA,YE
block_value
integer
example1

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

_links
object
self
object
href
string
examplehttps://api.nexmo.com/v1/fraud-defender/protection-configuration/absolute-burst/abcdef01-2345-6789-abcd-ef0123456789

link to fetch this individual entity directly

Example Response

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

Delete SMS Burst Protection entity by id

Remove an SMS burst protection entry from the system.

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

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

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

The ID of the entry to be fetched/modified/deleted, this id can be retrieved from the list of entries and use the field called id.

Responses

No Content

Custom Fraud Rules

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

利用可能な業務

List custom fraud rules

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

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

product
string
Required
Must be one of:SMSVOICE

Query Parameters

page_size
integer(int32)
Default100

Page size in Integer format

page
integer(int32)
Default1

Page number in Integer format

threshold
integer(int32)

Threshold value in Integer format

interval
integer(int32)

Interval value in Integer format it will be presented in minutes

countries
array

Array of ISO countries codes

Responses
Content Type
application/json

OK

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

self link

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

first link of the paginated result set

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

last link of the paginated result set

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

previous link of the paginated result set

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

self link

Example Response

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

Edit custom fraud rule by ID

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

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

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

Rule ID in UUID format

Request Body
Content Type
application/json

product
string

Product type (SMS or VOICE)

Must be one of:SMSVOICE
country
string
exampleGB

ISO country code

interval
integer(int32)
example360

Interval in minutes. Supported values:

  • 1 min: 1
  • 5 min: 5
  • 10 min: 10
  • 15 min: 15
  • 30 min: 30
  • 45 min: 45
  • 1 hour: 60
  • 6 hour: 360
  • 12 hour: 720
  • One day: 1440
Must be one of:1510153045603607201440
threshold
integer(int32)
example100

Example Request

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

Responses
Content Type
application/json

OK

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

self link

Example Response

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

Create custom fraud rule

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

Product type (SMS or VOICE)

Must be one of:SMSVOICE
country
string
exampleGB

ISO country code

interval
integer(int32)
example360

Interval in minutes. Supported values:

  • 1 min: 1
  • 5 min: 5
  • 10 min: 10
  • 15 min: 15
  • 30 min: 30
  • 45 min: 45
  • 1 hour: 60
  • 6 hour: 360
  • 12 hour: 720
  • One day: 1440
Must be one of:1510153045603607201440
threshold
integer(int32)
example100

Example Request

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

Responses
Content Type
application/json

OK

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

self link

Example Response

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

Get custom fraud rule by product and id

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

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

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

Rule ID in UUID format

Responses
Content Type
application/json

OK

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

self link

Example Response

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

Delete custom fraud rule by ID

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

Authentication

KeyDescriptionWhereExample
Authorization

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

Headers

Basic <base64>

Path Parameters

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

Rule ID in UUID format

Responses

No Content

Errors

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

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

CodeInformation
http:error:conflict

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

system:error:internal-error

Something went wrong.

http:error:validation-fail

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

http:error:bad-request

Bad Request. Please refer to the API specs