Directorships

The directorships endpoint returns JSON objects for each directory involved and registered with the business.

Example URL:

https://api2.redflagalert.net/v4/companies/01777777/directorships/

JSON Structure:

{
"data": [{
"relationships": {
"director": {
"links": {
"related": "https://api2.redflagalert.net/v4/directors/18206440/"
}
},
"company": {
"links": {
"related": "https://api2.redflagalert.net/v4/companies/01777777/"
}
}
},
"attributes": {
"town": "HARMONDSWORTH",
"first_name": "ANDREW IAN",
"surname": "FLEMING",
"suffix": null,
"title": "MR",
"date_resigned": null,
"locality": "SPEEDBIRD WAY",
"birthdate": "",
"county": null,
"appointment_type": "C",
"date_appointed": "2013-10-11",
"postcode": "UB70GB",
"address": "WATERSIDE PO BOX 365",
"nationality": null,
"other_appointments": "N",
"occupation": null
},
"type": "directorship",
"id": "645323-645323-18206440",
"links": {
"self": "https://api2.redflagalert.net/v4/directorships/645323-645323-18206440/"
}
}]
}

Attributes

Field Key

Description

Notes

town

The town of residence of the director in question.

โ€‹

first_name

The directors first name.

โ€‹

surname

The directors surname.

โ€‹

suffix

Honorary titles, such as OBE, MBE, CBE etc.

โ€‹

title

The directors title.

โ€‹

date_resigned

Date the director resigned if applicable. Will return 'null' where the director is still active.

โ€‹

locality

The equivalent of the 2nd line of address of the director.

โ€‹

birthdate

The directors date of birth (month and year) if known.

โ€‹

county

The county of residence of the director.

โ€‹

appointment_type

The type of appointment of the director

โ€‹

date_appointed

The date the director was appointed.

โ€‹

postcode

The directors post code.

โ€‹

address

First line of address of the director.

โ€‹

nationality

The directors nationality.

โ€‹

other_appointments

Any other appointments held by the director

โ€‹

occupation

Listed occupation if known. Will return 'null' if none.

โ€‹

Search for a Directorship

Like '/companies/', a search can be performed on directorships by making a GET request to the '/directorships/' endpoint:

https://api2.redflagalert.net/v3/directorships/

Returned resources will follow the JSON API format and will contain URLs in their 'links' section to the company they are linked to.

To filter directorship search results, append the criteria as request parameters in any order.

Search Parameters

The following fields can currently be searched on:

Field Name

Notes

title

The directors title

first_name

The directors first name

surname

The directors surname

name

The combination of first_name and surname, for example โ€˜Peter Smithโ€™

town

The directors town of residence

county

The directors county of residence

nationality

The nationality of the director

postcode

The postcode of the directors residence

occupation

The occupation of the director

appointment_type

The type of the appointment

The searches can be combined. For example, to find directorships held by British nationals with the surname Morgan, the query would be:

https://api2.redflagalert.net/v2/directorships/?nationality=British&surname=Morgan

When performing name searches, the 'name' field searches on full names. For example, the following query will only return directorships held by people called Peter Smith:

https://api2.redflagalert.net/v3/directorships/?first_name=Peter&surname=Smith

While the following search will return all directorships held by people whose name is either similar to 'Peter' or 'Smith', with the most relevant results returned first:

https://api2.redflagalert.net/v2/directorships/?name=Peter%20Smith

This means that 'Peter Smith' will rank highest, then 'Peter Smith Jones' then lastly, entries like 'James Smithโ€™.

If an unrecognised field name is included in search parameters, it will be ignored.

To also receive the companies the directorships are linked to, append the 'company' string in the 'include=' GET parameter:

https://api2.redflagalert.net/v3/directorships/?include=company

The response will be a compound document (see http://jsonapi.org/format/#document-compound- documents for format) containing the original search results along with the companies. All results are paginated.

https://api2.redflagalert.net/v2/directorships/?include=company