Documentation

Flow: your server (or trusted edge) sends one POST per form submission. Activelead stores an event, applies your risk threshold and disposable-email rule, returns JSON with traceId, riskScore, riskLevel, decision (allowed or blocked), flags, and signals (strings explaining the score).

Your account has a prepaid credit balance: each successful ingest deducts 1 credit when the event is stored. Invalid keys, validation errors, or insufficient balance return HTTP errors without consuming a credit for completed evaluations.

After sign-up, open Dashboard → your project → Settings: view or rotate the API key (format lsk_live.<publicId>.<secret>), set optional outbound webhook URL (HTTPS), copy the HMAC signing secret for webhooks, adjust Risk threshold (0–100), and toggle Block disposable emails.

Project → Integrate shows copy-paste examples (cURL, Node, PHP, browser) with your host and masked key. Project → Events lists past evaluations; you can export CSV from there when logged in.

Send your full project key on every ingest request. Two equivalent options: Authorization: Bearer lsk_live.<publicId>.<secret>, or X-Api-Key: lsk_live.<publicId>.<secret> (case-insensitive header name).

Never expose the secret in front-end bundles or public repos. Rotate the key from Settings if it leaks.

Method and path: POST /api/v1/ingest (on the same origin as your Activelead deployment, e.g. https://your-domain.com/api/v1/ingest).

leadId (string, required): stable identifier from your side (form submission id, CRM id, etc.). Max 256 characters.

formId (string, optional): label for the form or funnel. Max 256 characters.

ip (string, optional): IPv4/IPv6 of the submitter. If omitted, the API may use the connecting client IP from X-Forwarded-For / X-Real-Ip when present.

email (string, optional): valid email format; used for disposable-domain checks.

userAgent (string, optional): browser or client user-agent string. Max 512 characters.

metadata (object, optional): arbitrary JSON for your own context; included in stored events and may influence heuristics when values suggest proxy/VPN patterns in metadata text.

Per API key and client IP, requests are rate-limited (burst protection). If exceeded, the API returns HTTP 429 with a retry hint.

Your prepaid credit balance applies across all projects on the account. Each successful ingest deducts 1 credit. Without sufficient balance, ingest returns HTTP 402 (insufficient_credits) until you top up in Billing.

Success: HTTP 200, body { ok: true, data: { traceId, riskScore, riskLevel, decision, flags, signals } } (signals: e.g. disposable_domain_blocklist, baseline).

Errors: HTTP 4xx/5xx with { ok: false, error: { code, message, details? } }. Common codes: validation_error, unauthorized, invalid_api_key, insufficient_credits (HTTP 402 when out of credits), rate_limited.

If you set a webhook URL in project Settings, Activelead POSTs JSON after each successful ingest (non-blocking; automatic retries on failure; final failures are logged in audit).

Headers: User-Agent Activelead-Webhook/1.0, Content-Type application/json, X-Activelead-Timestamp (Unix seconds), X-Activelead-Signature as v1=<hex>. HMAC-SHA256 uses your project signing secret (64-char hex in Settings) over `${timestamp}.${rawBodyUTF8}` with the same JSON bytes as the POST. Verify the signature before processing.

Authenticated users can open Events for a project and download CSV (up to a large row cap per export). The export includes traceId, timestamps, leadId, formId, decision, riskScore, riskLevel, sourceIp, userAgent snippet, and flags JSON.

Export URL pattern (session required): GET /api/app/projects/{projectSlug}/events/export — use the button in the UI or the same origin with your logged-in session cookie.

Prefer server-side integration so the API secret never reaches browsers. If you must call from the client, you accept that the key can be extracted—use a separate low-privilege project or proxy through your backend instead.

Use TLS for all calls and webhook endpoints. Rotate keys after employee offboarding or suspected compromise. Monitor Events for unexpected volume or blocked traffic.