Track a lead event

Track a lead for a short link.

1 min read

post/track/lead

Request example

from dub import Dub


with Dub(
    token="DUB_API_KEY",
) as d_client:

    res = d_client.track.lead(request={
        "click_id": "<id>",
        "event_name": "Sign up",
        "customer_external_id": "<id>",
    })

    # Handle response
    print(res)

Response

{
  "click": {
    "id": "<string>"
  },
  "link": {
    "id": "<string>",
    "domain": "<string>",
    "key": "<string>",
    "shortLink": "<string>",
    "url": "<string>",
    "partnerId": "<string>",
    "programId": "<string>",
    "tenantId": "<string>",
    "externalId": "<string>"
  },
  "customer": {
    "name": "<string>",
    "email": "<string>",
    "avatar": "<string>",
    "externalId": "<string>"
  }
}

post/track/lead

Note

Conversion tracking requires a Business plan subscription or higher.

Deduplication behavior#

Lead events are automatically deduplicated to prevent duplicate tracking:

Events are deduplicated based on the combination of customerExternalId (the user ID of the referred customer within your database) and eventName
If you send multiple lead events with the same customer ID and event name, only the first event will be tracked
Subsequent duplicate events will return null and won't be tracked

Authorization

Authorizationstringheaderrequired#

Default authentication mechanism

Body

application/json

clickIdstringrequired#

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.

eventNamestringrequired#

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).

Length: 1–255

customerExternalIdstringrequired#

The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer.

Length: 1–100

customerNamestring#

The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”).

Default: null

Length: max 100

customerEmailstring#

The email address of the customer.

Default: null

Length: max 100Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

customerAvatarstring#

The avatar URL of the customer.

Default: null

modeenum<string>#

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.

Default: "async"

Options:asyncwaitdeferred

eventQuantityinteger#

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.

Range: true < x <= 100

metadataobject#

Additional metadata to be stored with the lead event. Max 10,000 characters.

Default: null

Show child attributes

{key}any#

Responses

application/json

A lead was tracked.

clickobjectrequired#

Show child attributes

idstringrequired#

linkobjectrequired#

Show child attributes

idstringrequired#

The unique ID of the short link.

domainstringrequired#

The domain of the short link. If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains).

keystringrequired#

The short link slug. If not provided, a random 7-character slug will be generated.

shortLinkstringrequired#

The full URL of the short link, including the https protocol (e.g. https://dub.sh/try).

urlstringrequired#

The destination URL of the short link.

partnerIdstringrequired#

The ID of the partner the short link is associated with.

programIdstringrequired#

The ID of the program the short link is associated with.

tenantIdstringrequired#

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant.

externalIdstringrequired#

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace.

customerobjectrequired#

Show child attributes

namestringrequired#

emailstringrequired#

avatarstringrequired#

externalIdstringrequired#

List events Track a sale event