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 whether the phone number is associated with a cellular phone and whether the phone number is linked to 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) |
| 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 | |
| HTTP 403 | Temporarily throttled due to exceeding the recommended 10/sec API calls |
Not super techie… integrate DNC Lookup into your favorite CRM, forms, and apps using Zapier or Integrately.
