API Reference

The CompanyStack API provides programmatic access to UK business intelligence data — company profiles, financial health scores, director networks, PSC records, and more. Built on top of Companies House data, enriched with our proprietary analytics engine.

REST API JSON Responses Bearer Auth

Base URL: https://api.companystack.co.uk

Authentication

All API requests require a valid API key sent as a Bearer token in the Authorization header.

Header Format

Authorization: Bearer your_api_key_here

Getting Your API Key

Create an account at companystack.co.uk/signup
Navigate to Dashboard → Settings
Click "Create New API Key" and copy the key immediately — it won't be shown again
Alternatively, use the POST /auth/keys endpoint after logging in

Keep your API key secret. Do not expose it in client-side code, public repositories, or URLs. Rotate keys immediately if compromised via the dashboard or the DELETE /auth/keys/:id endpoint.

Quick Start

Get up and running in seconds. Here's how to look up a company across three languages:

cURL

curl -s "https://api.companystack.co.uk/company/00000006" \
  -H "Authorization: Bearer your_api_key" | jq .

JavaScript (fetch)

const res = await fetch("https://api.companystack.co.uk/company/00000006", {
  headers: {
    "Authorization": "Bearer your_api_key"
  }
});
const company = await res.json();
console.log(company.company_name);

Python (requests)

import requests

headers = {"Authorization": "Bearer your_api_key"}
resp = requests.get("https://api.companystack.co.uk/company/00000006", headers=headers)
company = resp.json()
print(company["company_name"])

Example Response

{
  "company_number": "00000006",
  "company_name": "MARINE AND GENERAL MUTUAL LIFE ASSURANCE SOCIETY",
  "company_status": "dissolved",
  "date_of_creation": "1862-10-25",
  "registered_office_address": {
    "address_line_1": "Cms Cameron Mckenna Llp Cannon Place",
    "locality": "London",
    "postal_code": "EC4N 6AF"
  },
  "sic_codes": ["65110"]
}

Rate Limits

Rate limits depend on your plan tier. Exceeding limits returns a 429 Too Many Requests response.

Plan	Requests/min	Daily Limit
Free	30	1,000
Starter	60	10,000
Business	200	100,000
Enterprise	500	500,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 198
X-RateLimit-Reset: 1719000060

Companies

GET /company/:number

Retrieve detailed company information by Companies House number.

Path Parameters

Param	Type	Description
number	string	8-digit Companies House number (e.g. `00000006`)

Example Request

curl "https://api.companystack.co.uk/company/00000006" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "company_number": "00000006",
  "company_name": "MARINE AND GENERAL MUTUAL LIFE ASSURANCE SOCIETY",
  "company_status": "dissolved",
  "type": "private-unlimited-nsc",
  "date_of_creation": "1862-10-25",
  "date_of_cessation": "2018-07-10",
  "registered_office_address": {
    "address_line_1": "Cms Cameron Mckenna Llp Cannon Place",
    "address_line_2": "78 Cannon Street",
    "locality": "London",
    "postal_code": "EC4N 6AF",
    "country": "England"
  },
  "sic_codes": ["65110"],
  "accounts": {
    "last_accounts": { "period_end_on": "2017-12-31" }
  }
}

GET /company/search?q=&limit=&offset=

Full-text search across company names and numbers. Returns paginated results.

Query Parameters

Param	Type	Required	Description
q	string	Yes	Search query (min 2 characters)
limit	integer	No	Results per page (default: 20, max: 100)
offset	integer	No	Pagination offset (default: 0)

Example Request

curl "https://api.companystack.co.uk/company/search?q=barclays&limit=5" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "results": [
    {
      "company_number": "01026167",
      "company_name": "BARCLAYS PLC",
      "company_status": "active",
      "date_of_creation": "1985-01-01",
      "registered_office_address": { "locality": "London" }
    }
  ],
  "total": 847,
  "limit": 5,
  "offset": 0
}

GET /company/autocomplete?q=&limit=

Optimised low-latency autocomplete endpoint. Returns lightweight company suggestions for search-as-you-type UIs.

Query Parameters

Param	Type	Required	Description
q	string	Yes	Search prefix (min 1 character)
limit	integer	No	Max results (default: 8, max: 20)

Example Request

curl "https://api.companystack.co.uk/company/autocomplete?q=barc&limit=5" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "suggestions": [
    { "company_number": "01026167", "company_name": "BARCLAYS PLC", "company_status": "active" },
    { "company_number": "09740322", "company_name": "BARCLAYS UK PLC", "company_status": "active" }
  ]
}

GET /company/postcode/:postcode

Find all companies registered at a given UK postcode.

Path Parameters

Param	Type	Description
postcode	string	UK postcode (e.g. `EC4N6AF` or `EC4N 6AF`)

Example Request

curl "https://api.companystack.co.uk/company/postcode/EC4N6AF" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "postcode": "EC4N 6AF",
  "total": 42,
  "companies": [
    {
      "company_number": "00000006",
      "company_name": "MARINE AND GENERAL MUTUAL LIFE ASSURANCE SOCIETY",
      "company_status": "dissolved"
    }
  ]
}

POST /company/bulk

Look up multiple companies in a single request. Maximum 50 company numbers per request.

Request Body

Field	Type	Description
numbers	string[]	Array of company numbers (max 50)

Example Request

curl -X POST "https://api.companystack.co.uk/company/bulk" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["00000006", "01026167", "09740322"]}'

Example Response

{
  "results": [
    { "company_number": "00000006", "company_name": "MARINE AND GENERAL MUTUAL..." },
    { "company_number": "01026167", "company_name": "BARCLAYS PLC" },
    { "company_number": "09740322", "company_name": "BARCLAYS UK PLC" }
  ],
  "found": 3,
  "not_found": []
}

Intelligence

Proprietary analytics endpoints that provide enriched business intelligence beyond raw Companies House data.

GET /intelligence/health/:number

Get a composite health score (0–100) for a company, computed from filing recency, financial indicators, officer stability, and charge status.

Path Parameters

Param	Type	Description
number	string	Company number

Example Request

curl "https://api.companystack.co.uk/intelligence/health/01026167" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "company_number": "01026167",
  "company_name": "BARCLAYS PLC",
  "overall_score": 82,
  "grade": "B",
  "factors": {
    "filing_recency": { "score": 90, "detail": "Last accounts filed within 6 months" },
    "officer_stability": { "score": 75, "detail": "3 officer changes in past 2 years" },
    "financial_indicators": { "score": 85, "detail": "Positive net assets trend" },
    "charge_status": { "score": 78, "detail": "2 outstanding charges" }
  },
  "computed_at": "2024-12-15T10:30:00Z"
}

GET /intelligence/benchmark/:number

Compare a company's metrics against industry peers based on SIC code. Returns percentile rankings.

Path Parameters

Param	Type	Description
number	string	Company number

Example Request

curl "https://api.companystack.co.uk/intelligence/benchmark/01026167" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "company_number": "01026167",
  "sic_code": "64191",
  "industry": "Banks",
  "peer_count": 312,
  "benchmarks": {
    "health_score": { "value": 82, "percentile": 74 },
    "company_age": { "value": 39, "percentile": 88 },
    "officer_count": { "value": 15, "percentile": 95 }
  }
}

GET /intelligence/directors/:number

Enriched director analysis including tenure, other directorships, appointment patterns, and risk indicators.

Example Request

curl "https://api.companystack.co.uk/intelligence/directors/01026167" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "company_number": "01026167",
  "total_officers": 15,
  "active_directors": 8,
  "directors": [
    {
      "name": "John Smith",
      "role": "director",
      "appointed_on": "2019-03-15",
      "tenure_years": 5.7,
      "other_directorships": 3
    }
  ],
  "risk_flags": ["high_turnover_rate"]
}

GET /intelligence/group/:number

Discover corporate group structure — parent companies, subsidiaries, and sibling entities linked via shared officers or PSCs.

Example Request

curl "https://api.companystack.co.uk/intelligence/group/01026167" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "company_number": "01026167",
  "group_size": 12,
  "parent": null,
  "subsidiaries": [
    { "company_number": "09740322", "company_name": "BARCLAYS UK PLC", "relationship": "subsidiary" }
  ],
  "siblings": [],
  "linked_via": "shared_officers"
}

GET /intelligence/timeline/:number

Chronological timeline of key company events — officer changes, filings, address changes, status updates, and charges.

Example Request

curl "https://api.companystack.co.uk/intelligence/timeline/01026167" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "company_number": "01026167",
  "events": [
    { "date": "2024-10-01", "type": "filing", "description": "Annual accounts filed" },
    { "date": "2024-07-15", "type": "officer_change", "description": "Director appointed: Jane Doe" },
    { "date": "2024-03-20", "type": "charge", "description": "New charge registered" }
  ],
  "total_events": 156
}

Live Data

Real-time proxy to the Companies House API with caching and rate-limit management.

Note: Live endpoints fetch data directly from Companies House in real-time. Response times may be slightly higher than cached database endpoints.

GET /live/officers/:number

Current and resigned officers for a company, fetched live from Companies House.

Example Request

curl "https://api.companystack.co.uk/live/officers/01026167" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "total_results": 45,
  "active_count": 15,
  "resigned_count": 30,
  "items": [
    {
      "name": "SMITH, John Andrew",
      "officer_role": "director",
      "appointed_on": "2019-03-15",
      "nationality": "British",
      "occupation": "Banker"
    }
  ]
}

GET /live/psc/:number

Persons with Significant Control — individuals or entities that hold more than 25% of shares or voting rights.

Example Request

curl "https://api.companystack.co.uk/live/psc/01026167" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "total_results": 2,
  "items": [
    {
      "name": "Mr John Smith",
      "natures_of_control": [
        "ownership-of-shares-75-to-100-percent"
      ],
      "notified_on": "2016-04-06",
      "nationality": "British",
      "country_of_residence": "England"
    }
  ]
}

GET /live/filings/:number

Complete filing history including annual accounts, confirmation statements, and statutory filings.

Example Request

curl "https://api.companystack.co.uk/live/filings/01026167" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "total_count": 234,
  "items": [
    {
      "date": "2024-09-30",
      "category": "accounts",
      "type": "AA",
      "description": "Full accounts made up to 2023-12-31"
    },
    {
      "date": "2024-06-15",
      "category": "confirmation-statement",
      "type": "CS01",
      "description": "Confirmation statement made on 2024-06-01"
    }
  ]
}

GET /live/charges/:number

Example Request

curl "https://api.companystack.co.uk/live/charges/01026167" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "total_count": 8,
  "items": [
    {
      "charge_number": 1,
      "status": "outstanding",
      "created_on": "2020-01-15",
      "delivered_on": "2020-01-20",
      "persons_entitled": [{ "name": "HSBC Bank PLC" }],
      "particulars": { "description": "All present and future assets" }
    }
  ]
}

GET /live/profile/:number

Full company profile from Companies House — the most complete single-company endpoint. Includes all core data fields.

Example Request

curl "https://api.companystack.co.uk/live/profile/01026167" \
  -H "Authorization: Bearer your_api_key"

GET /live/complete/:number

All live data combined in a single response — profile, officers, PSCs, filings, and charges. Ideal for comprehensive snapshots.

Example Request

curl "https://api.companystack.co.uk/live/complete/01026167" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "profile": { "company_number": "01026167", "company_name": "BARCLAYS PLC", "..." },
  "officers": { "total_results": 45, "items": ["..."] },
  "pscs": { "total_results": 2, "items": ["..."] },
  "filings": { "total_count": 234, "items": ["..."] },
  "charges": { "total_count": 8, "items": ["..."] }
}

PSC (Persons with Significant Control)

Query our enriched PSC database — search by name, explore control networks, and analyse ownership structures across the UK company register.

GET /psc/company/:number

Retrieve PSC records from our database for a specific company. Faster than the live endpoint and includes enrichment data.

Example Request

curl "https://api.companystack.co.uk/psc/company/01026167" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "company_number": "01026167",
  "pscs": [
    {
      "name": "Mr John Smith",
      "kind": "individual-person-with-significant-control",
      "natures_of_control": ["ownership-of-shares-75-to-100-percent"],
      "notified_on": "2016-04-06"
    }
  ],
  "total": 2
}

GET /psc/search?name=&limit=

Search for PSCs by name across all UK companies. Useful for finding all companies controlled by a specific person.

Query Parameters

Param	Type	Required	Description
name	string	Yes	PSC name to search for
limit	integer	No	Max results (default: 20, max: 100)

Example Request

curl "https://api.companystack.co.uk/psc/search?name=John%20Smith&limit=10" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "results": [
    {
      "name": "Mr John Smith",
      "company_number": "01026167",
      "company_name": "BARCLAYS PLC",
      "natures_of_control": ["ownership-of-shares-75-to-100-percent"]
    }
  ],
  "total": 156
}

GET /psc/network/:name

Discover the full network of companies linked to a PSC — all entities where a person appears as PSC and shared connections.

Example Request

curl "https://api.companystack.co.uk/psc/network/John%20Smith" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "name": "John Smith",
  "companies": [
    { "company_number": "12345678", "company_name": "EXAMPLE LTD", "role": "psc" },
    { "company_number": "87654321", "company_name": "ANOTHER LTD", "role": "psc" }
  ],
  "total_companies": 5,
  "connections": [
    { "name": "Jane Smith", "shared_companies": 3 }
  ]
}

GET /psc/stats

Overview statistics of the PSC database — total records, unique individuals, corporate PSCs, and coverage metrics.

Example Request

curl "https://api.companystack.co.uk/psc/stats" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "total_psc_records": 8945231,
  "unique_individuals": 6123456,
  "corporate_pscs": 1245678,
  "companies_with_pscs": 4567890,
  "last_updated": "2024-12-15T00:00:00Z"
}

Analytics

Aggregated analytics across the entire UK company database — industry breakdowns, geographic distribution, and macro trends.

GET /analytics/overview

High-level overview of the CompanyStack database — total companies, status breakdown, and data freshness.

Example Request

curl "https://api.companystack.co.uk/analytics/overview" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "total_companies": 5234567,
  "active_companies": 2345678,
  "dissolved_companies": 2456789,
  "status_breakdown": {
    "active": 2345678,
    "dissolved": 2456789,
    "liquidation": 34567,
    "administration": 12345,
    "other": 385188
  },
  "last_updated": "2024-12-15T06:00:00Z"
}

GET /analytics/sic/:code

Industry analysis for a given SIC code — company counts, geographic distribution, average company age, and status distribution.

Path Parameters

Param	Type	Description
code	string	SIC code (e.g. `62012` for software development)

Example Request

curl "https://api.companystack.co.uk/analytics/sic/62012" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "sic_code": "62012",
  "description": "Business and domestic software development",
  "total_companies": 98456,
  "active_companies": 67234,
  "average_age_years": 6.2,
  "top_locations": [
    { "locality": "London", "count": 23456 },
    { "locality": "Manchester", "count": 5678 }
  ]
}

GET /analytics/postcode/:prefix

Geographic analysis by postcode area — total companies, top industries, status distribution, and company density.

Path Parameters

Param	Type	Description
prefix	string	Postcode prefix (e.g. `EC`, `M`, `SW1`)

Example Request

curl "https://api.companystack.co.uk/analytics/postcode/EC" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "postcode_prefix": "EC",
  "total_companies": 145678,
  "active_companies": 89234,
  "top_industries": [
    { "sic_code": "64191", "description": "Banks", "count": 4567 },
    { "sic_code": "69201", "description": "Accounting", "count": 3456 }
  ],
  "average_age_years": 11.4
}

Enterprise

Enterprise plan required. This endpoint aggregates data from multiple sources into a single comprehensive report. Contact support@blackpeakcfo.com for enterprise access.

GET /enterprise/due-diligence/:number

Comprehensive due diligence report combining company data, health scores, officer analysis, PSC data, charges, and risk assessment into a single response.

Path Parameters

Param	Type	Description
number	string	Company number

Example Request

curl "https://api.companystack.co.uk/enterprise/due-diligence/01026167" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "company": {
    "company_number": "01026167",
    "company_name": "BARCLAYS PLC",
    "company_status": "active",
    "date_of_creation": "1985-01-01"
  },
  "health_score": {
    "overall_score": 82,
    "grade": "B"
  },
  "risk_assessment": {
    "overall_risk": "low",
    "flags": [],
    "red_flags": 0,
    "amber_flags": 2
  },
  "officers_summary": {
    "active_directors": 8,
    "total_officers": 45,
    "average_tenure_years": 4.3
  },
  "psc_summary": {
    "total_pscs": 2,
    "corporate_pscs": 1
  },
  "charges_summary": {
    "outstanding": 5,
    "satisfied": 3,
    "total": 8
  },
  "generated_at": "2024-12-15T10:30:00Z"
}

Watchlist

Monitor companies for changes. Add companies to your watchlist and receive alerts when filings, officers, or status change.

GET /watchlist

List all companies on your watchlist.

Example Request

curl "https://api.companystack.co.uk/watchlist" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "watchlist": [
    {
      "company_number": "01026167",
      "company_name": "BARCLAYS PLC",
      "added_at": "2024-12-01T09:00:00Z",
      "last_alert": "2024-12-10T14:30:00Z"
    }
  ],
  "total": 3
}

POST /watchlist

Add a company to your watchlist for monitoring.

Request Body

Field	Type	Description
company_number	string	Company number to watch

Example Request

curl -X POST "https://api.companystack.co.uk/watchlist" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"company_number": "01026167"}'

DELETE /watchlist/:number

Remove a company from your watchlist.

Example Request

curl -X DELETE "https://api.companystack.co.uk/watchlist/01026167" \
  -H "Authorization: Bearer your_api_key"

GET /watchlist/alerts/summary

Get a summary of recent alerts across all watched companies — new filings, officer changes, status changes, and more.

Example Request

curl "https://api.companystack.co.uk/watchlist/alerts/summary" \
  -H "Authorization: Bearer your_api_key"

Example Response

{
  "total_alerts": 12,
  "unread": 5,
  "alerts": [
    {
      "company_number": "01026167",
      "company_name": "BARCLAYS PLC",
      "type": "filing",
      "description": "New annual accounts filed",
      "date": "2024-12-10T14:30:00Z",
      "read": false
    }
  ]
}

Auth

Account management and API key lifecycle endpoints.

POST /auth/register

Create a new CompanyStack account.

Request Body

Field	Type	Description
email	string	Email address
password	string	Password (min 8 characters)

Example Request

curl -X POST "https://api.companystack.co.uk/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "password": "securepassword"}'

POST /auth/login

Request Body

Field	Type	Description
email	string	Email address
password	string	Password

Example Response

{
  "session_key": "sk_live_abc123def456...",
  "email": "dev@example.com",
  "plan": "starter",
  "expires_at": "2024-12-16T10:30:00Z"
}

POST /auth/keys

Create a new API key. Requires session-based authentication (login first). The full key is only returned once.

Request Body

Field	Type	Required	Description
name	string	No	Friendly label (e.g. "Production Server")

Example Response

{
  "id": "key_abc123",
  "key": "cs_live_abc123def456ghi789...",
  "name": "Production Server",
  "created_at": "2024-12-15T10:30:00Z"
}

GET /auth/keys

List all API keys associated with your account. Keys are partially masked for security.

Example Response

{
  "keys": [
    {
      "id": "key_abc123",
      "name": "Production Server",
      "prefix": "cs_live_abc1...",
      "created_at": "2024-12-15T10:30:00Z",
      "last_used": "2024-12-15T14:22:00Z"
    }
  ]
}

DELETE /auth/keys/:id

Permanently revoke an API key. This action is immediate and cannot be undone.

Path Parameters

Param	Type	Description
id	string	API key ID (e.g. `key_abc123`)

Example Request

curl -X DELETE "https://api.companystack.co.uk/auth/keys/key_abc123" \
  -H "Authorization: Bearer your_session_key"

GET /auth/usage

Get your current API usage statistics — requests today, remaining quota, and historical usage.

Example Response

{
  "plan": "starter",
  "daily_limit": 10000,
  "requests_today": 1247,
  "remaining": 8753,
  "rate_limit_rpm": 60,
  "period_start": "2024-12-15T00:00:00Z",
  "period_end": "2024-12-15T23:59:59Z"
}

Error Codes

The API uses standard HTTP status codes. Errors return a JSON object with an error field.

Code	Status	Description
400	Bad Request	Invalid parameters, missing required fields, or malformed request body
401	Unauthorized	Missing or invalid API key. Check that you're passing the `Authorization: Bearer` header
403	Forbidden	Valid key but insufficient permissions. Upgrade your plan for this endpoint
404	Not Found	Company number not found, or the requested resource does not exist
429	Too Many Requests	Rate limit exceeded. Check `X-RateLimit-Reset` header for retry timing
500	Internal Server Error	Unexpected server error. If persistent, contact support

Error Response Format

// 401 Unauthorized
{
  "error": "Invalid or missing API key"
}

// 404 Not Found
{
  "error": "Company not found: 99999999"
}

// 429 Too Many Requests
{
  "error": "Rate limit exceeded. Retry after 45 seconds"
}

Response Format

Content Type

All responses return application/json. Set the Accept: application/json header in your requests.

Success Responses

Successful responses return a 200 OK status with the requested data as the JSON body. There is no wrapping envelope — the response is the data.

Error Responses

Error responses use the appropriate HTTP status code and return a JSON object with a single error field containing a human-readable message.

{ "error": "Description of what went wrong" }

Pagination

List endpoints support pagination via limit and offset query parameters. The response includes a total field to help calculate the number of pages.

Dates

All dates are returned in ISO 8601 format: YYYY-MM-DD for date-only fields and YYYY-MM-DDTHH:mm:ssZ for timestamps.

Encoding

All responses use UTF-8 encoding. Company names may include special characters and are returned as-is from Companies House.

Ready to get started?

Create a free account and start making API calls in under a minute.

Create Free Account View Pricing