Contact Data Enrichment

A facility to append business or residential telephone numbers to a CSV dataset.

Improve your consumer and business marketing list with an up to date telephone number sourced from all the licensed UK telehone providers. It's free to check how many matches we find and if you choose to proceed each record searched will return a match status, a phone number where available and the TPS status.

The data must be uploaded to T2A as a csv, containing at least these columns:-

• Surname or business name
• postcode
• address line 1
• address line 2

T2A will append two 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.

1. 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.
2. Upload your csv data and specify the location of the above columns by using the upload command. This is free.
3. Start the append process. It runs in the backgroumd.
4. 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.
5. When the process is completed, check the number of records found. This is free (but only available when you are uploading 100 or more records).
6. If you wish to purchase the full result (i.e. the original csv, appended), 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 <tele_append_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 error. See below for error codes.
transaction_id	The ID of the job created.
t2a_version_number	The current API version number.

Example XML Response

---

<?xml version="1.0"?>
<tele_append_res>
	<mode>normal</mode>
	<status>ok</status>
	<t2a_version_number>1.0.0</t2a_version_number>
	<transaction_id>wKVrW6dhYPMBEA0iQTuJ_u9YQx_L1fOvVqQ1AOboPS_U</transaction_id>
</tele_append_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.
type	Must be set to res or bus to denote residential or business data. The data cannot be mixed.
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.
surname_column	The column containing the surname, as a zero-based integer.
forename_column	The column containing the forename, as a zero-based integer.
address1_column	The column containing the first line of the address, as a zero-based integer.
address2_column	The column containing the second line of the address, as a zero-based integer.
address3_column	The column containing the third line of the address, as a zero-based integer.
postcode_column	The column containing the postcode, as a zero-based integer.

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 <tele_append_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 error. See below for error codes.
t2a_version_number	The current API version number.

Example XML Response

---

<?xml version="1.0"?>
<tele_append_res>
	<mode>normal</mode>
	<status>ok</status>
	<t2a_version_number>1.0.0</t2a_version_number>
	<transaction_id>wKVrW6dhYPMBEA0iQTuJ_u9YQx_L1fOvVqQ1AOboPS_U</transaction_id>
</tele_append_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

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 <tele_append_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 error. See below for error codes.
t2a_version_number	The current API version number.

Example XML Response

---

<?xml version="1.0"?>
<tele_append_res>
	<mode>normal</mode>
	<status>ok</status>
	<t2a_version_number>1.0.0</t2a_version_number>
	<transaction_id>wKVrW6dhYPMBEA0iQTuJ_u9YQx_L1fOvVqQ1AOboPS_U</transaction_id>
</tele_append_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.

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 <tele_append_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 error. See below for error codes.
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 'totals'

Read the results of the background process to discover how many records were found. This is free, but only available if you have uploaded 100 or more records.

You may then choose whether to download the appended results

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 totals
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 <tele_append_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 error. See below for error codes.
t2a_version_number	The current API version number.
total_found	The total number of records found.
total_tel	Total number of records found, which have a telephone number.
total_tps	The number of telephone records which are TPS registered.

Example XML Response

---

<?xml version="1.0"?>
<tele_append_res>
	<mode>normal</mode>
	<status>ok</status>
	<t2a_version_number>1.0.0</t2a_version_number>
	<transaction_id>wKVrW6dhYPMBEA0iQTuJ_u9YQx_L1fOvVqQ1AOboPS_U</transaction_id>
	<total_found>183</total_found>
	<total_tel>153</total_tel>
	<total_tps>114</total_tps> 
</tele_append_res> 

Command 'finalise'

Use this command to commit to purchase the appended results. Providing that you have sufficient T2A credits, the price is deducted from your balance, and you may then download the appended results.

This command can be safely re-invoked; it will only charge once.

The results include the URL by which the appended 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 <tele_append_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 error. See below for error codes.
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"?>
<tele_append_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&amp;job_id=2Kp9vcVWLYoisqKdADJx__3bf1LmVKVKEs6s01qOvZzz</download_url>
</tele_append_res> 

Error Codes

---

Name	Description
missing_job_id	Required during some commands. transaction_id or job_id
missing_cmd	Mandatory parameter (command or cmd)

See the common error codes.