# Developer docs: LeadScore API and embed

LeadScore turns website form submissions into AI-scored leads. Two integration surfaces: an embed script (captures forms automatically) and an HTTP endpoint (submit leads programmatically).

## Base URL & versioning

- Current version: `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` is a supported alias of v1.
- Deprecations are signalled with `Deprecation` and `Sunset` headers at least 90 days ahead.

## 1. Install the embed script

Add one tag before the closing `<body>` tag of every page with a form:

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

Every form submission on the page is captured and scored automatically. No per-form setup.

## 2. Submit a lead via the API

```
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" }
  }'
```

Response `200`:

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

`formData` accepts flat string/number/boolean fields, use whatever your form collects (name, email, budget, timeline, message).

Errors are always JSON, never HTML pages:

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

Full schema: [OpenAPI spec](/openapi.json).

## Spam & bot protection

- Top-level `website` / `company_website` fields are honeypots: leave them empty.
- Turnstile bot verification is supported but not enabled on this deployment; email us to enable it.
- Owners can lock a site to specific domains and set a daily cap in Settings.

## Notifications

- Slack alerts fire for hot and warm leads; email forwarding fires for hot leads (score 80+) only.
- Cold and spam submissions are stored silently.

## Rate limits

- 10 submissions/min per IP, 100 submissions/hour per site, per-site daily cap (default 500).
- Monthly scoring quota: 50 on trial, 1,000 on Pro, 3,000 on Agency (30-day rolling period).
- 60 reads/writes per minute per user+IP on the dashboard API.
- Responses carry RFC headers so clients can self-throttle:
  - `RateLimit: limit=10, remaining=7, reset=43`
  - `RateLimit-Policy: 10;w=60`
  - `Retry-After` on HTTP 429

## Reading scored leads back

Leads appear in the dashboard ranked by score. Export any view as CSV from the dashboard.
Programmatic access: create an API key in Settings, then `Authorization: Bearer ls_...` (or `x-api-key: ls_...`) against `GET /api/submissions`, `GET /api/submissions/:id`, `DELETE /api/submissions/:id`.

## More

- [LeadScore: Know which leads to call first](https://leadscore.icu/)
- [Developer Docs: LeadScore API and embed installation](https://leadscore.icu/docs)
- [About LeadScore](https://leadscore.icu/about)
- [Contact LeadScore](https://leadscore.icu/contact)
- [Privacy Policy](https://leadscore.icu/privacy)
- [Terms of Service](https://leadscore.icu/terms)
- [Cookie Policy](https://leadscore.icu/cookies)
- [Data Processing Addendum](https://leadscore.icu/dpa)
- [Subprocessors](https://leadscore.icu/subprocessors)
- [AI Lead Scoring for Agencies That Live Off Contact Forms](https://leadscore.icu/for-agencies)
- [Lead Scoring for Freelancers Who Can't Afford to Call Second](https://leadscore.icu/for-freelancers)
- [WordPress Lead Form Monitoring and Contact Form Lead Scoring](https://leadscore.icu/wordpress)
- [Webflow Lead Tracking and Form Scoring in One Embed](https://leadscore.icu/webflow)
- [Best Lead Scoring for Agencies (2026): What Actually Matters](https://leadscore.icu/best-lead-scoring-for-agencies)
- [How to Prioritize Sales Leads Without a CRM](https://leadscore.icu/prioritize-sales-leads)
- [Website Form Integration Guide: Score Every Submission](https://leadscore.icu/website-form-integration)
- [Log in](https://leadscore.icu/login)
- [Start your free trial](https://leadscore.icu/signup)