LeadScore API & Embed Docs

Everything needed to send leads into LeadScore: a one-line embed script or a single HTTP endpoint.

1. Install the LeadScore embed script

Add one tag before the closing </body> tag of every page with a form. Get your site ID from the dashboard.

<script src="https://leadscore.icu/embed.js" data-site-id="YOUR_SITE_ID"></script>

Every form submission on the page is captured automatically, no per-form setup. Works with WordPress, Webflow, Squarespace, and custom HTML. Platform walkthrough: website form integration guide.

Set up in under 5 minutes

Create a site in the dashboard, you get a site ID instantly.
Paste the snippet above before your closing </body> tag.
Submit your own form once, then open the dashboard: your test lead appears scored and ranked.
Optionally connect a Slack webhook or email forwarding in site settings for hot-lead alerts within seconds.

That is the whole integration. The 5-day trial scores 50 submissions with no credit card.

2. Submit a lead to the LeadScore API

Prefer programmatic submission? POST any form data to POST https://leadscore.icu/api/v1/submit. The endpoint is CORS-enabled and needs no auth beyond your public site ID.

curl -X POST https://leadscore.icu/api/v1/submit \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "YOUR_SITE_ID",
    "formData": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "message": "Need a new website, budget $3k"
    }
  }'

{ "ok": true, "id": "sub_xxxxxxxxxxxx" }

formData accepts flat string, number, or boolean fields, whatever your form collects (name, email, budget, timeline, message). Machine-readable schema: OpenAPI spec.

A scored lead comes back in your dashboard like this (also available via GET /api/submissions/:id with an API key):

{
  "id": "sub_xxxxxxxxxxxx",
  "score": 87,
  "classification": "hot",
  "summary": "Jane runs a bakery and needs a new ordering website, budget $3k, wants it live next month.",
  "suggestedReply": "Hi Jane, thanks for reaching out, a $3k ordering site on that timeline is very doable. Are you free for a 15-minute call Thursday?",
  "spamScore": 4
}

{ "ok": false, "error": "Trial limited to 50 submissions. Upgrade to continue.", "code": "forbidden" }

Quota errors return HTTP 403 with an upgrade hint; rate limits return 429 with a Retry-After header. Every error is JSON, never HTML.

Base URL & versioning

Current version: /api/v1 (e.g. POST https://leadscore.icu/api/v1/submit). Breaking changes ship only under a new /api/vN prefix, v1 is never broken in place. The unversioned /api/submit remains a supported alias of v1 for embed installs created before versioning. When an endpoint is ever deprecated, responses carry a Deprecation header and a Sunset date (RFC 8594) at least 90 days ahead.

What happens after scoring

AI scores the lead 0-100 and classifies it hot / warm / cold / spam.
The scored lead appears in your dashboard ranked hottest-first, with a summary and suggested reply.
Slack alerts fire for hot and warm leads; email forwarding fires for hot leads (score 80+) only. Cold and spam are stored silently.

Errors are JSON

Every API error, including unknown endpoints, is JSON, never an HTML page:

{
  "ok": false,
  "error": "Unknown site",
  "code": "not_found_site",
  "hint": "Copy the siteId exactly from the LeadScore dashboard"
}

Codes: bad_request, unauthorized, forbidden, not_found, not_found_site, rate_limited. The hint field points at the fix when one applies.

Spam & bot protection

Leave top-level website / company_website fields empty, they are honeypots and non-empty values are silently dropped. Site owners can also lock a site to specific domains and set a daily submission cap in dashboard Settings. Cloudflare Turnstile bot verification is supported but not enabled on this deployment; if you need it, email us and we will enable it for your sites.

Rate limits

10 submissions per minute per IP address
100 submissions per hour per site
Per-site daily cap (default 500, adjustable 10-10000 in Settings)
Monthly scoring quota: 50 on trial, 1,000 on Pro, 3,000 on Agency (30-day rolling period), see pricing
60 reads/writes per minute per user+IP on the dashboard API

Responses carry RFC rate-limit headers so clients can self-throttle: RateLimit: limit=10, remaining=7, reset=43, RateLimit-Policy: 10;w=60, and Retry-After on HTTP 429.

Reading leads back out

Leads live in the dashboard sorted by score; any filtered view exports as CSV. Programmatic access: create an API key in dashboard Settings, then call with Authorization: Bearer ls_... (or x-api-key: ls_...):

curl https://leadscore.icu/api/submissions -H "Authorization: Bearer ls_..."

curl https://leadscore.icu/api/submissions/SUB_ID -H "Authorization: Bearer ls_..."

curl -X DELETE https://leadscore.icu/api/submissions/SUB_ID -H "Authorization: Bearer ls_..."

Keys are read/delete-scoped to your own submissions and rate-limited. Revoke anytime from Settings. New to scoring? Start with how to prioritize sales leads.

Related guides

Website form integration guide Platform-by-platform install walkthrough.
How to prioritize sales leads The triage method behind the scoring.
Lead scoring for agencies Multi-client setup and alert routing.
Start your free trial 5 days, 50 submissions, no credit card.

Agent-friendly formats

Every public page is available as markdown: request it with an Accept: text/markdown header (e.g. this page at /md/docs). Site index for agents: /llms.txt.