API Documentation — Distressed.uk

Getting Started

Authenticate with a personal access token, respect rate limits, and call the /api/v1 endpoints below. All responses are JSON. Send Accept: application/json on every request.

Authentication

Pass your API token as a Bearer credential in the Authorization header.

Header

Authorization: Bearer YOUR_API_TOKEN

Need an API Token?

Generate an API Key in your Dashboard — requires a Paid + API subscription.

MCP for Cursor & AI clients

We ship an optional Model Context Protocol (MCP) server so AI tools (Cursor, Claude Desktop, etc.) can walk you through token setup and call this API on your behalf. The MCP runs on your machine with your Bearer token — it is not a public proxy.

What it helps with

Setup guide: Paid + API plan → create token → Authorization header
Endpoint catalogue and rate-limit model
Live calls: list/get opportunities and companies (uses your quota)

Cursor · mcp.json

{
  "mcpServers": {
    "distressed-uk": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/mcp/src/index.js"],
      "env": {
        "DISTRESSED_API_TOKEN": "YOUR_API_TOKEN",
        "DISTRESSED_API_BASE": "https://distressed.uk/api/v1"
      }
    }
  }
}

Package path on this product: mcp/ (see mcp/README.md). Generate a token first at API Keys, then ask your AI client to run get_setup_guide or check_api_token.

MCP is a convenience for API subscribers. The REST docs below remain the source of truth for integrations that do not use an AI client.

Rate Limits

Quotas are per billing account (not site-wide). All tokens on the account share the same pool.

Monthly + API

60/min

3,333 / day

100,000 / month allowance

Yearly + API

60/min

10,000 / day

300,000 / month allowance

Exceeding limits returns HTTP 429 with a Retry-After header. Full policy: API AUP.

Errors

Status	Meaning
401	Missing or invalid Bearer token
403	Account is not on an API plan
404	Opportunity / company not found
422	Validation error (e.g. empty filters)
429	Rate limit exceeded

{
  "message": "API rate limit exceeded.",
  "limit_reached": true,
  "quota": { "rpm_remaining": 0, "daily_remaining": 1840 }
}

Endpoints

All paths are relative to https://distressed.uk/api/v1.

GET /opportunities

Search published distressed opportunities. Query params: district, q, status, limit (max 50).

curl -s "https://distressed.uk/api/v1/opportunities?district=Manchester&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$res = $client->get('https://distressed.uk/api/v1/opportunities', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_TOKEN',
        'Accept' => 'application/json',
    ],
    'query' => [
        'district' => 'Manchester',
        'limit' => 10,
    ],
]);
$data = json_decode((string) $res->getBody(), true);

const res = await fetch('https://distressed.uk/api/v1/opportunities?district=Manchester&limit=10', {
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    Accept: 'application/json',
  },
});
const data = await res.json();

import requests

r = requests.get(
    'https://distressed.uk/api/v1/opportunities',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Accept': 'application/json',
    },
    params={'district': 'Manchester', 'limit': 10},
)
data = r.json()

GET /opportunities/{id}

Fetch a single published opportunity by local numeric id.

curl -s "https://distressed.uk/api/v1/opportunities/42" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$res = $client->get('https://distressed.uk/api/v1/opportunities/42', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode((string) $res->getBody(), true);

const res = await fetch('https://distressed.uk/api/v1/opportunities/42', {
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    Accept: 'application/json',
  },
});
const data = await res.json();

import requests

r = requests.get(
    'https://distressed.uk/api/v1/opportunities/42',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Accept': 'application/json',
    },
)
data = r.json()

GET /companies/{number}

Return company profile enrichment plus published opportunities for a Companies House number.

curl -s "https://distressed.uk/api/v1/companies/01234567" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$res = $client->get('https://distressed.uk/api/v1/companies/01234567', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode((string) $res->getBody(), true);

const res = await fetch('https://distressed.uk/api/v1/companies/01234567', {
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    Accept: 'application/json',
  },
});
const data = await res.json();

import requests

r = requests.get(
    'https://distressed.uk/api/v1/companies/01234567',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Accept': 'application/json',
    },
)
data = r.json()

Instant webhooks

API plans can register HTTPS endpoints that receive a signed opportunity.published POST as soon as we detect a company status change into distress. Configure URL and filters (region, status, properties only, into-distressed only) at /api/webhooks.

Into distressed only — e.g. active → liquidation (skips distressed→distressed moves)
Regions — same macro areas as digests (Yorkshire, London, …)
Properties only — require at least one Land Registry title match
Verify — HMAC-SHA256 of the raw body with your signing secret; header X-Distressed-Signature: sha256=…

Event: opportunity.published

Also sent: X-Distressed-Event, X-Distressed-Delivery, X-Distressed-Timestamp.

Sample webhook payload

{
  "id": "evt_01J9EXAMPLE",
  "type": "opportunity.published",
  "created_at": "2026-09-16T10:15:00Z",
  "data": {
    "id": 42,
    "company_number": "01234567",
    "company_name": "EXAMPLE HOLDINGS LIMITED",
    "company_status": "liquidation",
    "detected_at": "2026-09-16T09:58:12Z"
  }
}

type Always opportunity.published for status-change pushes
data.company_status May appear as new_status depending on visibility masking

JSON Response Format

Successful list/show calls wrap resources in a data key. Opportunity objects expose company filings, practitioner contacts, and Land Registry title matches (visibility depends on plan).

GET /opportunities — example item

{
  "data": [
    {
      "id": 42,
      "company_number": "01234567",
      "company_name": "EXAMPLE HOLDINGS LIMITED",
      "new_status": "liquidation",
      "company_status": "liquidation",
      "status_date": "2026-09-12",
      "title_count": 3,
      "districts": ["Manchester"],
      "practitioners": [
        {
          "name": "Jane Smith",
          "role": "Liquidator",
          "firm_name": "Example Advisory LLP",
          "ip_name": "Jane Smith",
          "ip_email": "jane.smith@example-advisory.example"
        }
      ],
      "titles": [
        {
          "title_number": "MAN123456",
          "property_address": "12 Example Street, Manchester",
          "tenure": "Freehold",
          "postcode": "M1 1AE"
        }
      ],
      "land_registry_matched_charges": 2,
      "company_profile_url": "https://find-and-update.company-information.service.gov.uk/company/01234567"
    }
  ],
  "meta": { "count": 1 }
}

company_status / new_status Distressed filing status (liquidation, administration, receivership, …)
ip_name Appointed insolvency practitioner name (also under practitioners[].name)
ip_email Practitioner contact email when available from enrichment
land_registry_matched_charges Count of HM Land Registry charge / title matches linked to the company
titles[] Matched property titles (number, address, tenure, postcode)

Distressed.uk API