List all partners

List all partners for a partner program.

1 min read

get/partners

Request example

from dub import Dub
from dub.models import operations


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

    res = d_client.partners.list(request={
        "group_id": "grp_123",
        "status": operations.ListPartnersQueryParamStatus.APPROVED,
        "country": "US",
        "email": "panic@thedis.co",
        "tenant_id": "1K0NM7HCN944PEMZ3CQPH43H8",
        "search": "john",
        "page": 1,
        "page_size": 50,
    })

    # Handle response
    print(res)

Response

[
  {
    "id": "<string>",
    "name": "<string>",
    "username": "<string>",
    "email": "<string>",
    "image": "<string>",
    "description": "<string>",
    "country": "<string>",
    "companyName": "<string>",
    "networkStatus": "draft",
    "defaultPayoutMethod": "connect",
    "paypalEmail": "<string>",
    "stripeConnectId": "<string>",
    "payoutsEnabledAt": "<string>",
    "identityVerifiedAt": "<string>",
    "programId": "<string>",
    "groupId": "<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,
    "clickRewardId": "<string>",
    "leadRewardId": "<string>",
    "saleRewardId": "<string>",
    "referralRewardId": "<string>",
    "discountId": "<string>",
    "applicationId": "<string>",
    "bannedAt": "<string>",
    "bannedReason": "tos_violation",
    "referralFormData": {
      "fields": [
        {
          "key": "<string>",
          "label": "<string>",
          "required": true,
          "locked": true,
          "position": 0,
          "type": "text",
          "constraints": {
            "maxLength": 1,
            "pattern": "<string>"
          }
        }
      ]
    },
    "application": {
      "rejectionReason": "needsMoreDetail",
      "rejectionNote": "<string>",
      "reviewedAt": "<string>"
    },
    "tags": [
      {
        "id": "<string>",
        "name": "<string>"
      }
    ],
    "totalClicks": 0,
    "totalLeads": 0,
    "totalConversions": 0,
    "totalSales": 0,
    "totalSaleAmount": 0,
    "netRevenue": 0,
    "earningsPerClick": 1,
    "averageLifetimeValue": 1,
    "clickToLeadRate": 1,
    "clickToConversionRate": 1,
    "leadToConversionRate": 1,
    "returnOnAdSpend": 1,
    "website": "<string>",
    "youtube": "<string>",
    "twitter": "<string>",
    "linkedin": "<string>",
    "instagram": "<string>",
    "tiktok": "<string>",
    "trustedAt": "<string>"
  }
]

get/partners

Authorization

Authorizationstringheaderrequired#

Default authentication mechanism

Query parameters

groupIdstring#

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

statusenum<string>#

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

Options:pendingapprovedrejectedinviteddeclineddeactivatedbannedarchived

countrystring#

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

sortByenum<string>#

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

Default: "totalSaleAmount"

Options:createdAttotalClickstotalLeadstotalConversionstotalSaleAmounttotalCommissionsnetRevenueearningsPerClickaverageLifetimeValueclickToLeadRateclickToConversionRateleadToConversionRatereturnOnAdSpend

sortOrderenum<string>#

The sort order. The default is desc.

Default: "desc"

Options:ascdesc

emailstring#

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

tenantIdstring#

Filter the partner list based on the partner's tenantId. The value must be a string. Combines with the other filters.

searchstring#

A search query to filter partners by ID, name, email, company name, description, social platforms, or referral links. Partial matches are supported.

pageinteger#

The page number for pagination. The first page is 1.

Range: true < x <= 9007199254740991

pageSizeinteger#

The number of items per page.

Default: 100

Range: true < x <= 100

Responses

application/json

The list of partners.

idstringrequired#

The partner's unique ID on Dub.

namestringrequired#

The partner's full legal name.

Length: max 190

usernamestringrequired#

The partner's unique username on Dub.

emailstringrequired#

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

Length: max 190

imagestringrequired#

The partner's avatar image.

descriptionstring#

A brief description of the partner and their background.

Length: max 5000

countrystringrequired#

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

companyNamestringrequired#

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

Length: max 190

networkStatusenum<string>required#

The partner's network status on Dub.

Options:draftsubmittedapprovedrejectedtrusted

defaultPayoutMethodenum<string>required#

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

Options:connectstablecoinpaypaltremendous

paypalEmailstringrequired#

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

stripeConnectIdstringrequired#

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

payoutsEnabledAtstringrequired#

The date when the partner enabled payouts.

identityVerifiedAtstringrequired#

The date when the partner's identity was verified.

programIdstringrequired#

The program's unique ID on Dub.

groupIdstring#

The partner's group ID on Dub.

partnerIdstringrequired#

The partner's unique ID on Dub.

tenantIdstringrequired#

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.

createdAtstringrequired#

statusenum<string>required#

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

Options:pendingapprovedrejectedinviteddeclineddeactivatedbannedarchived

linksobject[]required#

The partner's referral links in this program.

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.

clicksnumberrequired#

The number of clicks on the short link.

Default: 0

leadsnumberrequired#

The number of leads the short link has generated.

Default: 0

conversionsnumberrequired#

The number of leads that converted to paying customers.

Default: 0

salesnumberrequired#

The total number of sales (includes recurring sales) generated by the short link.

Default: 0

saleAmountnumberrequired#

The total dollar value of sales (in cents) generated by the short link.

Default: 0

totalCommissionsnumberrequired#

The total commissions paid to the partner for their referrals

Default: 0

clickRewardIdstring#

leadRewardIdstring#

saleRewardIdstring#

referralRewardIdstring#

discountIdstring#

applicationIdstring#

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

bannedAtstring#

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

bannedReasonenum<string>#

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

Options:tos_violationinappropriate_contentfake_trafficfraudspambrand_abuse

referralFormDataobject#

Show child attributes

fieldsobject[]required#

Items: min 1

Show child attributes

One of

keystringrequired#

Length: min 1

labelstringrequired#

Length: min 1

requiredbooleanrequired#

lockedbooleanrequired#

positionintegerrequired#

Range: 0–9007199254740991

typeenum<string>required#

Options:text

constraintsobject#

Show child attributes

maxLengthinteger#

Range: 1–9007199254740991

patternstring#

keystringrequired#

Length: min 1

labelstringrequired#

Length: min 1

requiredbooleanrequired#

lockedbooleanrequired#

positionintegerrequired#

Range: 0–9007199254740991

typeenum<string>required#

Options:textarea

constraintsobject#

Show child attributes

maxLengthinteger#

Range: 1–9007199254740991

keystringrequired#

Length: min 1

labelstringrequired#

Length: min 1

requiredbooleanrequired#

lockedbooleanrequired#

positionintegerrequired#

Range: 0–9007199254740991

typeenum<string>required#

Options:select

optionsobject[]required#

Items: min 2

Show child attributes

labelstringrequired#

Length: min 1

valuestringrequired#

Length: min 1

keystringrequired#

Length: min 1

labelstringrequired#

Length: min 1

requiredbooleanrequired#

lockedbooleanrequired#

positionintegerrequired#

Range: 0–9007199254740991

typeenum<string>required#

Options:country

keystringrequired#

Length: min 1

labelstringrequired#

Length: min 1

requiredbooleanrequired#

lockedbooleanrequired#

positionintegerrequired#

Range: 0–9007199254740991

typeenum<string>required#

Options:date

keystringrequired#

Length: min 1

labelstringrequired#

Length: min 1

requiredbooleanrequired#

lockedbooleanrequired#

positionintegerrequired#

Range: 0–9007199254740991

typeenum<string>required#

Options:multiSelect

optionsobject[]required#

Items: min 2

Show child attributes

labelstringrequired#

Length: min 1

valuestringrequired#

Length: min 1

keystringrequired#

Length: min 1

labelstringrequired#

Length: min 1

requiredbooleanrequired#

lockedbooleanrequired#

positionintegerrequired#

Range: 0–9007199254740991

typeenum<string>required#

Options:number

keystringrequired#

Length: min 1

labelstringrequired#

Length: min 1

requiredbooleanrequired#

lockedbooleanrequired#

positionintegerrequired#

Range: 0–9007199254740991

typeenum<string>required#

Options:phone

applicationobject#

Linked program application, including review outcome when applicable.

Show child attributes

rejectionReasonenum<string>required#

Preset reason when the application was rejected.

Options:needsMoreDetaildoesNotMeetRequirementsnotTheRightFitother

rejectionNotestringrequired#

Free-form note when the application was rejected.

reviewedAtstringrequired#

When the application was approved or rejected.

tagsobject[]#

The tags associated with the partner.

Show child attributes

idstringrequired#

namestringrequired#

totalClicksnumberrequired#

The total number of clicks on the partner's links

Default: 0

totalLeadsnumberrequired#

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

Default: 0

totalConversionsnumberrequired#

The total number of leads that converted to paying customers

Default: 0

totalSalesnumberrequired#

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

Default: 0

totalSaleAmountnumberrequired#

Total revenue generated by the partner's links

Default: 0

netRevenuenumberrequired#

Net revenue after commissions (Total Revenue - Total Commissions)

Default: 0

earningsPerClicknumber#

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

averageLifetimeValuenumber#

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

clickToLeadRatenumber#

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

clickToConversionRatenumber#

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

leadToConversionRatenumber#

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

returnOnAdSpendnumber#

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

websitestring#

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

youtubestring#

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

twitterstring#

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

linkedinstring#

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

instagramstring#

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

tiktokstring#

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

trustedAtstringdeprecated#

DEPRECATED: Use networkStatus instead.

Create partner Ban partner