Search for a company director

Example API call

---

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

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>