Skip to main content

​
Endpoint

​
method
string
POST
​
url
string
https://api.dub.co/track/lead

​
Authentication

This endpoint requires authentication using a Bearer token. 
Authorization: Bearer DUB_API_KEY

​
Request Body

​
clickId
string
required
The unique ID of the click that the lead conversion event is attributed to. You can read this value from dub_id cookie.For deferred lead tracking: If an empty string is provided, Dub will try to find an existing customer with the provided customerExternalId and use the clickId from the customer if found.
​
eventName
string
required
The name of the lead event to track. Can also be used as a unique identifier to associate a given lead event for a customer for a subsequent sale event (via the leadEventName prop in /track/sale).Maximum length: 255 charactersExample: Sign up
​
customerExternalId
string
required
The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer.Maximum length: 100 characters
​
customerName
string
The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”).Maximum length: 100 characters
​
customerEmail
string
The email address of the customer.Maximum length: 100 characters
​
customerAvatar
string
The avatar URL of the customer.
​
mode
enum
default:"async"
The mode to use for tracking the lead event.
  • async - Will not block the request
  • wait - Will block the request until the lead event is fully recorded in Dub
  • deferred - Will defer the lead event creation to a subsequent request
​
eventQuantity
number
The numerical value associated with this lead event (e.g., number of provisioned seats in a free trial). If defined as N, the lead event will be tracked N times.
​
metadata
object
Additional metadata to be stored with the lead event. Max 10,000 characters when stringified.

​
Response

​
click
object
​
id
string
The unique ID of the click event
​
link
object | null
The link information associated with the lead event
​
id
string
The unique ID of the link
​
domain
string
The domain of the short link
​
key
string
The key (slug) of the short link
​
shortLink
string
The full short link URL
​
url
string
The destination URL
​
partnerId
string | null
The partner ID if applicable
​
programId
string | null
The program ID if applicable
​
tenantId
string | null
The tenant ID if applicable
​
externalId
string | null
The external ID if applicable
​
customer
object
​
name
string | null
The name of the customer
​
email
string | null
The email of the customer
​
avatar
string | null
The avatar URL of the customer
​
externalId
string | null
The external ID of the customer

​
Examples

curl -X POST https://api.dub.co/track/lead \
  -H "Authorization: Bearer DUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clickId": "cm2xyz123abc",
    "eventName": "Sign up",
    "customerExternalId": "user_123456",
    "customerName": "John Doe",
    "customerEmail": "[email protected]"
  }'

​
Response Example

{
  "click": {
    "id": "cm2xyz123abc"
  },
  "link": {
    "id": "clx1y2z3a4b5c6d7e8f9",
    "domain": "dub.sh",
    "key": "example",
    "shortLink": "https://dub.sh/example",
    "url": "https://example.com",
    "partnerId": null,
    "programId": null,
    "tenantId": null,
    "externalId": null
  },
  "customer": {
    "name": "John Doe",
    "email": "[email protected]",
    "avatar": null,
    "externalId": "user_123456"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us