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.
We recommend limiting the API call rate to 10 per second. Check out the complete list of RealPhoneValidation API best practices here: realphonevalidation.com/api-best-practices/
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 | |
| HTTP 403 | Temporarily throttled due to exceeding the recommended 10/sec API calls |
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 |
