DNC Plus API Documentation
DNC Plus API uses GET/POST methods and supports only HTTPS with TLS v1.2+. Determines if the phone number is present on national, state, or Direct Marketing Association do-not-call lists. It also identifies the phone number connection status, line type, and if the phone number is associated with a known TCPA litigator or serial plaintiff.
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/
Before using, please make sure you have a SAN number from https://telemarketing.donotcall.gov/profile/create.aspx
Required Input Parameters:
| Parameter | Description |
|---|---|
| Output | (OPTIONAL) set to “json” or “xml”. Omitting this defaults to XML |
| Phone | 10 numeric digits ONLY |
| Token | Unique PW given by RealValidation |
Response Fields:
| Response Field | Description |
|---|---|
| Phone | 10 numeric digits ONLY |
| RESPONSECODE | “OK” or corresponding error code – see Appendix A |
| RESPONSEMSG | Blank or corresponding error message – see Appendix A |
| national_dnc | “Y” = on the National Do-Not-Call list, “N” = not on the list, “?” = timeout |
| state_dnc | “Y” = on a state Do-Not-Call list, “N” = not on the list, “?” = on another Do-Not-Call list or timeout |
| dma | “Y” = on a state Do-Not-Call list, “N” = not on the list, “?” = on another Do-Not-Call list or timeout |
| litigator | “Y” = on the known litigator list, “N” = not on the list, “?” = on a Do-Not-Call list or timeout |
| Iscell | “Y” means Cell phone, “N” means Landline (“V” is for VoIP if enabled on account) |
| Status | (See Appendix A below) |
| error_text | (See Appendix A below) |
Example API Call
https://api.realvalidation.com/rpvWebService/DNCPlus.php?phone=7275555555&token=1234ABCD-1234-ABCD-1234-123456ABCDEFResult in XML
<?xml version= "1.0 " encoding= "UTF-8 "?>
<response>
<status>connected</status>
<error_text></error_text>
<iscell>N</iscell>
<national_dnc>Y</national_dnc>
<state_dnc>N</state_dnc>
<dma>N</dma>
<litigator>N</litigator>
<response>Result in JSON
{
"status":"connected",
"error_text":{},
"iscell":"N",
"national_dnc":"Y",
"state_dnc":"N",
"dma":"N",
"litigator":"N",
}Appendix A:
| Status | Error Text | Description |
|---|---|---|
| -1 | Missing number | Missing or badly formatted number |
| 102 | The user is invalid | The phone number does not exist |
| unauthorized | < blank > | incorrect token or suspended account |
| invalid-phone | Phone number does not exist | |
| connected | Typically connected | |
| connected-75 | Connected 75% of the time | |
| pending | Not completed yet | |
| disconnected | Typically disconnected | |
| disconnected-70 | Disconnected 70% of the time | |
| busy | Busy | |
| unreachable | Not reachable | |
| invalid phone | Phone not valid | |
| restricted | Can’t be dialed | |
| ERROR | bad phone number | |
| ERROR | missing token | |
| unauthorized | token is not valid | |
| invalid-format | phone or zip are not in a valid format | |
| invalid-phone | phone number is not valid | |
| bad-zip-code | zip code is not valid | |
| server-unavailable | various messages | Contact support |
| HTTP 403 | Temporarily throttled due to exceeding the recommended 10/sec API calls |
Not super techie… integrate DNC Plus into your favorite CRM, forms, and apps using Zapier or Integrately.
