DNC Lookup API Documentation
DNC Lookup 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 if the phone number is a cellular phone 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) |
| ID | Internal identifier |
Example API Call
https://api.realvalidation.com/rpvWebService/DNCLookup.php?phone=7275555555&token=1234ABCD-1234-ABCD-1234-123456ABCDEFResult in XML
<?xml version= "1.0 " encoding= "UTF-8 "?>
<response>
<RESPONSECODE>OK</RESPONSECODE>
<RESPONSEMSG></RESPONSEMSG>
<national_dnc>Y</national_dnc>
<state_dnc>N</state_dnc>
<dma>N</dma>
<litigator>N</litigator>
<iscell>N</iscell>
<id>4</id>
<response>Result in JSON
{
"RESPONSECODE":"OK",
"RESPONSEMSG":{},
"national_dnc":"Y",
"state_dnc":"N",
"dma":"N",
"litigator":"N",
"iscell":"N",
"id":"4"
}Appendix A:
| Status | Error Text | Description |
|---|---|---|
| -1 | Missing number | Missing or badly formatted number |
| 102 | The user is invalid | Usually for insufficient balances may contain balance information |
| unauthorized | < blank > | incorrect token or suspended account |
| invalid-phone | Phone number does not exist |
Not super techie… integrate DNC Lookup into your favorite CRM, forms, and apps using Zapier or Integrately.
