Forms

Submit a lead to a named form

Universal lead capture. The formSlug selects a form definition in the CMS, which determines the accepted fields, their validation rules, the post-submit behaviour and the downstream destinations. The submission is stored synchronously; HubSpot and other destinations are pushed after the response is sent, so a 200 means "stored", not "synced". No authentication. Rate limited per IP per form to the form's rateLimitPerMinute (default 5 requests per 60 seconds), answered with 429 RATE_LIMITED. Submissions are idempotent only when a valid UUID v4 event_id is supplied.

post/api/leads

Request

  • Base URL: https://www.bland.ai
  • URL: https://www.bland.ai/api/leads
  • Auth: none required

Request body

formSlugstring required

Slug of the form definition in the CMS. Determines validation and routing.

valuesLeadFieldValues required

Field values keyed by the field names defined on the form in the CMS. Validation (required, email/phone/URL format, allowed options, max length, domain policy) is driven entirely by that form definition, so the accepted keys vary per formSlug.

turnstileTokenstring

Cloudflare Turnstile token. Required by default per form (requireTurnstile). A missing token or an unreachable Cloudflare fails OPEN; a supplied token that Cloudflare explicitly rejects fails CLOSED with 403 TURNSTILE_INVALID.

event_idstring uuid

Client-minted UUID v4 conversion id. Replaying the same valid UUID v4 event_id returns the original success envelope without re-firing HubSpot, downstream destinations, or ad conversions. Omitted or invalid IDs disable idempotency for compatibility with older clients; automatic retries can then create duplicate leads. Use crypto.randomUUID() and retain the same ID for retries.

Example request

{
  "formSlug": "newsletter",
  "values": {
    "email": "jane@acme.com",
    "first_name": "Jane",
    "company": "Acme Inc"
  },
  "event_id": "b7f4c1a2-6f0e-4a1b-9c3d-7e2f5a8b1c40"
}

Response

Lead accepted and stored.

oktrue required
gtmEventNamestring

Analytics event name the client should push, when the form defines one.

submissionIdstring nullable

Stored submission id, or null when nothing was stored. Never treat null as a failure.

Example response

{
  "submissionId": "1f0a9c7e-2b31-4b64-9f0a-2c9b7e51d3aa"
}

Changes

No recorded changes to this operation across all 1 revision of this API.