Official REST API v1

Litigation Firewall API

Client Integration & Developer Documentation. Real-time, automated screening of outbound phone numbers across 8 distinct databases to protect campaigns from TCPA violations.

Download Official PDF Documentation

1. Authentication

Access to the Litigation Firewall API requires a client-scoped API Key. This key must be supplied in each request as a custom HTTP header:

HTTP Header Specification
x-api-key: YOUR_CLIENT_API_KEY
⚠️ Security Warning: Your API key is secret and allows full access to the litigation check services. Keep it secure and never share it in public repositories or client-side code.

2. API Endpoint

All checks must be performed using the following endpoint:

POST /api/v1/litigation-firewall/check

Request Headers

Header Type Required Description
x-api-key String Yes Your unique client API key (starts with lf_).
Content-Type String Yes Must be set to application/json.

Request Body

Pass a JSON payload containing the 10-digit US phone number to check:

JSON Payload Example
{ "phone": "8439689323" }
📱 Phone Formatting Note: The API accepts formatted inputs (e.g. (843) 968-9323, +18439689323). All formatting spaces, brackets, and country codes (1 or +1) are stripped automatically. The remaining digits must contain exactly 10 digits.

3. Response Schema

The API returns a JSON response indicating the results of the 8 database lookups.

Success Response (200 OK)

Response Body Example
{ "ok": true, "submitted_phone": "8439689323", "overall_status": "risk_indicator_returned", "screened_at_utc": "2026-10-08T18:00:00Z", "notice": "Screening notice: Results reflect information returned by identified independent providers at the screening time. A no-match result does not mean a number is lawful or safe to call or text. Informational result only; not legal advice or authorization to call or text.", "checks": { "litigators_db": { "raw": "8439689323 is Clean", "status": "clean" }, "blacklisted_db": { "raw": "8439689323 Found : Clean", "status": "clean" }, "dnc": { "raw": "8439689323 : Clean", "status": "clean" }, "social_analytics": { "raw": "8439689323 is Checked", "status": "clean" }, "closers_dnc": { "raw": "8439689323 is Not found", "status": "clean" }, "invalid_phones": { "raw": "8439689323 is Valid", "status": "clean" }, "voip_blocked": { "raw": "8439689323 has VoIP indicator", "status": "flagged" } }, "location": { "zip": "29532", "city": "DARLINGTON", "state": "SC", "county": "DARLINGTON" } }
Screening notice: Results reflect information returned by identified independent providers at the screening time. A no-match result does not mean a number is lawful or safe to call or text. DNC Finder does not evaluate consent, revocation, exemptions, calling purpose, calling time, internal do-not-call requests, seller registration, licensing, caller identification, dialing technology, artificial or prerecorded voice use, recording laws, or every federal and state requirement.

Standard Status Values

API Status Label Description
no_match_returned No match returned No selected match was returned by checks that completed successfully. This is not permission to call or text.
match_returned Match returned One or more selected sources returned a match. Review the source-level result before contact.
risk_indicator_returned Risk indicator returned A non-registry provider returned a potential risk match. This is an informational indicator, not a legal finding.
incomplete Incomplete screening A requested check failed, timed out, lacked authorized scope, or returned no usable response. Must not be treated as no-match.
invalid_input Invalid input The submitted value could not be screened (e.g. malformed phone digits).

4. 8 Real-Time Database Checks

Every submitted phone number is screened simultaneously against 8 specialized protection databases:

1. Litigators DB Known TCPA attorneys & serial litigators
2. Blacklisted DB High-risk legal plaintiff records
3. DNC Registry National & State Do-Not-Call lists
4. Social Analytics Lead authenticity & activity signal
5. Closers DNC Internal agency blocklists
6. Old Closers DNC Historical agency complaint records
7. Invalid Phones Unassigned / disconnected numbers
8. VoIP Blocked Restricted virtual & internet lines

5. Error Responses

In the event of authentication or input errors, standard HTTP status codes and JSON error details are returned:

Status Reason Example Payload
400 Bad Request Phone number is missing or does not contain 10 digits. {"error": "Invalid phone number format."}
401 Unauthorized API Key is missing, invalid, or deleted. {"error": "Invalid or inactive API key."}
403 Forbidden API Key has been suspended or blocked. {"error": "API key is blocked."}
429 Too Many Requests Rate limit (requests per min) has been exceeded. {"error": "Rate limit exceeded. Maximum 60..."}
502 Bad Gateway External verification service temporary error. {"error": "Failed to communicate with API."}

6. Client Integration Examples

Node.js (Axios)

JavaScript / Node.js
const axios = require('axios'); axios.post('https://dncfinder.com/api/v1/litigation-firewall/check', { phone: '8439689323' }, { headers: { 'x-api-key': 'lf_YOUR_API_KEY', 'Content-Type': 'application/json' } }) .then(res => { console.log('Status:', res.data.normalized_status); console.log('Checks:', res.data.checks); }) .catch(err => { console.error('Request failed:', err.response?.data || err.message); });

Python

Python 3
import requests url = "https://dncfinder.com/api/v1/litigation-firewall/check" headers = { "x-api-key": "lf_YOUR_API_KEY", "Content-Type": "application/json" } payload = { "phone": "8439689323" } response = requests.post(url, json=payload, headers=headers) print(response.json())

cURL

cURL Command Line
curl -X POST https://dncfinder.com/api/v1/litigation-firewall/check \ -H "x-api-key: lf_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"phone": "8439689323"}'

Need Offline API Documentation?

Download the full, official PDF documentation version for your development team.

Download Official PDF