Skip to main content
GET
/
partners
Python
from dub import Dub
from dub.models import operations


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

    res = d_client.partners.list(request={
        "status": operations.ListPartnersQueryParamStatus.APPROVED,
        "country": "US",
        "email": "[email protected]",
        "tenant_id": "1K0NM7HCN944PEMZ3CQPH43H8",
        "search": "john",
        "page_size": 50,
    })

    # Handle response
    print(res)
[
  {
    "id": "<string>",
    "name": "<string>",
    "companyName": "<string>",
    "email": "<string>",
    "image": "<string>",
    "country": "<string>",
    "paypalEmail": "<string>",
    "stripeConnectId": "<string>",
    "payoutsEnabledAt": "<string>",
    "trustedAt": "<string>",
    "programId": "<string>",
    "partnerId": "<string>",
    "tenantId": "<string>",
    "createdAt": "<string>",
    "status": "pending",
    "links": [
      {
        "id": "<string>",
        "domain": "<string>",
        "key": "<string>",
        "shortLink": "<string>",
        "url": "<string>",
        "clicks": 0,
        "leads": 0,
        "conversions": 0,
        "sales": 0,
        "saleAmount": 0
      }
    ],
    "totalCommissions": 0,
    "totalClicks": 0,
    "totalLeads": 0,
    "totalConversions": 0,
    "totalSales": 0,
    "totalSaleAmount": 0,
    "netRevenue": 0,
    "description": "<string>",
    "groupId": "<string>",
    "clickRewardId": "<string>",
    "leadRewardId": "<string>",
    "saleRewardId": "<string>",
    "discountId": "<string>",
    "applicationId": "<string>",
    "bannedAt": "<string>",
    "bannedReason": "tos_violation",
    "earningsPerClick": 123,
    "averageLifetimeValue": 123,
    "clickToLeadRate": 123,
    "clickToConversionRate": 123,
    "leadToConversionRate": 123,
    "returnOnAdSpend": 123,
    "website": "<string>",
    "youtube": "<string>",
    "twitter": "<string>",
    "linkedin": "<string>",
    "instagram": "<string>",
    "tiktok": "<string>"
  }
]
Partners endpoints require an Advanced plan subscription or higher.

Authorizations

​
Authorization
string
header
required

Default authentication mechanism

Query Parameters

​
status
enum<string>

A filter on the list based on the partner's status field.

Available options:
pending,
approved,
rejected,
invited,
declined,
deactivated,
banned,
archived
Example:

"approved"

​
country
string

A filter on the list based on the partner's country field.

Example:

"US"

​
sortBy
enum<string>
default:totalSaleAmount

The field to sort the partners by. The default is totalSaleAmount.

Available options:
createdAt,
totalClicks,
totalLeads,
totalConversions,
totalSaleAmount,
totalCommissions,
netRevenue,
earningsPerClick,
averageLifetimeValue,
clickToLeadRate,
clickToConversionRate,
leadToConversionRate,
returnOnAdSpend
Example:

"totalSaleAmount"

​
sortOrder
enum<string>
default:desc

The sort order. The default is desc.

Available options:
asc,
desc
Example:

"desc"

​
email
string

Filter the partner list based on the partner's email. The value must be a string. Takes precedence over search.

Example:

"[email protected]"

​
tenantId
string

Filter the partner list based on the partner's tenantId. The value must be a string. Takes precedence over email and search.

Example:

"1K0NM7HCN944PEMZ3CQPH43H8"

​
search
string

A search query to filter partners by ID, name, email, or link.

Example:

"john"

​
page
number
default:1

The page number for pagination.

Required range: x > 0
Example:

1

​
pageSize
number
default:100

The number of items per page.

Required range: 0 < x <= 100
Example:

50

Response

The list of partners.

​
id
string
required

The partner's unique ID on Dub.

​
name
string
required

The partner's full legal name.

Maximum string length: 190
​
companyName
string | null
required

If the partner profile type is a company, this is the partner's legal company name.

Maximum string length: 190
​
email
string | null
required

The partner's email address. Should be a unique value across Dub.

Maximum string length: 190
​
image
string | null
required

The partner's avatar image.

​
country
string | null
required

The partner's country (required for tax purposes).

​
paypalEmail
string | null
required

The partner's PayPal email (for receiving payouts via PayPal).

​
stripeConnectId
string | null
required

The partner's Stripe Connect ID (for receiving payouts via Stripe).

​
payoutsEnabledAt
string | null
required

The date when the partner enabled payouts.

​
trustedAt
string | null
required

The date when the partner received the trusted badge in the partner network.

​
programId
string
required

The program's unique ID on Dub.

​
partnerId
string
required

The partner's unique ID on Dub.

​
tenantId
string | null
required

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.

​
createdAt
string
required
​
status
enum<string>
required

The status of the partner's enrollment in the program.

Available options:
pending,
approved,
rejected,
invited,
declined,
deactivated,
banned,
archived
​
links
Link · object[] | null
required

The partner's referral links in this program.

​
totalCommissions
number
default:0
required

The total commissions paid to the partner for their referrals

​
totalClicks
number
default:0
required

The total number of clicks on the partner's links

​
totalLeads
number
default:0
required

The total number of leads generated by the partner's links

​
totalConversions
number
default:0
required

The total number of leads that converted to paying customers

​
totalSales
number
default:0
required

The total number of sales generated by the partner's links (includes recurring sales)

​
totalSaleAmount
number
default:0
required

Total revenue generated by the partner's links

​
netRevenue
number
default:0
required

Net revenue after commissions (Total Revenue - Total Commissions)

​
description
string | null

A brief description of the partner and their background.

Maximum string length: 5000
​
groupId
string | null

The partner's group ID on Dub.

​
clickRewardId
string | null
​
leadRewardId
string | null
​
saleRewardId
string | null
​
discountId
string | null
​
applicationId
string | null

If the partner submitted an application to join the program, this is the ID of the application.

​
bannedAt
string | null

If the partner was banned from the program, this is the date of the ban.

​
bannedReason
enum<string> | null

If the partner was banned from the program, this is the reason for the ban.

Available options:
tos_violation,
inappropriate_content,
fake_traffic,
fraud,
spam,
brand_abuse,
​
earningsPerClick
number | null

Earnings Per Click (EPC) (Total Revenue ÷ Total Clicks)

​
averageLifetimeValue
number | null

Average lifetime value for each paying customer (Total Revenue ÷ Total Conversions)

​
clickToLeadRate
number | null

Percentage of clicks that become leads (Total Leads ÷ Total Clicks)

​
clickToConversionRate
number | null

Percentage of clicks that convert to paying customers (Total Conversions ÷ Total Clicks)

​
leadToConversionRate
number | null

Percentage of leads that convert to paying customers (Total Conversions ÷ Total Leads)

​
returnOnAdSpend
number | null

Return On Ad Spend (ROAS) (Total Revenue ÷ Total Commissions)

​
website
string | null

The partner's website URL (including the https protocol).

​
youtube
string | null

The partner's YouTube channel username (e.g. johndoe).

​
twitter
string | null

The partner's Twitter username (e.g. johndoe).

​
linkedin
string | null

The partner's LinkedIn username (e.g. johndoe).

​
instagram
string | null

The partner's Instagram username (e.g. johndoe).

​
tiktok
string | null

The partner's TikTok username (e.g. johndoe).