Track lead events

Endpoint

POST /track/lead

Track a lead conversion event for a short link. This endpoint creates a lead event and upserts a customer record.

Endpoint text 
POST /track/lead

Authentication

Requires authentication with an API key that has the conversionsWrite scope.

Request Body

Accepts a single object (not an array). All fields are required unless marked optional.

ParameterTypeRequiredDescription
clickId (body)stringYesClick ID string to attribute the lead. Use an empty string ("") for deferred tracking.
eventName (body)stringYesLead event name (1-255 characters).
customerExternalId (body)stringYesCustomer external ID (1-100 characters). Used to upsert the customer.
customerName (body)stringYesCustomer name (max 100 characters).
customerEmail (body)string (email)NoCustomer email, max 100 characters. Optional. Can be null to clear.
customerAvatar (body)string (URL)NoHTTPS customer avatar URL. Optional. Can be null to clear.
metadata (body)objectNoOptional metadata object stored with the lead event.

Deferred Tracking

Send clickId as an empty string ("") to attribute the lead to the customer's most recent lead click. This fails if the customer has no previous leads.

Retries create lead events

Every accepted POST creates a new lead event, including a retry. This includes caller retries. Repeated requests with the same customerExternalId reuse the active customer but create separate leads. No **Idempotency-Key** header is accepted, promised, or required. Retry only when another lead conversion is intended.

Capture clickId in the browser

If you don't already have a clickId, use the Browser attribution script to persist `hoko_id` and pass it to this endpoint. See [Browser attribution script](https://docs.hoko.to/track/analytics-js).