> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withshade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

# Shade Companies House API Documentation

***

<Note>
  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.
</Note>

## 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**: [hasnain@withshade.com](mailto:hasnain@withshade.com?subject=Request%20for%20API%20Key%20-%20Shade%20Companies%20House%20API\&body=Dear%20Shade%20Support%2C%0A%0AI%20would%20like%20to%20request%20an%20API%20key%20to%20access%20the%20Shade%20Companies%20House%20API.%20Please%20provide%20me%20with%20the%20necessary%20credentials.%0A%0AThank%20you%2C%0A%5BYour%20Name%5D)

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

```http theme={null}
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

```http theme={null}
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

```bash theme={null}
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)

```json theme={null}
{
  "status": "SUCCESS",
  "data": {
    "companyNumber": "15880668",
    "state": "PENDING"
  },
  "message": null
}
```

#### Example Response (Terminal `COMPLETE` State)

```json theme={null}
{
  "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

```http theme={null}
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

```bash theme={null}
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

<Note>
  This endpoint is coming soon.
</Note>

Retrieve the ownership structure tree of a specific company.

#### HTTP Request

```http theme={null}
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

<Note>
  This endpoint is coming soon.
</Note>

Submit information to incorporate a new company.

#### HTTP Request

```http theme={null}
POST /api/v2/companies-house/incorporation
```

**Full URL:**

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