Documentation
Documentation menu
API DOCUMENTATION

/api/officers/find

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

Officers Active Only Version 2

Version and Endpoint

Only available in API version 2

Request

https://convert-ixbrl.co.uk/api/officers/find

This endpoint requires authentication headers. See Authentication documentation.

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 officer details and key data. Note that this does not include all the fields that are sent across in response to a call to /officers/find

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.