API Documentation

Prospect Finder API (trial)

A trial endpoint returning recently incorporated UK companies from Kevarin's stored Companies House records. Base URL: https://visual-sparkle-checker.lovable.app/api/public/v1/prospects

Global data coverage, full live API access and x402 payments are planned, not yet available. The existing Prospect Finder endpoint is an experimental, read-only trial, not a production API.

GEThttps://visual-sparkle-checker.lovable.app/api/public/v1/prospectsExperimental · read-only trial

Returns recently incorporated UK companies from Kevarin's stored copy of Companies House records. It only reads, and it makes no live calls to Companies House. Any browser or server can call it, and every response is JSON. No key or sign-up is needed, and there are no required parameters. The data is updated once a day, at about 06:00 UTC.

Example request

curl "https://visual-sparkle-checker.lovable.app/api/public/v1/prospects?postcode_area=LS&limit=1"

Request trial access

Opens your email app with a pre-filled message to signalgrid.contact@gmail.com. Tell us what you're building and we'll help you get started.

Parameters

All are optional and combine with AND (every filter must match).

Name	Format	Default	Notes
incorporated_from	YYYY-MM-DD	none	Inclusive
incorporated_to	YYYY-MM-DD	none	Inclusive
postcode_area	1–2 letters	none	Any capitalisation. M matches M1, M14… but not ME
town	1–60 characters	none	Exact town name, any capitalisation
status	lowercase, e.g. active	none	Companies House status value
company_type	lowercase, e.g. ltd	none	Companies House type value
sic	62020 or 62020,62090 (max 10)	none	Five-digit SIC 2007 codes; matches any
limit	1–100	25	Page size
cursor	value of meta.next_cursor	first page	Treat as opaque

• Invalid values for these parameters return 400. Parameters not listed here are ignored.
• Dates: dates are checked strictly: an impossible date such as 2026-13-40 returns 400 with code invalid_query.

Pagination

Results are ordered by newest incorporation date, then by company number.

Example · two pages

# Page 1
curl "https://visual-sparkle-checker.lovable.app/api/public/v1/prospects?postcode_area=LS&limit=2"
#   meta.next_cursor = "2"

# Page 2: same filters, plus cursor
curl "https://visual-sparkle-checker.lovable.app/api/public/v1/prospects?postcode_area=LS&limit=2&cursor=2"
#   meta.next_cursor = "4"   (null means there are no more pages)

Keep the same filters and limit on every page.

Response (200)

• data[]: one entry per company.
• facts: from Companies House: status, company_type, incorporation_date, registered_address, postcode, town, sic_codes[].
• derived: computed by Kevarin, not Companies House: method, industry[] (code, division, division_title) and region.
• source: provider ("Companies House"), url (the company's public Companies House page) and retrieved_at.
• meta: total, limit, next_cursor (string or null), coverage (incorporated_from, incorporated_to, complete_days), attribution, note, facts_vs_derived.

Real live example · GET ?postcode_area=LS&limit=1

{"data":[{"company_number":"17515944","name":"AUTOHAUS PRESTIGE LTD",
  "facts":{"status":"active","company_type":"private-limited-guarant-nsc","incorporation_date":"2026-10-13",
  "registered_address":"9 Nowell Terrace, Leeds, LS9 6HX, England","postcode":"LS9 6HX","town":"Leeds","sic_codes":["45112"]},
 "derived":{"method":"Fixed lookups: SIC 2007 division titles (ONS) and postcode area to ITL1 region. Not from Companies House.",
  "industry":[{"code":"45112","division":"45","division_title":"Wholesale and retail trade and repair of motor vehicles and motorcycles"}],
  "region":"Yorkshire and The Humber"},
 "source":{"provider":"Companies House","url":"https://find-and-update.company-information.service.gov.uk/company/17515944","retrieved_at":"2026-10-14T20:53:04.586+00:00"}}],
 "meta":{"total":342,"limit":1,"next_cursor":"1",
  "coverage":{"incorporated_from":"2026-09-30","incorporated_to":"2026-10-13","complete_days":14},
  "attribution":"Contains public sector information from Companies House, licensed under the Open Government Licence v3.0.",
  "note":"A new incorporation is a registration fact. It is not evidence that the company needs, or will buy, any product or service.",
  "facts_vs_derived":"`facts` are copied from Companies House. `derived` values are computed by Kevarin and labelled with their method."}}

Rate limits

• Limits: 30 requests per minute and 600 per day for each caller, plus 5,000 per day across all callers. Days reset at 00:00 UTC.
• Every request counts: that includes invalid ones.
• Headers on every response: X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day.
• Fair use: please cache results on your side.

Errors (current formats)

Status	When	Body
400	Invalid parameter value	{"error":{"code":"invalid_query","message":"One or more query parameters are invalid. See error.fields.","status":400,"fields":[{"field":"incorporated_from","issue":"Must be a real calendar date in YYYY-MM-DD format."}]}}
429	Limit exceeded	{"error":{"code":"rate_limited","message":"…","status":429,"scope":"minute\|day\|global","limit":30,"reset_at":"…","retry_after_seconds":12}}, plus a Retry-After header
500	Stored records couldn't be read	{"error":{"code":"internal_error","message":"Could not query stored records. Please retry later.","status":500}}
503	Limit check temporarily unavailable	{"error":{"code":"service_unavailable","message":"Service temporarily unavailable. Please retry shortly.","status":503,"retry_after_seconds":30}}, plus Retry-After: 30

No API key is used during the trial, so 401 is never returned.

Attribution and data use

• Licence: each response includes the line "Contains public sector information from Companies House, licensed under the Open Government Licence v3.0" (licence text). Please keep it whenever you display or pass on the data.
• Source links: each record's source.url links to the company's official Companies House page.
• Not a sales signal: a new incorporation is a registration fact, not evidence that the company needs or will buy anything.

Testing safely

You only need the address above. Test with curl, a browser or Postman. No account, key, database access or collector access is given or needed. The API can only read public company records; it can't reach usage logs, rate-limit data, secrets or the demo Signals Explorer.

Questions, problems or higher limits for a trial? Email signalgrid.contact@gmail.com.

The endpoints below are planned and not yet available. Their responses are illustrative examples, not real data.

GET/v1/opportunitiesPlanned

Scored commercial opportunities derived from recent signals.

Query parameters

region, type, min_score, since

Example response · illustrative

{
  "data": [
    {
      "id": "opp_demo_7f2a",
      "company": "Quantera Health Ltd (demo)",
      "signal_type": "funding",
      "location": { "town": "Cambridge", "region": "East of England" },
      "opportunity_score": 88,
      "inferred": true,
      "rationale": "Newly funded companies typically hire and procure software.",
      "sources": [{ "name": "Statement of capital", "event_date": "2026-10-02" }]
    }
  ],
  "illustrative": true
}

GET/v1/businesses/newPlanned

Newly incorporated UK companies with SIC codes and location.

Query parameters

region, sic_code, since

Example response · illustrative

{
  "data": [
    {
      "company_number": "DEMO0001",
      "name": "Harbourline Logistics Ltd (demo)",
      "incorporated_on": "2026-10-08",
      "sic_codes": ["49410"],
      "postcode_district": "BS1",
      "confidence": "high"
    }
  ],
  "illustrative": true
}

GET/v1/planningPlanned

Planning applications and decisions with commercial relevance.

Query parameters

authority, status, use_class, since

Example response · illustrative

{
  "data": [
    {
      "reference": "DEMO/26/0412",
      "authority": "Leeds",
      "status": "submitted",
      "proposal": "Change of use from office to light industrial",
      "floor_area_sqm": 1200,
      "received_on": "2026-10-06"
    }
  ],
  "illustrative": true
}

GET/v1/regions/{region}/dailyPlanned

A daily digest of signals and top opportunities for a region.

Query parameters

date

Example response · illustrative

{
  "region": "North West",
  "date": "2026-10-05",
  "counts": { "new_businesses": 142, "planning": 37, "leadership_changes": 21 },
  "top_opportunities": ["opp_demo_19c4", "opp_demo_a03e"],
  "illustrative": true
}

Payments via x402

Planned · not enabled

We plan to use the x402 protocol so agents can pay per request. An unpaid call would receive an HTTP 402 response describing the price; the agent pays in USDC and retries. None of this is enabled yet — no payments can be made today.

Planned 402 response · illustrative

HTTP/1.1 402 Payment Required
{
  "price": "0.02",
  "currency": "USDC",
  "resource": "/v1/opportunities"
}

Developer interest

Build with Kevarin

Interested in testing the future UK business intelligence API? Tell us what you're building, the data you need and your expected usage. No launch date or access is guaranteed.

Request trial access

signalgrid.contact@gmail.com