Shade Companies House API Documentation

Welcome to the Shade Companies House API documentation. This API allows you to retrieve information about companies, such as shareholders and documents, and also incorporate new companies.

Introduction

This documentation provides detailed information on how to interact with the Shade Companies House API endpoints. You’ll find information on obtaining an API key, authentication, base URL, available endpoints, request examples, and expected responses.

Obtaining an API Key

To use the Shade Companies House API, you need to obtain an API key. Please send a brief email to request an API key.

Email Address: [email protected]

Clicking the email address above will open a new email with the subject and body pre-filled for your convenience.

Base URL

All API requests should be made to the following base URL:

https://api.withshade.com/

All endpoints described in this documentation are relative to this base URL.

Authentication

All API endpoints require an API key for authentication. Include your API key in the X-API-KEY header for each request.

Header Example

X-API-KEY: your-api-key-here

Response Format

All API responses adhere to the JSend format, which is a simple specification for JSON APIs. The response contains the following fields:

status: Indicates the success or failure of the request.
- Possible values:
  - SUCCESS: The request was successfully processed.
  - FAIL: There was a problem with the data submitted.
  - ERROR: An error occurred on the server while processing the request.
data: Contains the payload of the response. This is where the main response data is located.
message: Provides additional information, usually used for errors.

Endpoints

1. Get Shareholders

Retrieve the list of shareholders for a specific company. Note that the request may involve asynchronous processing, and you may need to poll the endpoint until the state field indicates a terminal status of COMPLETE or FAILED.

HTTP Request

GET /api/v2/companies-house/{companyNumber}/shareholders

Full URL:

https://api.withshade.com/api/v2/companies-house/{companyNumber}/shareholders

Path Parameters

companyNumber (string): The unique number of the company.

Headers

X-API-KEY (string): Your API key.

Processing Flow

When you request shareholder information, the processing may take some time. Initially, the state field in the response may be PENDING. In such cases, you need to poll the same endpoint periodically until the state changes to either COMPLETE or FAILED. Please implement a delay of at least 1 second between polling requests to avoid overloading the server.

Example Request

curl --request GET \
  --url 'https://api.withshade.com/api/v2/companies-house/15880668/shareholders' \
  --header 'X-API-KEY: your-api-key-here'

Example Response (Initial `PENDING` State)

{
  "status": "SUCCESS",
  "data": {
    "companyNumber": "15880668",
    "state": "PENDING"
  },
  "message": null
}

Example Response (Terminal `COMPLETE` State)

{
  "status": "SUCCESS",
  "data": {
    "companyNumber": "15880668",
    "sourceDocumentUrl": "https://api.withshade.com/api/v2/companies-house/document/NcDTGJFaTTm39cj5t4vxa0C4My62XRCt1R1Qv7rsbfo",
    "state": "COMPLETE",
    "totals": {
      "totalShares": {
        "units": 1
      },
      "totalSharesByClass": [
        {
          "shareClass": "ORDINARY",
          "units": 1,
          "percentage": 1.00000
        }
      ],
      "totalSharesByName": [
        {
          "name": "SHADE GROUP INC.",
          "units": 1,
          "percentage": 1.00000
        }
      ]
    },
    "shareholdings": [
      {
        "name": "SHADE GROUP INC.",
        "shareClass": "ORDINARY",
        "units": 1,
        "percentage": 1.00000
      }
    ]
  },
  "message": null
}

Response Breakdown

Field	Type	Description
`status`	`string`	Indicates the success or failure of the request. Possible values are `SUCCESS`, `FAIL`, and `ERROR`.
`data`	`object` or `null`	Contains the main data of the response if `status` is `SUCCESS`.
├─ `companyNumber`	`string`	The company number.
├─ `sourceDocumentUrl`	`string`	URL to the source document. Present when `state` is `COMPLETE`.
├─ `state`	`string`	The current processing state of the request. Possible values are `PENDING`, `COMPLETE`, `REJECT`, and `FAILED`.
├─ `totals`	`object`	Aggregated share totals. Present when `state` is `COMPLETE`.
│ ├─ `totalShares`	`object`	Total number of shares.
│ │ └─ `units`	`number`	Total units of shares.
│ ├─ `totalSharesByClass`	`array of objects`	Shares grouped by class. Each object contains `shareClass`, `units`, and `percentage`.
│ └─ `totalSharesByName`	`array of objects`	Shares grouped by shareholder name. Each object contains `name`, `units`, and `percentage`.
└─ `shareholdings`	`array of objects`	Detailed shareholding information. Each object contains `name`, `shareClass`, `units`, and `percentage`.
`message`	`string` or `null`	Provides additional information, usually used for error messages when `status` is `FAIL` or `ERROR`.

Note: The sourceDocumentUrl, totals, and shareholdings fields are available only when state is COMPLETE. State Values for state Field:

PENDING: The request has been received and is currently being processed. You should poll the same endpoint until the state changes to COMPLETE or FAILED. Implement a delay of at least 1 second between each request.
COMPLETE: The processing is finished, and the requested data is available.
REJECT: The request was invalid or did not meet the required criteria.
FAILED: An error occurred during the processing of the request.

Polling Guidelines

Polling Frequency: Wait at least 1 second between each polling request to prevent server overload.
Termination Conditions: Stop polling when the state field is either COMPLETE or FAILED.
Error Handling: If the state is FAILED, refer to the message field for additional information.

Possible Errors

401 Unauthorized: Invalid or missing API key.
404 Not Found: Company number does not exist.
500 Internal Server Error: An unexpected error occurred.

2. Get Company Document

Retrieve a specific document related to a company. The response is a PDF file.

HTTP Request

GET /api/v2/companies-house/document/{documentId}

Full URL:

https://api.withshade.com/api/v2/companies-house/document/{documentId}

Path Parameters

documentId (string): The unique identifier of the document.

Headers

X-API-KEY (string): Your API key.

Example Request

curl --request GET \
  --url 'https://api.withshade.com/api/v2/companies-house/document/NcDTGJFaTTm39cj5t4vxa0C4My62XRCt1R1Qv7rsbfo' \
  --header 'X-API-KEY: your-api-key-here'

Example Response

The response is a PDF file. The Content-Type header will be set to application/pdf.

Response Headers

Content-Type: application/pdf
Content-Disposition: attachment; filename="document.pdf"

Response Breakdown

Since the response is a binary PDF file, there is no JSON structure to describe. Ensure that your application handles binary data accordingly.

Possible Errors

401 Unauthorized: Invalid or missing API key.
404 Not Found: Document ID does not exist.
500 Internal Server Error: An unexpected error occurred.

3. Get Structure Tree

This endpoint is coming soon.

Retrieve the ownership structure tree of a specific company.

HTTP Request

GET /api/v2/companies-house/{companyNumber}/structure

Full URL:

https://api.withshade.com/api/v2/companies-house/{companyNumber}/structure

Path Parameters

companyNumber (string): The unique number of the company.

Description

This endpoint will provide a hierarchical view of the company’s ownership structure, detailing parent and subsidiary relationships.

4. Incorporate Company

This endpoint is coming soon.

Submit information to incorporate a new company.

HTTP Request

POST /api/v2/companies-house/incorporation

Full URL:

https://api.withshade.com/api/v2/companies-house/incorporation

API Documentation

​Shade Companies House API Documentation

​Introduction

​Obtaining an API Key

​Base URL

​Authentication

​Header Example

​Response Format

​Endpoints

​1. Get Shareholders

​HTTP Request

​Path Parameters

​Headers

​Processing Flow

​Example Request

​Example Response (Initial PENDING State)

​Example Response (Terminal COMPLETE State)

​Response Breakdown

​Polling Guidelines

​Possible Errors

​2. Get Company Document

​HTTP Request

​Path Parameters

​Headers

​Example Request

​Example Response

​Response Headers

​Response Breakdown

​Possible Errors

​3. Get Structure Tree

​HTTP Request

​Path Parameters

​Description

​4. Incorporate Company

​HTTP Request

Shade Companies House API Documentation

Introduction

Obtaining an API Key

Base URL

Authentication

Header Example

Response Format

Endpoints

1. Get Shareholders

HTTP Request

Path Parameters

Headers

Processing Flow

Example Request

Example Response (Initial `PENDING` State)

Example Response (Terminal `COMPLETE` State)

Response Breakdown

Polling Guidelines

Possible Errors

2. Get Company Document

HTTP Request

Path Parameters

Headers

Example Request

Example Response

Response Headers

Response Breakdown

Possible Errors

3. Get Structure Tree

HTTP Request

Path Parameters

Description

4. Incorporate Company

HTTP Request