Bulk TPS/CTPS check a CSV file
A facility to bulk TPS/CTPS check a CSV file of business or residential telephone numbers.
Use this method if you need to TPS check a whole dataset of UK telephone numbers. The method is asynchronous which allows you to start it processing and not tie up any resources waiting for the results.
Your CSV can contain residential or business data.
The data must be uploaded to T2A as a csv with at least one column that contains telephone numbers. The process automatically detects which columns contain telephone numbers.
T2A will append these further columns to the CSV:-
- result (FOUND, NOT FOUND)
- telephone number
- TPS/CTPS status of the telephone number. We check against both the TPS and CTPS data.
Usage
This is an asynchronous method, requiring several stages in the operation.
- Create a job (also known as a transaction). This is a unique item that will be used to upload, process and finally download your data. Create the job using the create command. Please note that this is a free method.
- Upload your csv data. This is free.
- Start the checking process. It runs in the backgroumd.
- Invoke the progress command to monitor the progress of T2A in processing your job. You may wish to display this as a progress bar or similar to your final users. The invocation of this method is normally from JavaScript. When the percentage figure has reached 100, the processing is complete, and you may proceed to the next stage. Nothing is chargeable yet.
- When the process is completed, view a summary of the results.
- If you wish to purchase the full result (i.e. the original csv with all telephone numbers TPS checked ), invoke the finalise command which will prepare the data, deduct the necessary credits, and supply a download URL which can be used to obtain the purchased csv.
Commands
Introduction
The individual operations of this method are selected using the mandatory command parameter.
Command 'create'
Create a transaction (also known as a job) to be used for your upload, append and download. This is free.
Mandatory Parameters
| Name | Description |
|---|---|
api_key or javascript_key |
Use your API key if invoking server-side. If invoking from the browser via JavaScript, generate a JavaScript key using the javascript_key method. |
| command | Must be set to create |
Optional Parameters
| Name | Description |
|---|---|
| client | You can optionally include an identifier for your final client or user. This is logged in your usage log and you will be able to view your usage statistics by client. |
| output | Set to json for a JSON response; the default response is XML. Not applicable to the SOAP API. |
| callback | When using JSON, specify a JSONP wrapper in which the JSON response is to be wrapped. |
Returned Values
The XML response is contained within a <tps_bulk_res> element.
| Name | Description |
|---|---|
| status | Returns ok if the operation has succeeded, or error if an
error has occurred; Returns the error_code for error details. |
| error_code |
Returns the error code when the status is |
| transaction_id | The ID of the job created. |
| t2a_version_number | The current API version number. |
Example XML Response
<?xml version="1.0"?> <tps_bulk_res> <mode>normal</mode> <status>ok</status> <t2a_version_number>1.0.0</t2a_version_number> <transaction_id>wKVrW6dhYPMBEA0iQTuJ_u9YQx_L1fOvVqQ1AOboPS_U</transaction_id> </tps_bulk_res>
Command 'upload'
Upload your csv data to T2A.
Mandatory Parameters
| Name | Description |
|---|---|
api_key or javascript_key |
Use your API key if invoking via server-side XML or SOAP. If using JSON, generate a JavaScript key using the javascript_key method. |
| command | Must be set to upload |
| transaction_id | The ID of the job, as created by create. |
| csv_data | The csv data. If you are using the REST API, you will need to invoke this method as a POST. |
| is_first_line_headers | Set to Y if the first line of the CSV is the column headers. |
Returned Values
The XML response is contained within a <tps_bulk_res> element.
| Name | Description |
|---|---|
| status | Returns ok if the operation has succeeded, or error if an
error has occurred; Returns the error_code for error details. |
| error_code |
Returns the error code when the status is |
| t2a_version_number | The current API version number. |
Example XML Response
<?xml version="1.0"?> <tps_bulk_res> <mode>normal</mode> <status>ok</status> <t2a_version_number>1.0.0</t2a_version_number> <transaction_id>wKVrW6dhYPMBEA0iQTuJ_u9YQx_L1fOvVqQ1AOboPS_U</transaction_id> </tps_bulk_res>
Command 'analyze'
Scans the uploaded CSV data and reports the number of unique telephone numbers found.
Mandatory Parameters
| Name | Description |
|---|---|
api_key or javascript_key |
Use your API key if invoking via server-side XML or SOAP. If using JSON, generate a JavaScript key using the javascript_key method. |
| command | Must be set to analyze |
| transaction_id | The ID of the job, as created by create |
Returned Values
The XML response is contained within a <tps_bulk_res> element.
| Name | Description |
|---|---|
| status | Returns ok if the operation has succeeded, or error if an
error has occurred; Returns the error_code for error details. |
| error_code |
Returns the error code when the status is |
| t2a_version_number | The current API version number. |
| num_cols | The number of columns in the CSV. |
| num_rows | The number of rows in the CSV. |
| num_telephone | The number of unique UK telephone numbers found.. |
Example XML Response
<?xml version="1.0"?> <tps_bulk_res> <mode>normal</mode> <status>ok</status> <t2a_version_number>1.0.0</t2a_version_number> <transaction_id>wKVrW6dhYPMBEA0iQTuJ_u9YQx_L1fOvVqQ1AOboPS_U</transaction_id> <num_rows>999</num_rows> <num_cols>8</num_cols> <num_telephone>752</num_telephone> </tps_bulk_res>
Command 'start'
Mandatory Parameters
| Name | Description |
|---|---|
api_key or javascript_key |
Use your API key if invoking via server-side XML or SOAP. If using JSON, generate a JavaScript key using the javascript_key method. |
| command | Must be set to start |
| transaction_id | The ID of the job, as created by create |
Returned Values
The XML response is contained within a <tps_bulk_res> element.
| Name | Description |
|---|---|
| status | Returns ok if the operation has succeeded, or error if an
error has occurred; Returns the error_code for error details. |
| error_code |
Returns the error code when the status is |
| t2a_version_number | The current API version number. |
Example XML Response
<?xml version="1.0"?> <tps_bulk_res> <mode>normal</mode> <status>ok</status> <t2a_version_number>1.0.0</t2a_version_number> <transaction_id>wKVrW6dhYPMBEA0iQTuJ_u9YQx_L1fOvVqQ1AOboPS_U</transaction_id> </tps_bulk_res>
Command 'progress'
Read the progress of the background processing of the appending. This might often be invoked as a client-side (Javascript) returning JSON.
Mandatory Parameters
| Name | Description |
|---|---|
api_key or javascript_key |
Use your API key if invoking via server-side XML or SOAP. If using JSON, generate a JavaScript key using the javascript_key method. |
| command | Must be set to progress |
| transaction_id | The ID of the job, as created by create. |
| output | Set to json if json is required. |
Returned Values
The XML response is contained within a <tps_bulk_res> element.
| Name | Description |
|---|---|
| status | Returns ok if the operation has succeeded, or error if an
error has occurred; Returns the error_code for error details. |
| error_code |
Returns the error code when the status is |
| t2a_version_number | The current API version number. |
| percentage | The progress. When "100" the job has finished processing and you may proceed to the next stage. |
Example JSON Response
{
"transaction_id":"5nTrnrVDj6Q83GKuq68IdqAQnFcKYKCnoKNsJSVLiRzY",
"percentage":"45",
"mode":"normal",
"status":"ok",
"t2a_version_number":"2.2.2.3"
}
Command 'finalise'
Use this command to commit to purchase the processed results. Providing that you have sufficient T2A credits, the price is deducted from your balance, and you may then download the processed results.
This command can be safely re-invoked; it will only charge once.
The results include the URL by which the processed CSV may be downloaded.
Mandatory Parameters
| Name | Description |
|---|---|
api_key or javascript_key |
Use your API key if invoking via server-side XML or SOAP. If using JSON, generate a JavaScript key using the javascript_key method. |
| command | Must be set to finalise |
| transaction_id | The ID of the job, as created by create. |
Optional Parameters
| Name | Description |
|---|---|
| output | Set to json for a JSON response; the default response is XML. Not applicable to the SOAP API. |
| callback | When using JSON, specify a JSONP wrapper in which the JSON response is to be wrapped. |
Returned Values
The XML response is contained within a <tps_bulk_res> element.
| Name | Description |
|---|---|
| status | Returns ok if the operation has succeeded, or error if an
error has occurred; Returns the error_code for error details. |
| error_code |
Returns the error code when the status is |
| t2a_version_number | The current API version number. |
| credit_used | The number of credits used in order to execute the request. |
| download_url | The full URL from which the processed CSV may now be downloaded. |
Example XML Response
<?xml version="1.0"?> <tps_bulk_res> <mode>normal</mode> <status>ok</status> <t2a_version_number>1.0.0</t2a_version_number> <transaction_id>wKVrW6dhYPMBEA0iQTuJ_u9YQx_L1fOvVqQ1AOboPS_U</transaction_id> <download_url>https://api.t2a.io/rest/rest.aspx?method=csv_download&job_id=2Kp9vcVWLYoisqKdADJx__3bf1LmVKVKEs6s01qOvZzz</download_url> </tps_bulk_res>
Error Codes
See the common error codes. There are no errors which are specific to this method.