Integrate a website without exposing its key.

Install the modern ESM package

leadpending-web is ESM-only, has no runtime dependencies, and targets modern bundlers and Node.js 18.13 or newer. Import only its public entry points: leadpending-web, leadpending-web/browser, and leadpending-web/server. The npm package also contains INTEGRATION.md as an offline handoff for coding agents.

npm install leadpending-web

Check the submission and collect the visit

Call trackPageView() on every navigation. It safely keeps up to 200 page steps, first referrer, landing URL, session start, and the standard UTM/gclid/fbclid keys in sessionStorage; collectVisitor() adds live browser context at submit time. checkSubmission() returns a verdict only: you decide whether to stop a filled honeypot, a non-negative elapsed time below 1,200 ms, an empty message, fewer than 3 Unicode code points, or one non-space character repeated at least 4 times.

import { checkSubmission, newIdempotencyKey } from 'leadpending-web'
import { collectVisitor, trackPageView } from 'leadpending-web/browser'

// Run on every page navigation. The SDK keeps this tab's journey in sessionStorage.
trackPageView()

// Generate once for this user submission and keep it if your own POST is retried.
const submissionId = newIdempotencyKey('contact')
const verdict = checkSubmission({
  message: form.message.value,
  honeypot: form.company_url.value,
  elapsedMs: Date.now() - formShownAt,
})
if (!verdict.ok) return

await fetch('/api/contact', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    submissionId,
    name: form.name.value,
    email: form.email.value,
    message: form.message.value,
    pageUrl: location.href,
    visitor: collectVisitor(),
  }),
})

Create the lead from server-only code

LeadPendingClient sends application/json to https://api.leadpending.com/api/v1/leads. Pass the browser visitor object through, then use connection for IP, user agent, and edge country observed by your server; non-empty connection values override those visitor fields without mutating the input. LeadPending is the only application store: do not mirror, cache, or fall back to a local lead row or submission event. Only return success after createLead resolves.

import { LeadPendingClient, LeadPendingError } from 'leadpending-web/server'

const leadpending = new LeadPendingClient({
  apiKey: process.env.LEADPENDING_API_KEY!,
})

export async function POST(request: Request) {
  const form = await request.json()

  try {
    const lead = await leadpending.createLead(
      {
        external_id: form.submissionId,
        name: form.name,
        email: form.email,
        message: form.message,
        page_url: form.pageUrl,
        visitor: form.visitor,
      },
      {
        idempotencyKey: form.submissionId,
        connection: {
          ip: request.headers.get('x-real-ip') ?? undefined,
          userAgent: request.headers.get('user-agent') ?? undefined,
          country: request.headers.get('cf-ipcountry') ?? undefined,
        },
        signal: request.signal,
      },
    )
    return Response.json({ accepted: true, replay: lead.replay })
  } catch (error) {
    if (error instanceof LeadPendingError) {
      console.error('LeadPending rejected lead', { status: error.status, code: error.code })
    }
    return Response.json({ accepted: false }, { status: 502 })
  }
}

The SDK is the recommended production path. This equivalent raw request is useful for checking the endpoint and headers independently; it still runs only from a trusted server, never from browser code.

curl --request POST 'https://api.leadpending.com/api/v1/leads' \
  --header 'Authorization: Bearer lp_live_<server-secret>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: contact-018f47f2' \
  --data '{
    "external_id": "contact-018f47f2",
    "name": "Jane Doe",
    "email": "[email protected]",
    "message": "Can you help with three websites?",
    "page_url": "https://example.org/pricing",
    "locale": "en",
    "metadata": { "budget": "3000-5000" },
    "visitor": { "country": "DE", "utm": { "utm_source": "google" } }
  }'

Keep one application store and erase by external ID

Do not insert or upsert an acquisition-form payload into a product database. A separate local account is fine: derive the same stable external_id from its ID without an application mapping. On erasure, call the site-scoped DELETE endpoint before deleting the account. It soft-deletes only the active lead belonging to this API key's exact site, returns 204 when already absent, and never accepts a browser credential.

curl --request DELETE \
  'https://api.leadpending.com/api/v1/leads/by-external-id?external_id=contact-018f47f2' \
  --header 'Authorization: Bearer lp_live_<server-secret>'

# 204 No Content. Repeating the same request is also 204.

Validate the real payload without creating a lead

validateLead uses the same authentication, strict decoding, lead validation, visitor normalization, and spam scoring as intake. It returns the resolved subject and locale, normalized visitor block, spam_score, and spam_reasons, but creates no lead, message, or notification. Run it with a representative production payload and a real site key before launch.

const preview = await leadpending.validateLead(
  {
    email: '[email protected]',
    message: 'Can you help with three websites?',
    visitor: { country: 'XX', ip: '203.0.113.77' },
  },
  { connection: { userAgent: 'integration-test' } },
)

// No lead or notification was created:
// {
//   would_accept: true,
//   subject: 'Inquiry from Example',
//   locale: 'en',
//   visitor: { ip: '203.0.113.77', user_agent: 'integration-test' },
//   spam_score: 0
// }

Lead fields and hard limits

Visitor context: let the SDK collect it

Use trackPageView() and collectVisitor() instead of maintaining a second collector. Every property is optional. JSON types and unknown fields are checked strictly when the body is decoded; after that, malformed or oversized telemetry values are dropped or truncated instead of rejecting an otherwise valid lead.

The normalized visitor object is capped at 48 KiB. If it is larger, the server removes the oldest journey steps until it fits; if it still cannot fit, it drops the whole visitor object. An empty object is omitted. The raw request body still has a hard 64 KiB limit, and unknown JSON fields or wrong JSON types return 400 before this best-effort cleanup.

Success responses

A new lead returns 201. A match by Idempotency-Key or external_id returns the existing lead with 200; LeadResult.replay is derived from that status. Both responses use { data: { id, status, created_at }, request_id }. Only a resolved, validated 2xx SDK result means accepted; malformed 2xx response data is reported as INVALID_RESPONSE.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "data": {
    "id": "0198…",
    "status": "pending",
    "created_at": "2026-08-02T12:00:00Z"
  },
  "request_id": "0198…"
}

Typed failures and HTTP codes

A valid non-2xx API response throws LeadPendingError with status, code, and a safe synthetic message; server details and request IDs are not exposed by the SDK. Network failures remain their original errors, and cancellation remains AbortError or the signal's explicit reason. Log status and code only—never the key, email, message, or visitor payload.

Spam scoring and email checks

Spam signals classify; they never reject a structurally valid lead. Every new real lead is stored even when its score is high, and the operator remains in control.

checkSubmission() is a separate preflight classifier for the browser. It returns only the first reason that fires: honeypot_filled, submitted_too_fast, message_empty, message_repeated_character, or message_very_short. The caller decides whether to stop the submission.

Intake trims the message, scores conservative content signals, and checks whether the email domain has MX or, as a fallback, A/AAAA records. DNS has a 2-second timeout and a 30-minute cache. Timeout or temporary resolver failure is fail-open: it adds no signal.

Scores combine as P = 1 − Π(1 − Pi) and are capped at 0.99. A score of 0.5 or more is shown as suspicious in the workspace. validateLead returns the same score and stable reason codes before launch.