Incorporations - JSON API
Table of Contents
Introduction
1.0 GET /incorporations
Retrieves a list of incorporations
Request
GET
/incorporations?filters[statuses]=700,900&filters[incorporatedFrom]=20200101&filters[incorporatedTo]=20200101&page[number]=1
| Filter | Description | Example |
|---|---|---|
| filter[statuses] | CSV of statuses | 700,900 |
| filter[incorporatedFrom] | Incorporated Date Range (Ymd) | 20200101 |
| filter[incorporatedTo] | Incorporated Date Range (Ymd) | 20200101 |
| filter[createdFrom] | Record Created Date Range (Ymd) | 20200101 |
| filter[createdTo] | Record Created Date Range (Ymd) | 20200101 |
Pagination Options
The incorporations endpoint contains two methods of pagination. 1) A traditional, offset/limit search, which simply paginates through individual pages based on the predefined per page limit. 2) A cursor based pagination which accepts a given ID and returns the next X results after said ID where X is a predefined per page limit.
Cursor pagination is more efficient, and as such, the individual API calls will complete in less time. Support for traditional pagination will be removed at a future date.
| Filter | Description |
|---|---|
| page[number] | Traditional, page based pagination where "number" is the specific page you wish to view |
| page[cursor] | Cursor based pagination where "cursor" is the ID of the record you wish to start viewing from (not including the cursor ID itself) |
Response
- A 'user' resource will be returned.
- DateTime is represented as
YmdHis
{
"id": 123,
"type": "LBS",
"name": "ABC LTD",
"number": 12345678,
"incorporated": 20210901,
"status": 200,
"created_at": 20210308165141,
"updated_at": 20210308165141,
"registered_office": {
"line1": "2a",
"line2": "Rickyard Barn",
"line3": "",
"town": "Northampton",
"postcode": "NN3 6WL",
"country": "UNITED KINGDOM"
},
"user": {
"id": 456,
"organisation": "",
"title": "Mr",
"firstname": "Joe",
"lastname": "Bloggs"
}
},
2.0 GET /incorporations/[id]/officers
Retrieves a list of incorporation officers
Request
GET /incorporations/123/officers
Response
- A 'user' resource will be returned.
- DateTime is represented as
YmdHis - Officer Role 'topdog' will be a director or member depending on company type.
- Officer Role 'holder' will be a shareholder or guarantor depending on company type.
{
"id": 123,
"type": "person",
"corporate_name": "",
"title": "Mr",
"firstname": "Joe",
"lastname": "Blogs",
"roles": {
"topdog": 1,
"secretary": 0,
"holder": 1,
"psc": 1
},
"residential_address": {
"assignment": "",
"line1": 2,
"line2": "Rickyarn Barn",
"line3": "",
"town": "Blisworth",
"postcode": "NN3 8ND",
"country": "ENGLAND"
},
"service_address": {
"assignment": "",
"line1": 2,
"line2": "Rickyarn Barn",
"line3": "",
"town": "Blisworth",
"postcode": "NN3 8ND",
"country": "ENGLAND"
},
"holdings": [
{
"class": "ORDINARY",
"quantity": 10,
"currency": "GBP",
"price": 1
}
],
"nature_of_control": [
{
"name": "RIGHTTOAPPOINTANDREMOVEDIRECTORS",
"description": "Appoint or remove the majority of the board of directors",
"answer": "yes"
},
{
"name": "RIGHTTOAPPOINTANDREMOVEMEMBERS_AS_TRUST",
"description": "Right to appoint members",
"answer": "no"
},
{
"name": "OWNERSHIPOFSHARES",
"description": "Ownership of shares",
"answer": "75TO100PERCENT"
},
{
"name": "SIGINFLUENCECONTROL_AS_FIRM",
"description": "Other significant influence or control",
"answer": "no"
},
{
"name": "RIGHTTOAPPOINTANDREMOVEDIRECTORS_AS_FIRM",
"description": "Appoint or remove the majority of the board of directors",
"answer": "no"
},
{
"name": "RIGHTTOSHARESURPLUSASSETS_AS_TRUST",
"description": "Right to share surplus assets",
"answer": null
},
{
"name": "OWNERSHIPOFSHARES_AS_FIRM",
"description": "Ownership of shares",
"answer": null
},
{
"name": "RIGHTTOAPPOINTANDREMOVEDIRECTORS_AS_TRUST",
"description": "Appoint or remove the majority of the board of directors",
"answer": "no"
},
{
"name": "RIGHTTOSHARESURPLUSASSETS",
"description": "Right to share surplus assets",
"answer": null
},
{
"name": "OWNERSHIPOFSHARES_AS_TRUST",
"description": "Ownership of shares",
"answer": null
},
{
"name": "VOTINGRIGHTS",
"description": "Voting Rights",
"answer": "75TO100PERCENT"
},
{
"name": "SIGINFLUENCECONTROL_AS_TRUST",
"description": "Other significant control or influence",
"answer": "no"
},
{
"name": "RIGHTTOSHARESURPLUSASSETS_AS_FIRM",
"description": "Right to share surplus assets",
"answer": null
},
{
"name": "SIGINFLUENCECONTROL",
"description": "Other Significant influences or control",
"answer": "no"
},
{
"name": "VOTINGRIGHTS_AS_FIRM",
"description": "Voting rights",
"answer": null
},
{
"name": "RIGHTTOAPPOINTANDREMOVEMEMBERS_AS_FIRM",
"description": "Right to appoint and remove members",
"answer": "no"
},
{
"name": "RIGHTTOAPPOINTANDREMOVEMEMBERS",
"description": "Appoint and remove members",
"answer": "no"
},
{
"name": "VOTINGRIGHTS_AS_TRUST",
"description": "Voting rights",
"answer": null
}
],
"incorporation": {
"id": 123,
"name": "ABC LTD",
"number": 12345678,
"status": 200
},
"user": {
"id": 456,
"organisation": "",
"title": "Mr",
"firstname": "Joe",
"lastname": "Bloggs"
}
}
3.0 GET /incorporations/[id]/dates
Retrieves a list of incorporations dates
Request
GET /incorporations/123/dates
Response
- A 'dates' resource will be returned.
- DateTime is represented as
YmdHis
{
"company_number": 12345678,
"incorporated_date": 20210901000000,
"accounts_due": 20230601000000,
"cs01_due": 20220914000000,
"dissolved_at": null,
"created_at": 20210902091753,
"updated_at": 20211002050730
},