Fraud Check API Documentation
The RealValidation – Fraud Check API uses GET/POST methods and supports only HTTPS with TLS v1.2+. Determines if a phone number has possible fraudulent use, warranting further examination.
Required Input Parameters:
| Parameter | Description |
|---|---|
| Phone | 10 numeric digits ONLY |
| Token | Unique PW given by RealValidation |
Example API Call
https://api.realvalidation.com/rpvWebService/RealPhoneValidationFraudChk.php?phone=7275555555&token=1234ABCD-1234-ABCD-1234-123456ABCDEFResult in XML
<?xml version=”1.0” encoding=”UTF-8”?>
<response>
<status>0</status>
<error_text></error_text>
<id>20</id>
<req_phone>7275555555</req_phone>
<tstatus>300</tstatus>
<tdesc>Transaction successfully completed</tdesc>
<phn_type>5</phn_type>
<phn_desc>VOIP</phn_desc>
<risk_level>medium</risk_level>
<recommendation>flag</recommendation>
<score>401</score>
<carrier>RingCentral - Sybase365</carrier>
<location_city>Countryside</location_city>
<location_state>FL</location_state>
<location_zip>34619</location_zip>
<location_metro_code></location_metro_code>
<location_county></location_county>
<location_country_name>United States</location_country_name>
<location_country_iso2>US</location_country_iso2>
<location_country_iso3>USA</location_country_iso3>
<location_latitude>27.99117</location_latitude>
<location_longitude>-82.72413</location_longitude>
<location_time_zone>America/New_York</location_time_zone>
<location_time_zone_utc_offset_min>-5</location_time_zone_utc_offset_min>
<location_time_zone_utc_offset_max>-5</location_time_zone_utc_offset_max>
<numbering_original_complete_phone_number>17275555555</numbering_original_complete_phone_number>
<numbering_original_country_code>1</numbering_original_country_code>
<numbering_original_phone_number>7275555555</numbering_original_phone_number>
<numbering_cleansing_call_country_code>1</numbering_cleansing_call_country_code>
<numbering_cleansing_call_phone_number>7275555555</numbering_cleansing_call_phone_number>
<numbering_cleansing_call_cleansed_code>100</numbering_cleansing_call_cleansed_code>
<numbering_cleansing_call_min_length>10</numbering_cleansing_call_min_length>
<numbering_cleansing_call_max_length>10</numbering_cleansing_call_max_length>
<numbering_cleansing_sms_country_code>1</numbering_cleansing_sms_country_code>
<numbering_cleansing_sms_phone_number>7275555555</numbering_cleansing_sms_phone_number>
<numbering_cleansing_sms_cleansed_code>100</numbering_cleansing_sms_cleansed_code>
<numbering_cleansing_sms_min_length>10</numbering_cleansing_sms_min_length>
<numbering_cleansing_sms_max_length>10</numbering_cleansing_sms_max_length>
</response>Response Fields:
| Response Field | Description |
|---|---|
| Status | (See appendix A below) |
| (See Appendix A below) | (See Appendix A below) |
| ID | internal identifier |
| tstatus | (See Appendix A below) |
| tdesc | (See Appendix A below) |
| phn_type | (See Appendix B below) |
| phn_desc | (See Appendix B below) |
| risk level | (See Appendix C below) |
| recommendation | (See Appendix C below) |
| score | (See Appendix C below) |
| carrier | phone service provider |
| location_city | geographic city region that the phone number was originally assigned to |
| location_state | geographic state, province, territory, or district region that the phone number was originally assigned to |
| location_zip | geographic zip code region that the phone number was originally assigned to |
| location_metro_code | geographic Primary Metropolitan Statistical Area code that the phone number was originally assigned to |
| location_county | geographic U.S. county region that the phone number was originally assigned to |
| location_country_name | geographic country region that the phone number was originally assigned to |
| location_county_iso2 | 2 letter ISO abbreviation of the location_country |
| location_country_iso3 | 3 letter ISO abbreviation of the location_country |
| location_latitude | geographic latitude coordinates that the phone number was originally assigned to location_longitude |
| location_longitude | geographic longitude coordinates that the phone number was originally assigned to |
| location_time_zone | geographic timezone name (U.S. Only) that the phone number was originally assigned to |
| location_time_zone_utc_offset_min | the location time zones minimum hour difference between UTC time |
| location_time_zone_utc_offset_max | the location time zones maximum hour difference between UTC time |
| numbering_original_complete _phone_number | The phone number complete with country code |
| numbering_original_ country_code | Country code of phone number |
| numbering_original_ phone_number | The complete phone number minus the country code |
| numbering_cleansing_ call_country_code | possibly corrected numeric country code needed to make the call |
| numbering_cleansing_ call_phone_number | possibly corrected phone number to make the call |
| numbering_cleansing_ call_cleansed_code | the location time zone maximum hour difference between UTC time |
| numbering_cleansing_ call_min_length | minimum number of phone digits allowed in this country for calling |
| numbering_cleansing_ call_max_length | maximum number of phone digits allowed in this country for calling |
| numbering_cleansing_ sms_country_code | possibly corrected numeric country code needed to send a text message |
| numbering_cleansing_ sms_phone_number | possibly corrected phone number to send a text message |
| numbering_cleansing_ sms_cleansed_code | (See Appendix D below) |
| numbering_cleansing_ sms_min_length | minimum number of phone digits allowed in this country for sending a text message |
| numbering_cleansing_ sms_max_length | maximum number of phone digits allowed in this country for sending a text message |
Appendix A:
| tstatus | tdesc | (description) |
|---|---|---|
| 300 | Transaction successfully completed | Able to obtain all applicable phone information |
| 301 | Transaction partially completed | Unable to obtain ALL of the phone information. This can cause some fields to return empty |
| 500 | Transaction not attempted | Phone information collection was not attempted |
| 501 | Phone number does not exist | Contact support |
| 599 | Contact support |
Appendix B:
| phn_type | phn_desc | (description) |
|---|---|---|
| 1 | Fixed line | Typically, an 800 style number usually used for commercial purposes. Actual formatting will differ between countries |
| 2 | Mobile | Mobile / Cellular phone |
| 3 | PrePaid Mobile | Mobile phone that is not tied into a contract and has a potential chance for increased anonymity for the user |
| 4 | Toll_Free | The number belongs to non-call receiving pager device |
| 5 | VoIP | Phone that connects to its user over the internet and not directly through a telephony provider network |
| 6 | Pager | Numbers where tdesc is prefixed with Restricted typically have special uses or are reserved and cannot be tied to a civilian endpoint |
| 7 | Payphone | Typical Payphone booth |
| 8 | Invalid | Not valid |
| 9 | Restricted* | The number is used for forwarding to any other number and is not tied to a particular location or device |
| 10 | Personal | The number belongs to a non-call-receiving pager device |
| 11 | Voicemail | Numbers designed only to connect straight to a voicemail account |
| 20 | other | a landline phone |
Appendix C:
| score | risk level | recommendation | description |
|---|---|---|---|
| 800-1000 | High | Block | Discard number due to fraud use |
| 601-800 | Medium-High | Block | Discard number due to fraud use |
| 401-600 | Medium | Flag | Be careful, as number is potentially used in fraud |
| 201-400 | Medium-Low | Allow | Number appears to be safe to use |
| 0-200 | Low | Allow | Number appears to be safe to use |
Appendix D:
| numbering_cleansing_call_cleansed_code -and- numbering_cleansing_sms_cleansed_code | Description |
|---|---|
| 100 | No changes were made as the formatting was correct |
| 101 | Changed – Might have had extraneous digits removed or additional digits added to meet country dialing rules |
| 102 | Phone was restricted and possibly used for premium or emergency services |
| 103 | Phone number appears to be formatted correctly but could not be matched to a specific area |
| 104 | Phone number is incorrectly formatted |
| 105 | Phone length is either too long or too short |
