Search for a company director

Find out what you can do with our API...


API method to use: director_search

Skip to demo

Description


Search for a UK company director or other company officer.

This method provides a low-cost summary of company directors, including a director ID which can be used with the director_details method to obtain full details of a company director or other company officer. The data comes directly from Companies house, in pages of up to around 30 results. Each page includes links to navigate backwards or forwards to receive a new page.

As each page arrives, we cache it for 60 minutes on your behalf, to ease navigation.

Example API call


Below is an example of what your API call will look like.

http://api.t2a.io/rest/?method=director_search&javascript_key=[YOUR JAVASCRIPT KEY]&name=[CITY, TOWN or POSTCODE]&output=[OUTPUT MARKUP]

Further details and more possible parameters are documented in the sections below

Skip to example XML response

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.
name The full name e.g. Mr Ted Foster.
Use this ONLY if not using forename or surname.
forename The person's forename or initial.
Use this ONLY if not supplying the full name.
surname The person's surname.
Use this ONLY if not supplying the full name.

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.
place Enter a UK place, postcode, or postcode area. Do not specify this to do a national UK search.
page_id Use a previous_page_id or next_page_id in a previous result, or leave blank to show the first page of results.

When using a page_id, 30 results are returned per page.

Returned Values


The XML response is contained within a <director_search_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.
mode Returns normal or test when executed in the free test mode.
previous_page_id A link to the previous page of results (if present).

Note that the ID consists only of alphanumeric characters plus the _ and – characters.
next_page_id A link to the next page of results (if present).

Note that the ID consists only of alphanumeric characters plus the _ and – characters.
director_list

An array of director records.

Only one of the lists is present :-

  • If a place_list is returned, the place name is ambiguous, and the final user should be given a selection from the list.
  • If a director_list is returned, the search has returned a list of directors (or other company officers).
place_list An array of place records. This is present if the place name is ambiguous. No charge is made when a place_list is retuned.
place_list An array of place records. This is present if the place name is ambiguous. No charge is made when a place_list is retuned.
fuzzy Defaults to true. Set to false to disable fuzzy matching.

Date Details Node


Structure This node structure is commonly used, but the node will actually be pertinently named, such as dob_details or created_details.

The nodes listed below are all children of the aforementioned node.

Element Description
y The year (4 digits)
m The month 1-12
d The day of the month 1-31
en The date in a short English form D Mon YYYY, for example:-

1 May 2015
12 Jan 1974

Error Codes


See the common error codes. There are no errors which are specific to this method.

Free Test Mode


When operating in the free test mode errors are returned if mandatory parameters are missing, or it returns a dummy data response, in an identical format to a real response.

Note that the mode is returned as test when the method is operating in the free test mode.

The free test mode for this method operates in the following manner:-

  • If the place parameter is set to leeds, a place_list is returned.
  • If the name is set (to anything) a dummy director_list is returned.

Example XML Response



<?xml version="1.0"?>
<director_search_res>
  <mode>test</mode>
  <status>ok</status>
  <credit_used>0</credit_used>
  <t2a_version_number>3.3.7.9</t2a_version_number>
  <director_list>
    <director>
      <postcode>YO10 3LR</postcode>
      <title>Mr</title>
      <forename>Alan</forename>
      <surname>Fiction</surname>
      <name_single_line>Mr Alan Fiction</name_single_line>
      <dob>1956-04-01</dob>
      <director_id>sJu6um2mjNlieXCIQgCzd0MqlkxshJR71gmHzBznQMdRZKLswBFYDsvdxjYKqCRfz_</director_id>
      <dob_details>
        <y>1956</y>
        <m>4</m>
        <en>Apr 1956</en>
      </dob_details>
    </director>
  </director_list>
  <next_page_id>231671A</next_page_id>
</director_search_res>

Back to Find People

Full API method list

Demo