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-123456ABCDEF
Result 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.
