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.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Query Parameters
100Page size in Integer format
1Page number in Integer format
Threshold value in Integer format
Interval value in Integer format it will be presented in minutes
Array of ISO countries codes
11005450GB6010SMSabcdef01-2345-6789-abcd-ef0123456789https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779self link
https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=1&size=100first link of the paginated result set
https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=4&size=100last link of the paginated result set
https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=1&size=100previous link of the paginated result set
https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=1&size=100self link
Example Response
{
"page": 1,
"page_size": 100,
"total_pages": 5,
"total_items": 450,
"_embedded": {
"entries": [
{
"country": "GB",
"interval": 60,
"threshold": 10,
"product": "SMS",
"id": "abcdef01-2345-6789-abcd-ef0123456789",
"_links": {
"self": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779"
}
}
}
]
},
"_links": {
"first": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=1&size=100"
},
"last": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=4&size=100"
},
"prev": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=1&size=100"
},
"self": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS?page=1&size=100"
}
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
SMSProduct type (SMS or VOICE)
VOICESMSGBISO country code
6010Example Request
{
"product": "SMS",
"country": "GB",
"interval": 60,
"threshold": 10
}{
"product": "SMS",
"country": "GB",
"interval": 60,
"threshold": 10
}GB6010SMSabcdef01-2345-6789-abcd-ef0123456789https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779self link
Example Response
{
"country": "GB",
"interval": 60,
"threshold": 10,
"product": "SMS",
"id": "abcdef01-2345-6789-abcd-ef0123456789",
"_links": {
"self": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779"
}
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
SMSProduct type (SMS or VOICE)
VOICESMSGBISO country code
6010Example Request
{
"product": "SMS",
"country": "GB",
"interval": 60,
"threshold": 10
}{
"product": "SMS",
"country": "GB",
"interval": 60,
"threshold": 10
}GB6010SMSabcdef01-2345-6789-abcd-ef0123456789https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779self link
Example Response
{
"country": "GB",
"interval": 60,
"threshold": 10,
"product": "SMS",
"id": "abcdef01-2345-6789-abcd-ef0123456789",
"_links": {
"self": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779"
}
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
GB6010SMSabcdef01-2345-6789-abcd-ef0123456789https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779self link
Example Response
{
"country": "GB",
"interval": 60,
"threshold": 10,
"product": "SMS",
"id": "abcdef01-2345-6789-abcd-ef0123456789",
"_links": {
"self": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/configuration/custom-rules/SMS/e21ace94-54fa-4365-a824-38033dc06779"
}
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
trueused to turn on/off AIT protection
standardRequired if protection_enabled is set to true. Default AIT protection level will be used for countries where no specific per-country configuration exists.
highstandardnonearray of specific per-country AIT protection level configurations
UScountry code in ISO 3166-1 Alpha-2 standard
highAIT protection level
highstandardnonehttps://api.nexmo.com/v0.1/fraud-defender/configurations/protections/ait/SMSExample Response
{
"data": {
"protection_enabled": true,
"default_protection_level": "standard",
"protection_level_per_country": [
{
"country": "US",
"protection_level": "standard"
}
],
"_links": {
"self": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/configurations/protections/ait/SMS"
}
}
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
trueused to turn on/off AIT protection
standardRequired if protection_enabled is set to true. Default AIT protection level will be used for countries where no specific per-country configuration exists.
highstandardnonearray of specific per-country AIT protection level configurations
UScountry code in ISO 3166-1 Alpha-2 standard
highAIT protection level
highstandardnoneExample Request
{
"data": {
"protection_enabled": true,
"default_protection_level": "standard",
"protection_level_per_country": [
{
"country": "US",
"protection_level": "high"
}
]
}
}{
"data": {
"protection_enabled": true,
"default_protection_level": "standard",
"protection_level_per_country": [
{
"country": "US",
"protection_level": "high"
}
]
}
}trueused to turn on/off AIT protection
standardRequired if protection_enabled is set to true. Default AIT protection level will be used for countries where no specific per-country configuration exists.
highstandardnonearray of specific per-country AIT protection level configurations
UScountry code in ISO 3166-1 Alpha-2 standard
highAIT protection level
highstandardnonehttps://api.nexmo.com/v0.1/fraud-defender/configurations/protections/ait/SMSExample Response
{
"data": {
"protection_enabled": true,
"default_protection_level": "standard",
"protection_level_per_country": [
{
"country": "US",
"protection_level": "standard"
}
],
"_links": {
"self": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/configurations/protections/ait/SMS"
}
}
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
smsvoicesms1544The 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.
My custom prefix ruleHuman readable reason
blockblockallowactiveactivearchivedExample Request
{
"product": "sms",
"prefix": "44",
"reason": "My custom prefix rule",
"action": "block",
"status": "active"
}{
"product": "sms",
"prefix": "44",
"reason": "My custom prefix rule",
"action": "block",
"status": "active"
}test-idsmsvoicesms44The 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.
fromfromtooutboundoutboundOutbound rules apply to traffic generated from you API Key. Inbound rules apply to traffic sent to your phone numbers.
blockblockallowMy custom prefix ruleHuman readable reason
editvieweditactiveactivearchived2022-12-09T18:19:262022-11-09T18:19:262022-10-09T18:19:26https://api.nexmo.com/v0.1/fraud-defender/rules/test-idExample Response
{
"id": "test-id",
"product": "sms",
"prefix": "44",
"direction": "from",
"traffic_direction": "outbound",
"action": "block",
"reason": "My custom prefix rule",
"permission": "edit",
"status": "active",
"created_timestamp": "2022-12-09T18:19:26",
"updated_timestamp": "2022-11-09T18:19:26",
"archived_timestamp": "2022-10-09T18:19:26",
"_links": {
"self": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/rules/test-id"
}
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Query Parameters
if passed, lists rules for that product. if not, gives such for all product types
voicesmsphone prefix filter
reason filter
action filter
rule type filter (allow, block)
filter rules by status (active, archived, all)
truedefines whether to display default rules or not
trueshow custom rules flag
150page size parameter, starts from 1
1page offset parameter, starts from 1
sort by product, prefix or traffic and it's case-insensitive
productprefixtrafficdescsort order either asc or desc and it's case-insensitive
ascdeschttps://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=1&page_size=3first link of the paginated result set
https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=4&page_size=3last link of the paginated result set
https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=3&page_size=3next link of the paginated result set
https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=1&page_size=3previous link of the paginated result set
https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=2&page_size=3self link
2Page number
3Page size number or 0 if no entries found. Default is 150.
11Total entries for the result set or 0 if no entries found
4Total pages for the paginated result set or 1 if no entries found
test-idsmsvoicesms44The 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.
fromfromtooutboundoutboundOutbound rules apply to traffic generated from you API Key. Inbound rules apply to traffic sent to your phone numbers.
blockblockallowMy custom prefix ruleHuman readable reason
editvieweditactiveactivearchived2022-12-09T18:19:262022-11-09T18:19:262022-10-09T18:19:26https://api.nexmo.com/v0.1/fraud-defender/rules/test-idExample Response
{
"_links": {
"first": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=1&page_size=3"
},
"last": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=4&page_size=3"
},
"next": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=3&page_size=3"
},
"prev": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=1&page_size=3"
},
"self": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/rules?order=asc&page=2&page_size=3"
}
},
"page": {
"number": 2,
"size": 3,
"totalElements": 11,
"totalPages": 4
},
"_embedded": {
"rules": [
{
"id": "test-id",
"product": "sms",
"prefix": "44",
"direction": "from",
"traffic_direction": "outbound",
"action": "block",
"reason": "My custom prefix rule",
"permission": "edit",
"status": "active",
"created_timestamp": "2022-12-09T18:19:26",
"updated_timestamp": "2022-11-09T18:19:26",
"archived_timestamp": "2022-10-09T18:19:26",
"_links": {
"self": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/rules/test-id"
}
}
}
]
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
test-idsmsvoicesms44The 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.
fromfromtooutboundoutboundOutbound rules apply to traffic generated from you API Key. Inbound rules apply to traffic sent to your phone numbers.
blockblockallowMy custom prefix ruleHuman readable reason
editvieweditactiveactivearchived2022-12-09T18:19:262022-11-09T18:19:262022-10-09T18:19:26https://api.nexmo.com/v0.1/fraud-defender/rules/test-idExample Response
{
"id": "test-id",
"product": "sms",
"prefix": "44",
"direction": "from",
"traffic_direction": "outbound",
"action": "block",
"reason": "My custom prefix rule",
"permission": "edit",
"status": "active",
"created_timestamp": "2022-12-09T18:19:26",
"updated_timestamp": "2022-11-09T18:19:26",
"archived_timestamp": "2022-10-09T18:19:26",
"_links": {
"self": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/rules/test-id"
}
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
My custom prefix ruleHuman readable reason
Example Request
{
"reason": "My custom prefix rule"
}{
"reason": "My custom prefix rule"
}test-idsmsvoicesms44The 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.
fromfromtooutboundoutboundOutbound rules apply to traffic generated from you API Key. Inbound rules apply to traffic sent to your phone numbers.
blockblockallowMy custom prefix ruleHuman readable reason
editvieweditactiveactivearchived2022-12-09T18:19:262022-11-09T18:19:262022-10-09T18:19:26https://api.nexmo.com/v0.1/fraud-defender/rules/test-idExample Response
{
"id": "test-id",
"product": "sms",
"prefix": "44",
"direction": "from",
"traffic_direction": "outbound",
"action": "block",
"reason": "My custom prefix rule",
"permission": "edit",
"status": "active",
"created_timestamp": "2022-12-09T18:19:26",
"updated_timestamp": "2022-11-09T18:19:26",
"archived_timestamp": "2022-10-09T18:19:26",
"_links": {
"self": {
"href": "https://api.nexmo.com/v0.1/fraud-defender/rules/test-id"
}
}
}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. |