Fetching an Officer

Description

The OpenCorporates officers endpoint allows you to pull richer information than what is provided in either the officer search or get company endpoint. However, unlike companies that are keyed from their jurisdiction and local company identifier – officers are assigned their own identifier within our platform that requires you to pinpoint the officer from either an officer search or from a company record.

GET officers/:id

The officer identifier can be found from the company search result within the officer block:

 "officers": [
      {
        "officer": {
          "id": 206814968,
          "name": "ROBERT MURRAY MCKINNON",
          "position": "director",
          "uid": null,
          "start_date": "2010-11-18",
          "end_date": "2011-03-17",
          "opencorporates_url": "https://opencorporates.com/officers/206814968",
          "occupation": "DIRECTOR",
          "inactive": true,
          "current_status": null,
          "address": "ASTON HOUSE CORNWALL AVENUE, LONDON, N3 1LF, UNITED KINGDOM",
          "nationality": "BRITISH",
          "date_of_birth": null
        }
      },
      {
        "officer": {
          "id": 206814999,
          "name": "CHRISTOPHER TAGGART",
          "position": "director",
          "uid": null,
          "start_date": "2010-11-18",
          "end_date": null,
          "opencorporates_url": "https://opencorporates.com/officers/206814999",
          "occupation": "DEVELOPER",
          "inactive": null,
          "current_status": null,
          "address": "ASTON HOUSE CORNWALL AVENUE, LONDON, N3 1LF, UNITED KINGDOM",
          "nationality": "BRITISH",
          "date_of_birth": null
        }
      }
]

In our examples below we take the officers[n].officer.id to pass into our officer endpoint.

Further API documentation can be found here.

Examples

This example uses the following officer identifier:
officer.id = 206814999

curl "https://api.opencorporates.com/v0.4/officers/206814999?api_token=xxxxxxxxxx"

// Requires
const OCUtils = require('./ocutil.js'); // OC Utilities
const jp = require('jsonpath');         // JSONPath
const { exit } = require('process');

// Set http request options
const options = {
  hostname: 'api.opencorporates.com',
  port: 443,
  path: '/v0.4/officers/search',
  method: 'GET',
  headers : {'Content-Type' : 'application/json'}
};

// Check our command line has enough information to continue
var requiredCommandLineArguments = ["q", "api_token" ];

//If not, explain what is needed on the command line
if(!OCUtils.isCommandLineComplete(requiredCommandLineArguments)){
    console.log("Required Arguments:")
    console.log("--api_token your API Token")
    console.log("--q the officer to query e.g. 'Christoper Taggart'")
    console.log("")
    process.exit(1);
}else{
    // Fetch the command line arguments
    var commandLineArguments = OCUtils.getCommandLineArguments(requiredCommandLineArguments);

    // Append command line arguments as URL parameters onto the request URL
    options.path = OCUtils.addURLParameter(options.path, "q", commandLineArguments.get("q"), true);
    options.path = OCUtils.addURLParameter(options.path, "api_token", commandLineArguments.get("api_token"), false);
    options.path = OCUtils.addURLParameter(options.path, "jurisdiction_code", "gb", false);


    // Little bit of debug to explain what we have called.
    console.log("Searching for: '%s'", commandLineArguments.get("q"));
    console.log("Using API Key: %s", commandLineArguments.get("api_token"));
    console.log("Request URL: %s%s%s", (options["port"] == 443 ? "https://":"http://"), options["hostname"], options["path"], );    

    // Make the request to the OC endpoint to search officers
    OCUtils.makeOCRequest(options, function(statusCode, payload){
        //Use JSONPath to pull each of the officers.
        var officers = jp.query(payload, "$.results.officers..officer");    
        console.log("");
        // Print (as a table) the officers array from the response
        console.table(officers, ["id", "name", "position", "opencorporates_url"]);
        console.log("");
    });
}

Results

cURL response is the complete response from the API.

NodeJS example has flattened its JSON into key pairs for illustrative purposes and output via console.table.

{
  "api_version": "0.4",
  "results": {
    "officer": {
      "id": 206814999,
      "uid": null,
      "name": "CHRISTOPHER TAGGART",
      "position": "director",
      "start_date": "2010-11-18",
      "end_date": null,
      "opencorporates_url": "https://opencorporates.com/officers/206814999",
      "occupation": "DEVELOPER",
      "current_status": null,
      "inactive": null,
      "nationality": "BRITISH",
      "date_of_birth": null,
      "address": "ASTON HOUSE CORNWALL AVENUE, LONDON, N3 1LF, UNITED KINGDOM",
      "source": {
        "source_type": "external",
        "publisher": "UK Companies House",
        "url": "http://xmlgw.companieshouse.gov.uk/",
        "terms": "UK Crown Copyright",
        "retrieved_at": "2015-12-20T02:37:10+00:00"
      },
      "company": {
        "name": "OPENCORPORATES LTD",
        "jurisdiction_code": "gb",
        "company_number": "07444723",
        "opencorporates_url": "https://opencorporates.com/companies/gb/07444723"
      }
    }
  }
}

demo@oc % node officer_details.js --api_token xxxxxxxxxxx --jurisdiction_code gb --id 206814999
Officer ID: '206814999'
Using API Key: xxxxxxxxxxx
Request URL: https://api.opencorporates.com/v0.4/officers/206814999?api_token=xxxxxxxxxxx

Officer 206814999 Details
┌─────────┬──────────────────────┬───────────────────────────────────────────────────────────────┐
│ (index) │         key          │                             value                             │
├─────────┼──────────────────────┼───────────────────────────────────────────────────────────────┤
│    0    │         'id'         │                           206814999                           │
│    1    │        'name'        │                     'CHRISTOPHER TAGGART'                     │
│    2    │      'position'      │                          'director'                           │
│    3    │     'occupation'     │                          'DEVELOPER'                          │
│    4    │    'nationality'     │                           'BRITISH'                           │
│    5    │     'start_date'     │                         '2010-11-18'                          │
│    6    │ 'opencorporates_url' │        'https://opencorporates.com/officers/206814999'        │
│    7    │      'address'       │ 'ASTON HOUSE CORNWALL AVENUE, LONDON, N3 1LF, UNITED KINGDOM' │
│    8    │      'company'       │                           [Object]                            │
└─────────┴──────────────────────┴───────────────────────────────────────────────────────────────┘