Track API

Purpose and Scope

The Track API is the ingestion surface for conversion and deep-link activity that happens after a user interacts with a Dub link. In Dub terminology, tracking is distinct from analytics retrieval: tracking endpoints receive events from your application, while analytics and events endpoints read back the resulting click, lead, and sale records. This page focuses on the public Track API family represented by the OpenAPI path registry, and it also explains how the adjacent Events API gives authenticated workspaces a way to list the event records that tracking produces.

Dub’s product model centers on short links, conversion tracking, and affiliate programs. The Track API is where those ideas become operational for application developers. A short-link click can later be associated with a lead when a user signs up, with a sale when revenue is generated, or with an app open when a Dub-powered deep link launches an iOS or Android app. Those events let Dub connect link attribution to downstream business outcomes rather than stopping at click counts.

The repository source for this page is intentionally concentrated in OpenAPI assembly modules. apps/web/lib/openapi/track/index.ts defines the path family for write-side tracking routes. apps/web/lib/openapi/events/index.ts defines a read-side list operation that returns event records as a discriminated union of click, lead, and sale response schemas. Together, these files show that tracking and event retrieval are related but separate API families, with different route prefixes, tags, and authentication expectations. Sources: apps/web/lib/openapi/track/index.ts, apps/web/lib/openapi/events/index.ts

Relevant Source Files

• apps/web/lib/openapi/track/index.ts - Registers the Track OpenAPI paths for POST /track/lead, POST /track/sale, and POST /track/open, wiring each route to its imported operation object.
• apps/web/lib/openapi/events/index.ts - Defines the GET /events OpenAPI operation for listing click, lead, and sale events from an authenticated workspace, including its query schema, response union, tag, and token security declaration.

API Components

The Track path registry exports trackPaths as a ZodOpenApiPathsObject. That object contains three route keys: /track/lead, /track/sale, and /track/open. Each route exposes a post operation, delegated to trackLead, trackSale, and trackOpen respectively. This structure is the source-level contract that the generated OpenAPI document uses to group these endpoints under the Track API family. It also makes the route list explicit for SDK generation, generated docs, and any internal tooling that consumes the OpenAPI path object. Sources: apps/web/lib/openapi/track/index.ts

Lead tracking represents a conversion milestone such as a signup, form submission, or other named event that should be attributed to a short-link click. The official API docs describe POST /track/lead as “Track a lead for a short link” and identify deduplication as a core behavior. Deduplication is based on the combination of customerExternalId and eventName, so repeated lead submissions for the same customer and event name are not counted multiple times. That behavior is important for integrations that may retry requests or emit lifecycle events from more than one service.

Sale tracking represents revenue attributed to a customer and, by extension, to the click or customer record that established attribution. The official API docs describe POST /track/sale as “Track a sale for a short link.” Its request body includes business-facing fields such as customerExternalId, amount, and currency. Amounts are represented in the smallest currency unit for two-decimal currencies, while zero-decimal currencies use the full integer value. Currency values are ISO 4217 codes, and sales are documented as being converted and stored as USD at current exchange rates.

Open tracking represents a deep-link app open. The official API docs describe POST /track/open as the endpoint used when a user opens an app through a Dub-powered deep link on iOS or Android. It accepts a deepLink value when the app has it available, and a dubDomain value for probabilistic tracking workflows. The docs also note that deferred deep linking requires a Pro plan or higher, while conversion tracking for lead and sale events requires a Business plan or higher.

Endpoint Reference

Endpoint	Method	Operation	Primary use	Notes
/track/lead	POST	trackLead	Record a lead conversion for a short link	Lead events are deduplicated by customerExternalId and eventName according to the official docs.
/track/sale	POST	trackSale	Record attributed revenue for a customer	Important request fields include customerExternalId, amount, and currency.
/track/open	POST	trackOpen	Record that a Dub-powered deep link opened an app	Supports direct deepLink attribution and dubDomain-based probabilistic tracking.
/events	GET	listEvents	Retrieve recorded event data for a workspace	Authenticated read-side endpoint tagged as Events, not Track.

The Track endpoints are write-side ingestion endpoints. Client applications, backend services, checkout handlers, and mobile apps call them when a conversion or app-open moment happens. The Events endpoint is a read-side retrieval endpoint. It is exported separately as eventsPath, defines operationId: "listEvents", and uses the Speakeasy name override list. Its response schema is an array whose items are discriminated by the event property across click, lead, and sale response schemas. This is a useful distinction when designing integrations: send events through Track, then inspect normalized event records through Events. Sources: apps/web/lib/openapi/events/index.ts

The GET /events operation also shows the authenticated workspace boundary for event retrieval. It accepts eventsQuerySchema as query parameters, returns a paginated-style list described as “A list of events,” includes shared OpenAPI error responses, and declares security: [{ token: [] }]. In practical terms, event listing is scoped to the authenticated workspace and should be treated as an API-key-protected reporting operation. That contrasts with the official Track endpoint snippets, which are documented with an empty OpenAPI security array so mobile and server-side tracking flows can be modeled as event ingestion operations.

Execution Flow

A typical lead attribution flow starts when a user clicks a Dub short link and Dub records the click. Your application later reads the click identifier, commonly from the dub_id cookie described in the official lead tracking docs, and sends it with a lead event when the user converts. The event should include a stable external customer identifier from your own system and a meaningful event name. Because lead deduplication uses the customer identifier plus event name, applications should choose event names intentionally, such as Sign Up, Demo Requested, or Trial Started, rather than generating unstable names per request.

A sale attribution flow usually happens after a checkout, invoice payment, or subscription event. Your backend should send the customer identifier that Dub can associate with prior attribution, the sale amount, and the currency. For two-decimal currencies, pass the amount in cents; for zero-decimal currencies, pass the integer monetary value. This model keeps sale tracking compatible with payment processors that emit webhook events, because the application can translate a provider-specific payment event into Dub’s stable trackSale operation and let Dub attach it to the customer’s attribution history.

A deep-link open flow is mobile-oriented. When an app is opened through a Dub-powered deep link, the app can send the deep link string to POST /track/open. If the deep link is not available, the official docs describe a probabilistic fallback that uses the Dub deep-link custom domain, such as acme.link, to look for an associated click from the user’s IP address. This makes the open endpoint useful both for direct deep-link handoff and deferred deep-linking scenarios where attribution has to bridge install and first open.

Relationship to Events and Analytics

The Events API is not a replacement for Track; it is the retrieval side of the same attribution story. The listEvents operation imports clickEventResponseSchema, leadEventResponseSchema, and saleEventResponseSchema, then returns a discriminated union over those shapes. That tells API consumers to expect a mixed event feed in which each item identifies its event type and carries the corresponding response fields. It also means click events can appear alongside conversion events, making the endpoint useful for auditing attribution sequences or building workspace-level event tables. Sources: apps/web/lib/openapi/events/index.ts

Because listEvents uses eventsQuerySchema, consumers should expect query-level filtering, pagination, or selection behavior to be defined by the analytics schema module rather than directly in the OpenAPI event module. The visible source does not inline those query fields; it composes them from the shared analytics schema. That composition is a recurring Dub OpenAPI pattern: small path modules define route identity, operation metadata, security, and response composition, while shared Zod schemas define reusable request and response structures across the API surface.

Implementation Details for API Consumers

When building against the Track API, use stable identifiers and server-side event sources whenever possible. customerExternalId should be the durable ID from your own database, not an email address or a temporary session value. Event names should be consistent across retries and deployments so that deduplication behaves predictably. For sales, amounts should be computed before calling Dub, and currency should be sent explicitly unless the default USD behavior is what you want. These conventions reduce duplicate events and make later reporting easier to interpret.

For mobile deep linking, decide whether your app can reliably capture and forward the full deep-link URL. If it can, send deepLink directly to the open tracking endpoint. If not, configure and send the Dub deep-link domain so Dub can attempt probabilistic matching. This decision affects attribution accuracy and should be tested on both iOS and Android, especially around install, first launch, and app resume paths. The open event endpoint exists specifically for that mobile app-open moment, not for general click tracking.

For reporting workflows, call GET /events with an API token and consume the result as a mixed event stream. Because the OpenAPI operation declares the response as a discriminated union, client code should branch on the event discriminator before reading type-specific fields. This is safer than assuming every item is a sale or lead. It also keeps reporting code aligned with Dub’s data model, where clicks, leads, and sales are separate event kinds but can be viewed together for a workspace.

Next Steps

If you are implementing conversion tracking, start by deciding which business moments map to leads and which map to sales. Then wire server-side calls to POST /track/lead and POST /track/sale, using stable customer identifiers and predictable event names. If you are implementing mobile attribution, add POST /track/open to the app-open path and verify whether direct deep-link or domain-based probabilistic tracking is appropriate. After events are being sent, use the authenticated Events API to inspect the resulting click, lead, and sale stream.

Related pages: Conversion Tracking Events, Track Leads, Sales, and Opens, Analytics API, OpenAPI Specs