Dub Partners API
The Partners API from Dub — 6 operation(s) for partners.
OpenAPI Specification
openapi: 3.0.3
info:
title: Dub Analytics Partners 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: Partners
paths:
/partners:
post:
operationId: createPartner
x-speakeasy-name-override: create
summary: Create or update a partner
description: Creates or updates a partner record (upsert behavior). If a partner with the same email already exists, their program enrollment will be updated with the provided tenantId. If no existing partner is found, a new partner will be created using the supplied information.
tags:
- Partners
security:
- token: []
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
description: The partner's full name. If undefined, the partner's email will be used in lieu of their name (e.g. `john@acme.com`)
nullable: true
type: string
maxLength: 100
email:
type: string
maxLength: 190
format: email
pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
description: The partner's email address. Partners will be able to claim their profile by signing up at `partners.dub.co` with this email.
username:
description: The partner's unique username in your system (max 100 characters). This will be used to create a short link for the partner using your program's default domain. If not provided, Dub will try to generate a username from the partner's name or email.
nullable: true
type: string
maxLength: 100
image:
description: The partner's avatar image. If not provided, a default avatar will be used.
nullable: true
type: string
tenantId:
description: The partner's unique ID in your system. Useful for retrieving the partner's links and stats later on. If not provided, the partner will be created as a standalone partner.
type: string
groupId:
description: The group ID to add the partner to. If not provided, the partner will be added to the default group.
type: string
country:
description: The partner's country of residence. Must be passed as a 2-letter ISO 3166-1 country code. See https://d.to/geo for more information.
nullable: true
type: string
description:
description: A brief description of the partner and their background. Max 5,000 characters.
nullable: true
type: string
maxLength: 5000
linkProps:
description: Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.
type: object
properties:
externalId:
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.
example: '123456'
nullable: true
type: string
minLength: 1
maxLength: 255
tenantId:
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.
nullable: true
type: string
maxLength: 255
prefix:
description: Path prefix for each default referral link slug (e.g. `/c/` → `https://{domain}/c/{identity}`). If the group has multiple default links, a short random suffix is appended to the identity segment for uniqueness (e.g. `c/jane-a7f2`).
type: string
archived:
description: Whether the short link is archived. Defaults to `false` if not provided.
type: boolean
tagIds:
description: The unique IDs of the tags assigned to the short link.
example:
- clux0rgak00011...
anyOf:
- type: string
- type: array
items:
type: string
tagNames:
description: The unique name of the tags assigned to the short link (case insensitive).
anyOf:
- type: string
- type: array
items:
type: string
comments:
description: The comments for the short link.
nullable: true
type: string
expiresAt:
description: The date and time when the short link will expire at.
nullable: true
type: string
expiredUrl:
description: The URL to redirect to when the short link has expired.
maxLength: 32000
nullable: true
type: string
password:
description: The password required to access the destination URL of the short link.
nullable: true
type: string
proxy:
description: Whether the short link uses Custom Link Previews feature. Defaults to `false` if not provided.
type: boolean
title:
description: 'The custom link preview title (og:title). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og'
nullable: true
type: string
description:
description: 'The custom link preview description (og:description). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og'
nullable: true
type: string
image:
description: 'The custom link preview image (og:image). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og'
nullable: true
type: string
video:
description: 'The custom link preview video (og:video). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og'
nullable: true
type: string
rewrite:
description: Whether the short link uses link cloaking. Defaults to `false` if not provided.
type: boolean
ios:
description: The iOS destination URL for the short link for iOS device targeting.
nullable: true
type: string
maxLength: 32000
android:
description: The Android destination URL for the short link for Android device targeting.
nullable: true
type: string
maxLength: 32000
doIndex:
description: 'Allow search engines to index your short link. Defaults to `false` if not provided. Learn more: https://d.to/noindex'
type: boolean
testVariants:
nullable: true
minItems: 2
maxItems: 4
type: array
items:
type: object
properties:
url:
type: string
percentage:
type: number
minimum: 10
maximum: 90
required:
- url
- percentage
description: An array of A/B test URLs and the percentage of traffic to send to each URL.
example:
- url: https://example.com/variant-1
percentage: 50
- url: https://example.com/variant-2
percentage: 50
testStartedAt:
description: The date and time when the tests started.
nullable: true
type: string
testCompletedAt:
description: The date and time when the tests were or will be completed.
nullable: true
type: string
required:
- email
responses:
'201':
description: The created or updated partner
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The partner's unique ID on Dub.
name:
type: string
maxLength: 190
description: The partner's full legal name.
username:
nullable: true
description: The partner's unique username on Dub.
type: string
email:
nullable: true
description: The partner's email address. Should be a unique value across Dub.
type: string
maxLength: 190
image:
nullable: true
description: The partner's avatar image.
type: string
description:
description: A brief description of the partner and their background.
nullable: true
type: string
maxLength: 5000
country:
nullable: true
description: The partner's country (required for tax purposes).
type: string
companyName:
nullable: true
description: If the partner profile type is a company, this is the partner's legal company name.
type: string
maxLength: 190
networkStatus:
type: string
enum:
- draft
- submitted
- approved
- rejected
- trusted
description: The partner's network status on Dub.
defaultPayoutMethod:
nullable: true
description: 'The partner''s default payout method. Connect: Bank account payouts via Stripe Connect; Stablecoin: USDC payouts directly to a crypto wallet; PayPal: Payouts via PayPal'
type: string
enum:
- connect
- stablecoin
- paypal
paypalEmail:
nullable: true
description: The partner's PayPal email (for receiving payouts via PayPal).
type: string
stripeConnectId:
nullable: true
description: The partner's Stripe Connect ID (for receiving payouts via Stripe).
type: string
payoutsEnabledAt:
nullable: true
description: The date when the partner enabled payouts.
type: string
identityVerifiedAt:
nullable: true
description: The date when the partner's identity was verified.
type: string
programId:
type: string
description: The program's unique ID on Dub.
groupId:
description: The partner's group ID on Dub.
nullable: true
type: string
partnerId:
type: string
description: The partner's unique ID on Dub.
tenantId:
nullable: true
description: The partner's unique ID within your database. Can be useful for associating the partner with a user in your database and retrieving/update their data in the future.
type: string
createdAt:
type: string
status:
type: string
enum:
- pending
- approved
- rejected
- invited
- declined
- deactivated
- banned
- archived
description: The status of the partner's enrollment in the program.
links:
nullable: true
description: The partner's referral links in this program.
type: array
items:
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.
clicks:
default: 0
description: The number of clicks on the short link.
type: number
leads:
default: 0
description: The number of leads the short link has generated.
type: number
conversions:
default: 0
description: The number of leads that converted to paying customers.
type: number
sales:
default: 0
description: The total number of sales (includes recurring sales) generated by the short link.
type: number
saleAmount:
description: The total dollar value of sales (in cents) generated by the short link.
default: 0
type: number
required:
- id
- domain
- key
- shortLink
- url
- clicks
- leads
- conversions
- sales
- saleAmount
additionalProperties: false
totalCommissions:
description: The total commissions paid to the partner for their referrals
default: 0
type: number
clickRewardId:
nullable: true
type: string
leadRewardId:
nullable: true
type: string
saleRewardId:
nullable: true
type: string
referralRewardId:
nullable: true
type: string
discountId:
nullable: true
type: string
applicationId:
description: If the partner submitted an application to join the program, this is the ID of the application.
nullable: true
type: string
bannedAt:
description: If the partner was banned from the program, this is the date of the ban.
nullable: true
type: string
bannedReason:
description: If the partner was banned from the program, this is the reason for the ban.
nullable: true
type: string
enum:
- tos_violation
- inappropriate_content
- fake_traffic
- fraud
- spam
- brand_abuse
referralFormData:
nullable: true
type: object
properties:
fields:
minItems: 1
type: array
items:
oneOf:
- type: object
properties:
key:
type: string
minLength: 1
label:
type: string
minLength: 1
required:
type: boolean
locked:
type: boolean
position:
type: integer
minimum: 0
maximum: 9007199254740991
type:
type: string
enum:
- text
constraints:
type: object
properties:
maxLength:
type: integer
exclusiveMinimum: true
maximum: 9007199254740991
pattern:
type: string
additionalProperties: false
required:
- key
- label
- required
- locked
- position
- type
additionalProperties: false
- type: object
properties:
key:
type: string
minLength: 1
label:
type: string
minLength: 1
required:
type: boolean
locked:
type: boolean
position:
type: integer
minimum: 0
maximum: 9007199254740991
type:
type: string
enum:
- textarea
constraints:
type: object
properties:
maxLength:
type: integer
exclusiveMinimum: true
maximum: 9007199254740991
additionalProperties: false
required:
- key
- label
- required
- locked
- position
- type
additionalProperties: false
- type: object
properties:
key:
type: string
minLength: 1
label:
type: string
minLength: 1
required:
type: boolean
locked:
type: boolean
position:
type: integer
minimum: 0
maximum: 9007199254740991
type:
type: string
enum:
- select
options:
minItems: 2
type: array
items:
type: object
properties:
label:
type: string
minLength: 1
value:
type: string
minLength: 1
required:
- label
- value
additionalProperties: false
required:
- key
- label
- required
- locked
- position
- type
- options
additionalProperties: false
- type: object
properties:
key:
type: string
minLength: 1
label:
type: string
minLength: 1
required:
type: boolean
locked:
type: boolean
position:
type: integer
minimum: 0
maximum: 9007199254740991
type:
type: string
enum:
- country
required:
- key
- label
- required
- locked
- position
- type
additionalProperties: false
- type: object
properties:
key:
type: string
minLength: 1
label:
type: string
minLength: 1
required:
type: boolean
locked:
type: boolean
position:
type: integer
minimum: 0
maximum: 9007199254740991
type:
type: string
enum:
- date
required:
- key
- label
- required
- locked
- position
- type
additionalProperties: false
- type: object
properties:
key:
type: string
minLength: 1
label:
type: string
minLength: 1
required:
type: boolean
locked:
type: boolean
position:
type: integer
minimum: 0
maximum: 9007199254740991
type:
type: string
enum:
- multiSelect
options:
minItems: 2
type: array
items:
type: object
properties:
label:
type: string
minLength: 1
value:
type: string
minLength: 1
required:
- label
- value
additionalProperties: false
required:
- key
- label
- required
- locked
- position
- type
- options
additionalProperties: false
- type: object
properties:
key:
type: string
minLength: 1
label:
type: string
minLength: 1
required:
type: boolean
locked:
type: boolean
position:
type: integer
minimum: 0
maximum: 9007199254740991
type:
type: string
enum:
- number
required:
- key
- label
- required
- locked
- position
- type
additionalProperties: false
- type: object
properties:
key:
type: string
minLength: 1
label:
type: string
minLength: 1
required:
type: boolean
locked:
type: boolean
position:
type: integer
minimum: 0
maximum: 9007199254740991
type:
type: string
enum:
- phone
required:
- key
- label
- required
- locked
- position
- type
additionalProperties: false
type: object
required:
- fields
additionalProperties: false
application:
description: Linked program application, including review outcome when applicable.
nullable: true
type: object
properties:
rejectionReason:
nullable: true
description: Preset reason when the application was rejected.
type: string
enum:
- needsMoreDetail
- doesNotMeetRequirements
- notTheRightFit
- other
rejectionNote:
nullable: true
description: Free-form note when the application was rejected.
type: string
reviewedAt:
nullable: true
description: When the application was approved or rejected.
type: string
required:
- rejectionReason
- rejectionNote
- reviewedAt
additionalProperties: false
tags:
description: The tags associated with the partner.
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
additionalProperties: false
totalClicks:
default: 0
description: The total number of clicks on the partner's links
type: number
totalLeads:
default: 0
description: The total number of leads generated by the partner'
# --- truncated at 32 KB (123 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dub/refs/heads/main/openapi/dub-partners-api-openapi.yml