Our CNAM API allows for integration of our CNAM service, which includes Robocall mitigation, into your VoIP network. The API takes information about the call in question including the call from # and call to # and returns various information about the caller. Traditionally, CNAM services have simply done a look-up and given you the name of the caller. With VI’s CNAM service, you will also receive a “fraud score” which is a number between 0 and 100 that shows the chance that this particular call is from a fraudulent source. For calls above a certain threshold, we will return an edited form of the calling name including a prepended ROBO or if the fraud score is high enough, even replacing the calling name with “Fraudulent Call”. The original, unedited calling name is available in the response as well if you do not wish to use the edited form, as well as the fraud score itself so that you can use that information as you wish to protect your customers.

Creating Logins for CNAM API

Logins for the CNAM API match the current API logins found under Add-ons -> API Users in the Back Office. Similar to the Account Management API (API 3.0), authentication is done by username/password as well as the IP address the requests are coming from.

 Once in Add-Ons -> API Users, input the Username, Server IP, and Password and create the user.

Using the CNAM API

The CNAM API service is performed via a POST using a REST API call.

Expected Response

If the call is successful, you will receive a reply in the form of a JSON body with the following information:

{"calling_name_status":"available", - Whether the CNAM status is available

"calling_name":"WIRELESS CALLER", - Treated Caller Name. Caller IDs that have a high chance of being a fraudulent or robocaller will be shown in this field by either a prepended [ROBO] or by replacing the calling_name with “Fraudulent Call” depending on the fraud risk score

"presentation_indicator":"allowed", - Determines whether the information is allowed to be displayed to the receiving end

"call_treatment":"NONE", - (Not Currently Used) Eventually, this will be used in conjunction with the Fraud score to dictate whether calls should be blocked or sent to voicemail instead of going through.

"fraud_score":0, - This is the likelihood that the caller is a part of some fraudulent activity. Score ranges from 0 to 100.

"original_calling_name":"WIRELESS CALLER",  - This is the original, nontreated Calling Name if you do not wish to use the calling_name that has been edited based off the fraud score

"callId":"bc4537ab-0622-4223-b92f-ea32e67a6199"  - Unique Identifier

}

Possible Issues

 “Invalid Auth from: XXX.XXX.XXX.XXX” – This is an authentication failure which could be a result of a few different things. The IP address returned in the area is the IP address that is being used in the authentication process. Make sure that the API User that you are using has that IP address linked to it.

Other than the IP address, it is possible that either the incorrect username/password was passed due to a typo or that the API user was just created and has not propagated to the CNAM system yet. If the information appears to be correct, please wait for the propagation of the user and try again later.

Limitations for CNAM API Calls

• 50 calls per second (per source IP address)

Postman Example for API Call

Open

Billing

If you are using the CNAM API calls, pricing for this service is charged to be Per-DIP based off the CNAM-PER DIP pricing on your account.

If you are using the Robocall Mitigation service at the endpoint-group level (see below for more information), there is no additional cost besides the monthly recurring charge for CNAM at the DID-level.

Whenever using the API, you will receive 2 different forms of the caller name, one that is updated based off the Robocall Mitigation service, and another that is the original, unedited form of the caller name.

Billing CDRs will be created for each successful look-up and will appear in your CDRs.

Robocall Mitigation

The CNAM API will provide CallerID name look-ups as well as a fraud score. This score is a number between 0 and 100 that is basically the chance that the caller is a part of some fraudulent activity. This score is based off of a number of different things, but we treat the Caller Name differently depending on the score:

Score 60-79: Robo? Name (Prepend Robo? )

Score 80-98: Spam? Name (Prepend Spam? )

Score 99-100: Fraudulent Call (Complete Overlay)

For example , if we had a Caller Name of “VOIP INNOVATIONS” with a score of 71, it would instead be displayed as “ROBO? VOIP INNO”. The same Caller Name with a score of 99-100 would be completely replaced and just show “Fraudulent Call”.

How to Use Robocall Mitigation at the Endpoint Group-Level

Go to Endpoints > Endpoint Group Management, and open the desired endpoint group.

You will see the Robocall Mitigation option. Set this to Prepend and then click Update Group:

Open

Once enabled, any DIDs that have CNAM Lookup enabled will use the logic above to prepend ROBO, SPAM, or FRAUDULENT CALL to the source number when we send the call to your network.

You can then use this information to determine whether or not your network will accept or reject the calls based on their fraud score.