Docs

Get structured UK company data in 5 minutes

This quickstart uses live endpoint paths from the Perpetua v1 API. Search examples filter to gold tier (tagged revenue). Omit the tier param to include silver balance-sheet records. Broad balance-sheet coverage on ~3M UK companies matches the market; tagged P&L revenue is a narrow subset — filter with data_quality_tier=gold or check field nullability per company.

Coverage disclosure (live counts also at GET /v1/meta/coverage)

Step 1: Create an account and get your API key

Create an account, then generate a key in settings.

Open Settings

Step 2: cURL (Greggs lookup)

curl -H "X-API-Key: pk_live_your_key_here" \
  "${PERPETUA_API_URL:-http://localhost:8000}/v1/companies/00445790"

Step 3: Multi-year time-series

Trend arrays and pre-computed CAGR — the depth moat vs snapshot-only competitors.

curl -H "X-API-Key: pk_live_your_key_here" \
  "${PERPETUA_API_URL:-http://localhost:8000}/v1/companies/00445790/time-series"

Step 4: Filing provenance (explain)

Per-field XBRL tags, confidence, and Companies House document URLs.

curl -H "X-API-Key: pk_live_your_key_here" \
  "${PERPETUA_API_URL:-http://localhost:8000}/v1/companies/00445790/explain"

Step 5: Python (requests)

import requests

BASE_URL = "http://localhost:8000"
API_KEY = "pk_live_your_key_here"
HEADERS = {"X-API-Key": API_KEY}

# Search by name
search_resp = requests.get(
    f"{BASE_URL}/v1/companies/search/",
    params={"name": "Greggs", "data_quality_tier": "gold", "limit": 5},
    headers=HEADERS,
    timeout=20,
)
search_data = search_resp.json()

# Fetch profile
profile_resp = requests.get(
    f"{BASE_URL}/v1/companies/00445790",
    headers=HEADERS,
    timeout=20,
)
company = profile_resp.json()

print(company["company_number"], company["name"], company["data_quality_tier"], company["owner_max_age"])

Step 6: JavaScript (fetch)

const baseUrl = "http://localhost:8000";
const apiKey = "pk_live_your_key_here";
const headers = { "X-API-Key": apiKey };

const searchResp = await fetch(
  `${baseUrl}/v1/companies/search/?name=Greggs&data_quality_tier=gold&limit=5`,
  { headers }
);
const searchData = await searchResp.json();

const profileResp = await fetch(
  `${baseUrl}/v1/companies/00445790`,
  { headers }
);
const company = await profileResp.json();

console.log(company.company_number, company.name, company.data_quality_tier, company.owner_max_age);