Documentation
/api/officers/find
Only available in api version 2

This API endpoint returns a list of officers that match the given criteria. The results only contain companies that are active.

Request
https://convert-ixbrl.co.uk/api/officers/find
Method Type
HTTP POST
Authentication
This endpoint requires the authentication header to be supplied. See the authentication section.
Request Body Parameters.
API Version is mandatory and all other parameters are optional but atleast one must be supplied. This endpoint returns up to 10K results per query.
Name Type Optional Description
companynumber
 string Yes The unique identifier number of the company
personnumber
 string Yes The unique identifier number for the officer
postcode
 string Yes The postal code of the address related to the person or company
partialdateofbirth
 string Yes Partial date of birth information in MM/yyyy format. For example 12/1990 for December 1990.
forename
 string Yes The given name(s) of the person
surname
 string Yes The family name or last name of the person
nationality
 string Yes The nationality of the person
apiversion
 string No The version of the API being used (currently "2")
HTTP Response codes
Status Code Description
200 Successful requests with results
404 Returned when the specified list name was not found
400 Authorisation error for when the secret key header is missing or is invalid

Response JSON Sample (only one result shown for brevity)

The order of fields may be different to what is shown below

{
    "status": "Ok",
    "result": [
        {
            "resultNumber": 1,
            "companyNumber": "09237481",
            "companyName": "EVEREST SOLUTIONS LTD",
            "appDateOrigin": "7",
            "appointmentType": "DIRECTOR",
            "personNumber": "220987453210",
            "corporateIndicator": "",
            "appointmentDate": "22/09/2018",
            "resignationDate": "15/03/2023",
            "postcode": "N12 7XY",
            "partialDateOfBirth": null,
            "title": "Mr",
            "forename": "JAMES",
            "surname": "THORNTON",
            "honours": "",
            "careOf": "",
            "poBox": "",
            "addressLine1": "84 RIVERSIDE WALK",
            "addressLine2": "CAMDEN",
            "postTown": "LONDON",
            "county": "",
            "country": "ENGLAND",
            "occupation": "DIRECTOR",
            "nationality": "BRITISH",
            "residentCountry": "UK"
        }
    ]
}

Response Properties

Name Type Nullable Description
status
 string no Contains
Ok
if the request was successful,
Error
if there was an error.
errorMessage
 string yes If the request was unsuccessful, this would contain a description of the error where available
result
 object no Contains company details and key financial data. Note that this does not include all the financial fields that are sent across in response to a call to /financials

Response properties for result object

Name Type Nullable Description
resultNumber
 integer no A sequential identifier for the result entry.
companyNumber
 string no The company's registration number.
companyName
 string no The registered name of the company.
appointmentType
 string no The type of appointment. This field will contain 'Director', 'Secretary', or be an empty string.
personNumber
 string no Companies House Identifier number for the individual appointed. Note that a given officer may have more than one identifier allocated to it by Companies House. The results are 'deduplicated' based on CompanyNumber,CompanyName,PersonNumber,AppointmentDate,PartialDateOfBirth,Forename and Surname.
corporateIndicator
 string yes Indicates if the appointment is corporate; may be empty if not applicable.
appointmentDate
 string (date) no Date when the appointment started, formatted as DD/MM/YYYY.
resignationDate
 string (date) yes Date when the person resigned or the appointment ended, formatted as DD/MM/YYYY; may be empty if still active.
postcode
 string no Postal code related to the person's address.
partialDateOfBirth
 null|string yes Partial date of birth information in MM/yyyy format, if available; otherwise null.
title
 string yes Title of the person (e.g., Mr, Mrs, Dr); may be empty.
forename
 string no The person's first name.
surname
 string no The person's last name.
honours
 string yes Any honours or titles held by the person; may be empty.
careOf
 string yes Care of address line; may be empty.
poBox
 string yes PO Box information, if applicable.
addressLine1
 string no First line of the person's address.
addressLine2
 string yes Second line of the address; may be empty.
postTown
 string no Town or city of the address.
county
 string yes County or region of the address; may be empty.
country
 string yes Country of residence; may be empty.
occupation
 string yes Person's occupation; may be empty.
nationality
 string no Person's nationality.
residentCountry
 string yes Country where the person resides; may be empty.