API documentation – TCPA Litigator List

API Authentication

To use our API please use Basic Authentication.

Generate API Keys you can here



Our main API server: https://api.tcpalitigatorlist.com

Note: In case of API unexpected fails, you can switch traffic to our backup server. Keep in mind it`s for emergencies, not for constant use: https://api101.tcpalitigatorlist.com

Example
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phone/tcpa/1000000000';
$api_username = '$api_username';
$api_password = '$api_password';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
$output = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);
$response_array = json_decode($output,true);
https://api.tcpalitigatorlist.com/scrub/phone/ Method: POST
Check if phone number is in our TCPA/DNC list
Params:
  • [phone_number] (POST) (required) Phone number to check
  • [contact_name] (POST) (optional) Name of contact person
  • [type] (POST) (optional) List type to scrub against.
    Available values:
    - all
    - tcpa (default) - Scrub out TCPA, Troll
    - dnc - Scrub out DNC complainers
    Or array of the values.
  • [state] (POST) (optional) Country states codes array.
    If specified application will also be scrubing out phone numbers of requested states DNC lists. Example: ['FL','NY','CA'].
    Available states
    Note: This option is independent from TYPE parameter.
  • [return] (POST) (optional) Specifies the format of the returned value. Available values: boolean (1 - match, 0 - clean)
Example
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phone/';
$api_username = '$api_username';
$api_password = '$api_password';

$types = ["tcpa", "dnc"];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('type' => json_encode($types), 'phone_number' => '9258492311', 'contact_name' => 'John')));
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$output = curl_exec($ch);
curl_close ($ch);

$response_array = json_decode($output,true); Response example: 
{
	"clean": {
		"9258492311": {
			"phone_number": "9258492311"
		}
	},
	"results": {
		{
			"phone_number": "9258492311"
			"clean": "1"
		}
	}
}
https://api.tcpalitigatorlist.com/scrub/phone/[type]/[phone_number]/[contact_name] Method: GET
Check if phone number is in our TCPA/DNC list
Params:
  • [type] (required) List type to scrub against.
    Available values:
    - all
    - tcpa (default) - Scrub out TCPA, Troll
    - dnc - Scrub out DNC complainers
    Or array of the values.
  • [phone_number] (required) Phone number to check
  • [contact_name] (optional) Name of contact person
  • [state] (optional) Country states code.
    If specified application will also be scrubing out phone numbers of requested states DNC lists. Example: 'FL'.
    Available states
    Note: This option is independent from TYPE parameter.
Example
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phone/all/9258492311/John';
$api_username = '$api_username';
$api_password = '$api_password';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
$output = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);
$response_array = json_decode($output,true); Response example: 
{
	"clean": {
		"9258492311": {
			"phone_number": "9258492311"
		}
	},
	"results" : {
		{
			"phone_number": "9258492311"
			"clean": "1"
		}
	}
}
https://api.tcpalitigatorlist.com/scrub/name/[type]/[contact_name] Method: GET
Check if contact name is in our TCPA/DNC list
Params:
  • [type] (required) List type to scrub against.
    Available values:
    - all
    - tcpa (default) - Scrub out TCPA, Troll
    - dnc - Scrub out DNC complainers
    Or array of the values.
  • [contact_name] (optional) Name of contact person
Example
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/name/tcpa/John vitorino';
$api_username = '$api_username';
$api_password = '$api_password';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
$output = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);
$response_array = json_decode($output,true); Response example: 
{
	"match": {
		"7276089538": {
			"phone_number": 7276089538,
			"status": "TCPA",
			"name": "John  Vitorino",
			"first_name": null,
			"middle_name": null,
			"last_name": null,
			"case_title": "",
			"multiple_cases": "1",
			"phone_type": "",
			"phone_status": "Listed In Complaint",
		}
	},
	"results": {
		{
			"phone_number": 7276089538,
			"status": "TCPA",
			"name": "John  Vitorino",
			"first_name": null,
			"middle_name": null,
			"last_name": null,
			"case_title": "",
			"multiple_cases": "1",
			"phone_type": "",
			"phone_status": "Listed In Complaint",
			"clean":0,
		}
	}
}
Match tcpa: 
{
	"match": {
		"1231231231": {
			"phone_number":"1231231231",
			"name":"John Vitorino"
			"first_name":"John",
			"middle_name":"",
			"last_name":"Vitorino",
			"case_title":"",
			"multiple_cases":"1",
			"phone_type":"TCPA, Federal DNC",
			"phone_status":"Listed In Complaint",
		}
	},
	"results": {
		{
			"phone_number":"1231231231",
			"name":"John Vitorino"
			"first_name":"John",
			"middle_name":"",
			"last_name":"Vitorino",
			"case_title":"",
			"multiple_cases":"1",
			"phone_type":"TCPA, Federal DNC",
			"phone_status":"Listed In Complaint",
			"clean":0,
		}
	}
}
Match DNC Complainers or Federal DNC: 
{
	"match": {
		"1231231231": {
			"phone_number": "1231231231",
			"type": "Federal DNC"
		}
	},
	"results": {
		{
			"phone_number":"1231231231",
			"name":"John Vitorino"
			"first_name":"John",
			"middle_name":"",
			"last_name":"Vitorino",
			"case_title":"",
			"multiple_cases":"1",
			"phone_type":"TCPA, Federal DNC",
			"phone_status":"Listed In Complaint",
			"clean":0,
		}
	}
}
Clean: 
{
	"clean": {
		"9258492311": {
			"phone_number": "9258492311"
		}
	},
	"results" : {
		{
			"phone_number": "9258492311"
			"clean": "1"
		}
	}
}
Not enough credits: 
{
	"error": "You do not have enough credits"
}
API subscription is not active or incorrect API credentials: 
{
	"code": "rest_forbidden",
	"message": "Sorry, you are not allowed to do that.",
	"data": {
		"status": 401
	}
}

Mass records scrub

How to do mass scrub?

There are two ways to do mass scrub for small lists and big lists (take a look at difference /scrub/phones/).

If want to scrub small list, you need to do next steps:

  1. Send your phone numbers with /scrub/phones/ endpoint, using the small_list param
  2. As result you will get clean and match phone numbers.
    For example: 
    {
	"match": {
		"6319796917": {
			"phone_number": "6319796917",
			"status": "DNC_COMPLAINERS"
		}
	},
	"clean": {
		"6028912045": {
			"phone_number": "6028912045"
		},
		"6024223200": {
			"phone_number": "6024223200"
		}
	},
	"results" : {
		{
			"phone_number": "6028912045"
			"clean": "1"
		},
		{
			"phone_number": "6024223200"
			"clean": "1"
		},
		{
			"phone_number":"6319796917",
			"name":"John Vitorino"
			"first_name":"John",
			"middle_name":"",
			"last_name":"Vitorino",
			"case_title":"",
			"multiple_cases":"1",
			"phone_type":"TCPA",
			"phone_status":"Listed In Complaint",
			"clean":0,
		}
	}
}

If want to scrub big list, you need to do next steps:

  1. Send your phone numbers with /scrub/phones/ endpoint.
    As result you will get a unique key. The key is an id of your job in jobs queue. With the key you can check the job status and get its result.
    For example: 
    {
	"status": "in_queue",
	"job_key": "2959996d31374622d45c20f57388912f"
}
  2. Check the job with the key you got earlier until you get the job result. To check a job status use /scrub/phones/get/ or /scrub/phones/jobs/ endpoint.
    Example you can find here /scrub/phones/.
https://api.tcpalitigatorlist.com/scrub/phones/ Method: POST
How to scrub?
Check if phone numbers are in our TCPA/DNC list. There are two ways to do mass scrub for small lists (less then 3000 phone numbers) and big lists (more then 3000 phone numbers).
The different between them is if you use this endpoint with small_list flag, you will get result right away, but there is 3000 phone numbers limit.
If you use this endpoint without small_list flag, you will be added in common queue and as response you will get a unique key, with that key you can get scrub result in the future.
To get scrub result you need to send request to /scrub/phones/get/ endpoint with the key you got earlier. Using this endpoint without small_list flag, you have no limits.

What does sub_user means?
The sub_user param is a request marker. This marker is needed for grouping requests. Here you can find statistics of these groups.

The big list scrub speed test
790K numbers - TCPA = 1 minute 10 seconds
790K numbers - DNC = 56 seconds
790K numbers - DNC FED = 1 minute 7 seconds
790K numbers - ALL = 1 minute 53 seconds
Params:
  • [phones] (required) (POST) Phone numbers list
  • [type] (optional) (POST) List type to scrub against.
    Available values:
    - all
    - tcpa (default) - Scrub out TCPA, Troll
    - dnc - Scrub out DNC complainers
    Or array of the values.
  • [sub_user] (optional) (POST) Request marker
  • [small_list] (optional) (POST) If true, scrub result will be returned immediately. Available values: true, false
  • [use_suppression_list] (optional) (POST) Use your suppression list uploaded on the site or not. Available values: true, false
  • [state] (POST) (optional) Country states codes array.
    If specified application will also be scrubing out phone numbers of requested states DNC lists. Example: ['FL','NY','CA'].
    Available states
    Note: This option is independent from TYPE parameter.

Small list (up to 3000) scrub example

PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones';
$api_username = '$api_username';
$api_password = '$api_password';

$numbers = ["6319796917", "6024223200", "6028912045"];

$types = ["tcpa", "dnc"];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('phones' => json_encode($numbers), 'type' => json_encode($types), 'sub_user' => 'Some user', 'small_list' => 'true')));
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$output = curl_exec($ch);
curl_close ($ch);

$response_array = json_decode($output,true); Response example: 
{
	"match": {
		"6319796917": {
			"phone_number": "6319796917",
			"status": "DNC_COMPLAINERS"
		}
	},
	"clean": {
		"6024223200": {
			"phone_number": "6024223200"
		},
		"6028912045": {
			"phone_number": "6028912045"
		}
	},
	"results" : {
		{
			"phone_number": "6024223200"
			"clean": "1"
		},
		{
			"phone_number": "6028912045"
			"clean": "1"
		},
		{
			"phone_number":"6319796917",
			"name":"John Vitorino"
			"first_name":"John",
			"middle_name":"",
			"last_name":"Vitorino",
			"case_title":"",
			"multiple_cases":"1",
			"phone_type":"TCPA",
			"phone_status":"Listed In Complaint",
			"clean":0,
		}
	}
}

Big list (over 3000) scrub example

PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones';
$api_username = '$api_username';
$api_password = '$api_password';

$numbers = ["6319796917", "6024223200", "6028912045"];

$types = ["tcpa", "dnc"];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('phones' => json_encode($numbers), 'type' => json_encode($types), 'sub_user' => 'Some user')));
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$output = curl_exec($ch);
curl_close ($ch);

$response_array = json_decode($output,true); Response example: 
{
	"status": "in_queue",
	"job_key": "3e3c21b74b5de356c6a0c42190836c6f"
}
Get result
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones/get/';
$api_username = '$api_username';
$api_password = '$api_password';

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('key' => "'3e3c21b74b5de356c6a0c42190836c6f'")));
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$interval = 10;

while(true) {

sleep($interval);

$output = curl_exec($ch);

$response_array = json_decode($output,true);

if(
isset($response_array['status']) &&
($response_array['status'] == 'in_queue' ||
$response_array['status'] == 'processing')
) {
//Result not ready yet
continue;
} else if(isset($response_array['match'])) {
//Result ready
$result = $response_array;
break;
} else {
//Something went wrong
break;
}
}

curl_close ($ch);

$response_array = json_decode($output,true); Response example: 
{
	"match": {
		"6319796917": {
			"phone_number": "6319796917",
			"status": "DNC_COMPLAINERS"
		}
	},
	"clean": {
		"6024223200": {
			"phone_number": "6024223200"
		},
		"6028912045": {
			"phone_number": "6028912045"
		}
	},
	"results" : {
		{
			"phone_number": "6024223200"
			"clean": "1"
		},
		{
			"phone_number": "6028912045"
			"clean": "1"
		},
		{
			"phone_number":"6319796917",
			"name":"John Vitorino"
			"first_name":"John",
			"middle_name":"",
			"last_name":"Vitorino",
			"case_title":"",
			"multiple_cases":"1",
			"phone_type":"TCPA",
			"phone_status":"Listed In Complaint",
			"clean":0,
		}
	}
}
https://api.tcpalitigatorlist.com/scrub/phones/get/ Method: POST
Get result of the job
Params:
  • [key] (required) A key of the job
Example
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones/get/';

$api_username = '$api_username';

$api_password = '$api_password';



$ch = curl_init();



curl_setopt($ch, CURLOPT_URL,$api_endpoint);

curl_setopt($ch, CURLOPT_POST, 1);

curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('key' => '972a569d8bdcaeee1ac30404c05054aa')));

curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");

curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);



$output = curl_exec($ch);

curl_close ($ch);



$response_array = json_decode($output,true);
Response example: 
{
	"match": {
		"6319796917": {
			"phone_number": "6319796917",
			"status": "DNC_COMPLAINERS"
		}
	},
	"clean": {
		"6028912045": {
			"phone_number": "6028912045"
		},
		"6024223200": {
			"phone_number": "6024223200"
		}
	},
	"results" : {
		{
			"phone_number": "6028912045"
			"clean": "1"
		},
		{
			"phone_number": "6024223200"
			"clean": "1"
		},
		{
			"phone_number":"6319796917",
			"name":"John Vitorino"
			"first_name":"John",
			"middle_name":"",
			"last_name":"Vitorino",
			"case_title":"",
			"multiple_cases":"1",
			"phone_type":"TCPA",
			"phone_status":"Listed In Complaint",
			"clean":0,
		}
	}
}
https://api.tcpalitigatorlist.com/scrub/phones/jobs Method: POST
Get all queue jobs
Example
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones/jobs';
$api_username = '$api_username';
$api_password = '$api_password';
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$output = curl_exec($ch);
curl_close ($ch);

$response_array = json_decode($output,true); Response example: 
{
	"jobs": [
		{
			"key": "b8c6e9f019be06b581e888c0474eafee",
			"status": "result_ready",
			"create_ts": "2020-05-15 07:46:18"
		},
		{
			"key": "0700d5c294e6fb31e36e826b471e536c",
			"status": "result_ready",
			"create_ts": "2020-05-15 07:46:51"
		},
		{
			"key": "8da181132f2b63d53972b49f44dd7fc4",
			"status": "result_ready",
			"create_ts": "2020-05-15 08:00:11"
		}
	]
}
https://api.tcpalitigatorlist.com/scrub/stats/[start_date]/[end_date] Method: GET
Show API statistics
Params:
  • [start_date] (optional) Start date
  • [end_date] (optional) End date
Example
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/stats/2020-05-16/2020-05-16';
$api_username = '$api_username';
$api_password = '$api_password';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
$output = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);
$response_array = json_decode($output,true); Return: 
{
	"total": {
		"count": "0",
		"price": 0
	},
	"user": {
		"count": "0",
		"price": 0
	},
	"sub_users": []
}

Array scrub example

To use our API please use Basic Authentication
PHP Example
$api_endpoint = 'https://api.tcpalitigatorlist.com/scrub/phones/all/';
$api_username = '$api_username';
$api_password = '$api_password';

$numbers = ["6319796917", "6038980045", "6014250300"];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$api_endpoint);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('phones' => json_encode($numbers), 'small_list' => 'true')));
curl_setopt($ch, CURLOPT_USERPWD, "$api_username:$api_password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$output = curl_exec($ch);
curl_close ($ch);

$response_array = json_decode($output,true);

Results examples

TCPA Match 
{
	"match":{
		"9257350671":{
			"phone_number":9257350671,
			"status":"TCPA",
			"name":"Carolyn Murakami",
			"serial":"0",
			"phone_type":"Landline",
			"phone_status":"Associated With Litigator",
			"filling_date":"",
			"added":"2019 Feb 09"
		}
	},
	"results" : {
		{
			"phone_number":9257350671,
			"status":"TCPA",
			"name":"Carolyn Murakami",
			"serial":"0",
			"phone_type":"Landline",
			"phone_status":"Associated With Litigator",
			"filling_date":"",
			"added":"2019 Feb 09",
			"clean":"0",
		}
	}
}
Clean phone number 
{
	"clean": {
		"92573506711": {
			"phone_number": "92573506711"
		}
	},
	"results": {
		{
			"phone_number": "92573506711",
			"clean": 1,
		}
	}
}

Easily scrub your phone numbers using our API SDK

Our repository you can find here https://github.com/StreetYo/TCPA-SDK

API SDK

SDK stands for software development kit or devkit for short. It’s a set of software tools and programs used by developers to create applications for specific platforms.

SDK tools will include a range of things, including libraries, documentation, code samples, processes, and guides that developers can use and integrate into their own apps.


Make it before use

Login to your account. Generate your API keys here if you don't have them yet.

Example

Set your API login and password. You can run this code with the GET phone or phones parameters and get their scrub statuses.

if ( isset($_GET['phone']) ){
	print_r(tcpa_scrub_single_number($_GET['phone']));
}

if ( isset($_GET['phones']) ){
	print_r(tcpa_mass_scrub(explode(',', $_GET['phones'])));
}

function tcpa_scrub_single_number($phone_number, $fields = []){
	$api_config = [
		'api_username' => 'YOUR API LOGIN',
		'api_password' => 'YOUR API PASSWORD',
		'response_format' => 'json',
		'response_type' => isset($_GET['boolean']) ? 'boolean' : 'regular',
		'check_types' => isset($_GET['type']) ? [$_GET['type']] : ['all'],
	];
    $api = new TCPA_API($api_config);
    return $api->request_single_number($phone_number, $fields);
}

function tcpa_mass_scrub($phone_numbers, $fields = []) {
    $api_config = [
        'api_username' => 'YOUR API LOGIN',
        'api_password' => 'YOUR API PASSWORD',
        'check_types' => isset($_GET['type']) ? [$_GET['type']] : ['all'],
    ];
    $api = new TCPA_API($api_config);
    return $api->mass_scrub($phone_numbers, $fields);
}
Download SDK