OpenAPI Specification
openapi: 3.0.3
info:
title: Dub Analytics Track API
description: Dub is the modern link attribution platform for short links, conversion tracking, and affiliate programs.
version: 0.0.1
contact:
name: Dub Support
email: support@dub.co
url: https://dub.co/support
license:
name: AGPL-3.0 license
url: https://github.com/dubinc/dub/blob/main/LICENSE.md
servers:
- url: https://api.dub.co
description: Production API
tags:
- name: Track
paths:
/track/lead:
post:
operationId: trackLead
x-speakeasy-name-override: lead
summary: Track a lead
description: Track a lead for a short link.
tags:
- Track
security:
- token: []
requestBody:
content:
application/json:
schema:
type: object
properties:
clickId:
type: string
description: '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:
type: string
minLength: 1
maxLength: 255
description: 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`).
example: Sign up
customerExternalId:
type: string
minLength: 1
maxLength: 100
description: The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer.
customerName:
default: null
description: The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”).
nullable: true
type: string
maxLength: 100
customerEmail:
default: null
description: The email address of the customer.
nullable: true
type: string
maxLength: 100
format: email
pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
customerAvatar:
default: null
description: The avatar URL of the customer.
nullable: true
type: string
mode:
default: async
description: 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.
type: string
enum:
- async
- wait
- deferred
eventQuantity:
description: 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.
nullable: true
type: number
metadata:
default: null
description: Additional metadata to be stored with the lead event. Max 10,000 characters.
nullable: true
type: object
additionalProperties: {}
required:
- clickId
- eventName
- customerExternalId
responses:
'200':
description: A lead was tracked.
content:
application/json:
schema:
type: object
properties:
click:
type: object
properties:
id:
type: string
required:
- id
additionalProperties: false
link:
nullable: true
type: object
properties:
id:
type: string
description: The unique ID of the short link.
domain:
type: string
description: 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).
key:
type: string
description: The short link slug. If not provided, a random 7-character slug will be generated.
shortLink:
type: string
format: uri
description: The full URL of the short link, including the https protocol (e.g. `https://dub.sh/try`).
url:
type: string
format: uri
description: The destination URL of the short link.
partnerId:
nullable: true
description: The ID of the partner the short link is associated with.
type: string
programId:
nullable: true
description: The ID of the program the short link is associated with.
type: string
tenantId:
nullable: true
description: 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.
type: string
externalId:
nullable: true
description: 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.
type: string
required:
- id
- domain
- key
- shortLink
- url
- partnerId
- programId
- tenantId
- externalId
additionalProperties: false
customer:
type: object
properties:
name:
nullable: true
type: string
email:
nullable: true
type: string
avatar:
nullable: true
type: string
externalId:
nullable: true
type: string
required:
- name
- email
- avatar
- externalId
additionalProperties: false
required:
- click
- link
- customer
additionalProperties: false
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'410':
$ref: '#/components/responses/410'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
/track/sale:
post:
operationId: trackSale
x-speakeasy-name-override: sale
summary: Track a sale
description: Track a sale for a short link.
tags:
- Track
security:
- token: []
requestBody:
content:
application/json:
schema:
type: object
properties:
customerExternalId:
type: string
minLength: 1
maxLength: 100
description: The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer.
amount:
type: integer
minimum: 0
maximum: 9007199254740991
description: 'The amount of the sale in cents (for all two-decimal currencies). If the sale is in a zero-decimal currency, pass the full integer value (e.g. `1580` JPY). Learn more: https://d.to/currency'
currency:
description: 'The currency of the sale. Accepts ISO 4217 currency codes. Sales will be automatically converted and stored as USD at the latest exchange rates. Learn more: https://d.to/currency'
default: usd
type: string
eventName:
default: Purchase
description: 'The name of the sale event. Recommended format: `Invoice paid` or `Subscription created`.'
example: Invoice paid
type: string
maxLength: 255
paymentProcessor:
default: custom
description: The payment processor via which the sale was made.
type: string
enum:
- stripe
- shopify
- polar
- paddle
- apple
- revenuecat
- dub
- custom
invoiceId:
default: null
description: The invoice ID of the sale. Can be used as a idempotency key – only one sale event can be recorded for a given invoice ID.
nullable: true
type: string
metadata:
default: null
description: Additional metadata to be stored with the sale event. Max 10,000 characters when stringified.
nullable: true
type: object
additionalProperties: {}
leadEventName:
default: null
description: The name of the lead event that occurred before the sale (case-sensitive). This is used to associate the sale event with a particular lead event (instead of the latest lead event for a link-customer combination, which is the default behavior). For direct sale tracking, this field can also be used to specify the lead event name.
example: Cloned template 1481267
nullable: true
type: string
clickId:
description: '[For direct sale tracking]: The unique ID of the click that the sale conversion event is attributed to. You can read this value from `dub_id` cookie.'
nullable: true
type: string
customerName:
default: null
description: '[For direct sale tracking]: The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”).'
nullable: true
type: string
maxLength: 100
customerEmail:
default: null
description: '[For direct sale tracking]: The email address of the customer.'
nullable: true
type: string
maxLength: 100
format: email
pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
customerAvatar:
default: null
description: '[For direct sale tracking]: The avatar URL of the customer.'
nullable: true
type: string
required:
- customerExternalId
- amount
responses:
'200':
description: A sale was tracked.
content:
application/json:
schema:
type: object
properties:
eventName:
type: string
customer:
nullable: true
type: object
properties:
id:
type: string
name:
nullable: true
type: string
email:
nullable: true
type: string
avatar:
nullable: true
type: string
externalId:
nullable: true
type: string
required:
- id
- name
- email
- avatar
- externalId
additionalProperties: false
sale:
nullable: true
type: object
properties:
amount:
type: number
currency:
type: string
paymentProcessor:
type: string
invoiceId:
nullable: true
type: string
metadata:
nullable: true
type: object
additionalProperties: {}
required:
- amount
- currency
- paymentProcessor
- invoiceId
- metadata
additionalProperties: false
required:
- eventName
- customer
- sale
additionalProperties: false
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'410':
$ref: '#/components/responses/410'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
/track/open:
post:
operationId: trackOpen
x-speakeasy-ignore: true
summary: Track a deep link open event
description: This endpoint is used to track when a user opens your app via a Dub-powered deep link (for both iOS and Android).
tags:
- Track
requestBody:
content:
application/json:
schema:
type: object
properties:
deepLink:
description: 'The deep link that brought the user to the app. If left blank, Dub will fallback to probabilistic tracking by using the `dubDomain` parameter to check if there is an associated click event for the user''s IP address. Learn more: https://d.to/ddl'
type: string
maxLength: 32000
dubDomain:
description: 'Your deep link custom domain on Dub (e.g. `acme.link`). This is used in probabilistic tracking to check if there is an associated click event for the user''s IP address. Learn more: https://d.to/ddl'
type: string
responses:
'200':
description: The response from the tracked open event.
content:
application/json:
schema:
type: object
properties:
clickId:
nullable: true
description: 'The click ID of the associated open event (or the prior click that led the user to the app store for probabilistic tracking). Learn more: https://d.to/ddl'
type: string
link:
nullable: true
description: 'The deep link that brought the user to the app. This will be `null` if the open event was not associated with a link (e.g. a direct download from the app store). Learn more: https://d.to/ddl'
type: object
properties:
id:
type: string
description: The ID of the deep link.
example: link_xxx
domain:
type: string
description: The domain of the deep link.
example: acme.link
key:
type: string
description: The key of the deep link.
example: fb-promo
url:
type: string
description: The URL of the deep link.
example: https://acme.com/product/123
required:
- id
- domain
- key
- url
additionalProperties: false
required:
- clickId
- link
additionalProperties: false
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'410':
$ref: '#/components/responses/410'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
components:
responses:
'500':
description: The server has encountered a situation it does not know how to handle.
content:
application/json:
schema:
x-speakeasy-name-override: InternalServerError
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- internal_server_error
description: A short code indicating the error code returned.
example: internal_server_error
message:
x-speakeasy-error-message: true
type: string
description: A human readable explanation of what went wrong.
example: The requested resource was not found.
doc_url:
type: string
description: A link to our documentation with more details about this error code
example: https://dub.co/docs/api-reference/errors#internal-server_error
required:
- code
- message
required:
- error
'429':
description: The user has sent too many requests in a given amount of time ("rate limiting")
content:
application/json:
schema:
x-speakeasy-name-override: RateLimitExceeded
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- rate_limit_exceeded
description: A short code indicating the error code returned.
example: rate_limit_exceeded
message:
x-speakeasy-error-message: true
type: string
description: A human readable explanation of what went wrong.
example: The requested resource was not found.
doc_url:
type: string
description: A link to our documentation with more details about this error code
example: https://dub.co/docs/api-reference/errors#rate-limit_exceeded
required:
- code
- message
required:
- error
'422':
description: The request was well-formed but was unable to be followed due to semantic errors.
content:
application/json:
schema:
x-speakeasy-name-override: UnprocessableEntity
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unprocessable_entity
description: A short code indicating the error code returned.
example: unprocessable_entity
message:
x-speakeasy-error-message: true
type: string
description: A human readable explanation of what went wrong.
example: The requested resource was not found.
doc_url:
type: string
description: A link to our documentation with more details about this error code
example: https://dub.co/docs/api-reference/errors#unprocessable-entity
required:
- code
- message
required:
- error
'403':
description: The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
content:
application/json:
schema:
x-speakeasy-name-override: Forbidden
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- forbidden
description: A short code indicating the error code returned.
example: forbidden
message:
x-speakeasy-error-message: true
type: string
description: A human readable explanation of what went wrong.
example: The requested resource was not found.
doc_url:
type: string
description: A link to our documentation with more details about this error code
example: https://dub.co/docs/api-reference/errors#forbidden
required:
- code
- message
required:
- error
'404':
description: The server cannot find the requested resource.
content:
application/json:
schema:
x-speakeasy-name-override: NotFound
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- not_found
description: A short code indicating the error code returned.
example: not_found
message:
x-speakeasy-error-message: true
type: string
description: A human readable explanation of what went wrong.
example: The requested resource was not found.
doc_url:
type: string
description: A link to our documentation with more details about this error code
example: https://dub.co/docs/api-reference/errors#not-found
required:
- code
- message
required:
- error
'401':
description: Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
content:
application/json:
schema:
x-speakeasy-name-override: Unauthorized
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
description: A short code indicating the error code returned.
example: unauthorized
message:
x-speakeasy-error-message: true
type: string
description: A human readable explanation of what went wrong.
example: The requested resource was not found.
doc_url:
type: string
description: A link to our documentation with more details about this error code
example: https://dub.co/docs/api-reference/errors#unauthorized
required:
- code
- message
required:
- error
'400':
description: The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
content:
application/json:
schema:
x-speakeasy-name-override: BadRequest
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- bad_request
description: A short code indicating the error code returned.
example: bad_request
message:
x-speakeasy-error-message: true
type: string
description: A human readable explanation of what went wrong.
example: The requested resource was not found.
doc_url:
type: string
description: A link to our documentation with more details about this error code
example: https://dub.co/docs/api-reference/errors#bad-request
required:
- code
- message
required:
- error
'409':
description: This response is sent when a request conflicts with the current state of the server.
content:
application/json:
schema:
x-speakeasy-name-override: Conflict
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- conflict
description: A short code indicating the error code returned.
example: conflict
message:
x-speakeasy-error-message: true
type: string
description: A human readable explanation of what went wrong.
example: The requested resource was not found.
doc_url:
type: string
description: A link to our documentation with more details about this error code
example: https://dub.co/docs/api-reference/errors#conflict
required:
- code
- message
required:
- error
'410':
description: This response is sent when the requested content has been permanently deleted from server, with no forwarding address.
content:
application/json:
schema:
x-speakeasy-name-override: InviteExpired
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- invite_expired
description: A short code indicating the error code returned.
example: invite_expired
message:
x-speakeasy-error-message: true
type: string
description: A human readable explanation of what went wrong.
example: The requested resource was not found.
doc_url:
type: string
description: A link to our documentation with more details about this error code
example: https://dub.co/docs/api-reference/errors#invite-expired
required:
- code
- message
required:
- error
securitySchemes:
token:
type: http
description: Default authentication mechanism
scheme: bearer
x-speakeasy-example: DUB_API_KEY