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.
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”, “N”, “?” indicating a “yes”, “no”, or “timeout” presence on the national DNC list |
| state_dnc | “Y”, “N”, “?” indicating a “yes”, “no”, or “timeout” presence on the state DNC list |
| dma | “Y”, “N”, “?” indicating a “yes”, “no”, or “timeout” presence on the DMA list |
| litigator | “Y”, “N”, “?” indicating a “yes”, “no”, or “timeout” if a known DNC litigator |
| 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 |
Not super techie… integrate DNC Plus into your favorite CRM, forms, and apps using Zapier or Integrately.
