REST API

Programmatic access to UK business search and enrichment. Available on the Starter plan and above. All endpoints are versioned under /api/v1 and return JSON.

Authentication

Generate a key in the app under Billing & API → Create key. The full key (pk_live_…) is shown once on creation — store it securely; we only keep a hash. Pass it as a bearer token on every request (the header x-api-key is also accepted):

curl https://your-domain/api/v1/usage \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx"

Rate limiting & headers

Rate limits are enforced per API key, per minute, and scale with your plan (Starter 60/min, Growth 120/min, Scale 300/min). Every response carries:

X-RateLimit-Limit — your per-minute ceiling
X-RateLimit-Remaining — calls left in the current window
X-Credits-Remaining — enrichment credits left

Exceeding the limit returns 429 with a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

{ "error": { "code": "rate_limited",
  "message": "Rate limit exceeded. Slow down and retry shortly." } }

Endpoints

GET/api/v1/searchcounts vs monthly search quota

Search UK businesses by location, optionally filtered by keyword and industry.

Query params: location (required), query (keyword), industry, limit (default 20, max 60).

curl "https://your-domain/api/v1/search?query=marketing&location=London&limit=2" \
  -H "Authorization: Bearer pk_live_..."

{
  "data": [
    {
      "name": "Acme Marketing Ltd",
      "address": "1 High St, London, UK",
      "phone": "+44 20 7946 0000",
      "website": "https://acme.example",
      "rating": 4.6,
      "googleMapsUrl": "https://maps.google.com/?cid=123",
      "placeId": "ChIJ...",
      "types": ["marketing_agency"],
      "location": { "lat": 51.5, "lng": -0.12 }
    }
  ],
  "meta": { "count": 1, "searches_remaining": 498 }
}

POST/api/v1/enrich1 credit / result

Enrich a company by domain. Charged 1 credit only on a successful match — if nothing is found you get 404 and are not charged.

Body: { "domain": "example.com" } (website is also accepted and normalised to a domain).

curl -X POST https://your-domain/api/v1/enrich \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "domain": "acme.example" }'

{
  "data": {
    "domain": "acme.example",
    "name": "Acme Marketing Ltd",
    "description": "Full-service B2B marketing agency.",
    "logo": "https://logo.clearbit.com/acme.example",
    "foundedYear": 2014,
    "location": "London, UK",
    "employees": 42,
    "tags": ["Marketing", "B2B"],
    "source": "clearbit"
  },
  "meta": { "found": true, "credits_charged": 1 }
}

GET/api/v1/usagefree

Returns your current plan, search quota, credit balance, and rate-limit info. Costs nothing — use it to self-throttle.

curl https://your-domain/api/v1/usage \
  -H "Authorization: Bearer pk_live_..."

{
  "plan": "starter",
  "searches": { "used": 12, "limit": 500, "remaining": 488 },
  "credits": { "balance": 88 },
  "api": {
    "rate_limit_per_min": 60,
    "calls_this_period": 134,
    "enrichments_this_period": 12
  }
}

Error codes

Errors return { "error": { "code", "message" } } with the matching HTTP status.

Status	code	Meaning
400	`missing_parameter`	A required parameter (e.g. `location`) was missing.
401	`invalid_api_key`	Missing, malformed, or revoked API key.
402	`insufficient_credits`	Not enough enrichment credits — top up or upgrade.
403	`api_not_enabled`	The API isn't available on your plan (upgrade to Starter+).
429	`rate_limited` / `quota_exceeded`	Per-minute rate limit hit, or monthly search quota reached.
500	`search_failed` / `enrich_failed`	An unexpected server or upstream-provider error.

Ready to start? Generate an API key from the billing dashboard.