---
title: "Create a real lead"
method: POST
path: "/leads"
---

# Create a real lead

`POST /leads`

## Request

- Base URL: `https://gringofunnels.com/api/v1`
- URL: `https://gringofunnels.com/api/v1/leads`
- Auth: HTTP bearer

Idempotent lead ingestion with optional bounded first-touch attribution. Set emailMarketingConsent=true only after an explicit marketing opt-in; analytics consent is never reused. Never send raw gclid/fbclid values. Demo fixtures are never returned by this API or counted as activation.

## Headers

- `Idempotency-Key` string, required

## Request body

- LeadCreate
  - `externalId` string
  - `funnelId` string, uuid
  - `name` string, required
  - `email` string, email, required
  - `phone` string
  - `city` string
  - `source` string
  - `attribution` LeadAttributionInput: Privacy-safe first-touch acquisition fields. Send a pathname only (never a full landing/referrer URL). Raw advertising click identifiers are not accepted or stored.
    - `utmSource` string
    - `utmMedium` string
    - `utmCampaign` string
    - `utmContent` string
    - `utmTerm` string
    - `landingPath` string
    - `referrerHost` string
  - `emailMarketingConsent` boolean: Explicit opt-in to marketing e-mail for this capture.
  - `stage` string
  - `score` integer

## Response `200`

Existing lead returned for an idempotent retry

- LeadCreateResponse
  - `data` object, required
    - `id` string, uuid, required
    - `createdAt` string, date-time, required
    - `duplicate` boolean, required

## Other responses

- `201`: Lead created
- `400`: Missing or malformed request metadata
- `401`: Missing or invalid API key
- `413`: Request body exceeds the endpoint-specific bound
- `415`: Content-Type must be application/json
- `422`: Invalid query parameters
- `429`: Tenant and endpoint allowance exceeded (600 requests per 60 seconds)
- `503`: A required API protection or dependency is unavailable

---

[API](https://skmtc.dev/gringofunnels/apis/gringo-funnels-api.md) · [All operations](https://skmtc.dev/gringofunnels/apis/gringo-funnels-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gringofunnels/apis/gringo-funnels-api/revisions/b57b5e365b56?raw)