Signup Login

Bulk Check the Bereavement Register

API Method: deceased_bulk

Description

This method allows for the checking of multiple items against our deceased register.

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

  • surname
  • forename
  • postcode
  • address line 1

T2A will append two further columns to the CSV:-

  • deceased status (y for deceased, n for not)
  • date of death where available, as YYYY-MM-DD

Usage

This is an asynchronous method, requiring several stages in the operation.

  1. Create a job. This is a unique transaction item that will be used to upload, process and finally download your data. Create the job using the job_create method. Please note that this is a free method.
  2. Upload your csv data using the upload command. There is a small charge for each uploaded row - see the pricing page for details.
  3. Instruct T2A to determine how many of the records in the csv are deceased, by using the count command.

    This is a free method; the result will allow you to decide whether or not to buy the full results, which show which of the records are deceased. This is the asynchronous part of the process - T2A will process this in the background. For this reason, the count command will return immediately, but the counting is happening in the background.

  4. Invoke the job_progress method 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.
  5. Invoke the totals command to discover how many of the persons in your csv are in our deceased register.
  6. If you wish to purchase the full result (i.e. the original csv appended with deceased status and date of death), invoke the commit 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 'upload'

Upload your csv data to T2A.

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 upload
job_id The ID of the job, as created by job_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.
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.
postcode_column The column containing the postcode, as a zero-based integer.

Returned Values

The XML response is contained within a <deceased_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 error. See below for error codes.

If the person is not found in our deceased register, the error code will be no_record.

If the person is found in our deceased register, the status will be OK and there will be no error code.

t2a_version_number The current API version number.
credit_used The number of credits used in order to execute the request.

Command 'count'

Starts the background processing whereby T2A will count the number of deceased persons in your data.

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 count
job_id The ID of the job, as created by job_create.

Returned Values

The XML response is contained within a <deceased_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 error. See below for error codes.

If the person is not found in our deceased register, the error code will be no_record.

If the person is found in our deceased register, the status will be OK and there will be no error code.

t2a_version_number The current API version number.

Command 'totals'

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
job_id The ID of the job, as created by job_create.

Returned Values

The XML response is contained within a <deceased_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 error. See below for error codes.

If the person is not found in our deceased register, the error code will be no_record.

If the person is found in our deceased register, the status will be OK and there will be no error code.

t2a_version_number The current API version number.
total_deceased The number of persons that are deceased in your csv data.

Command 'commit'

Use this command to commit to purchase the full results, for which T2A appends a deceased status and date of death (where known) to each row.

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
job_id The ID of the job, as created by job_create.

Returned Values

The XML response is contained within a <deceased_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 error. See below for error codes.

If the person is not found in our deceased register, the error code will be no_record.

If the person is found in our deceased register, the status will be OK and there will be no error code.

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.