List all partners

List all partners for a partner program.

GET /partners

PHP

PHP

declare(strict_types=1);

require 'vendor/autoload.php';

use Dub;
use Dub\Models\Operations;

$sdk = Dub\Dub::builder()
    ->setSecurity(
        'DUB_API_KEY'
    )
    ->build();

$request = new Operations\ListPartnersRequest(
    groupId: 'grp_123',
    status: Operations\ListPartnersQueryParamStatus::Approved,
    country: 'US',
    email: '[e-mail]',
    tenantId: '1K0NM7HCN944PEMZ3CQPH43H8',
    search: 'john',
    page: 1,
    pageSize: 50,
);

$response = $sdk->partners->list(
    request: $request
);

if ($response->responseBodies !== null) {
    // handle response
}

200

[
  {
    "id": "<string>",
    "name": "<string>",
    "username": "<string>",
    "email": "<string>",
    "image": "<string>",
    "country": "<string>",
    "companyName": "<string>",
    "paypalEmail": "<string>",
    "stripeConnectId": "<string>",
    "payoutsEnabledAt": "<string>",
    "identityVerifiedAt": "<string>",
    "programId": "<string>",
    "partnerId": "<string>",
    "tenantId": "<string>",
    "createdAt": "<string>",
    "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>",
    "referralRewardId": "<string>",
    "discountId": "<string>",
    "applicationId": "<string>",
    "bannedAt": "<string>",
    "referralFormData": {
      "fields": [
        {
          "key": "<string>",
          "label": "<string>",
          "required": true,
          "locked": true,
          "position": 4503599627370495,
          "constraints": {
            "maxLength": 123,
            "pattern": "<string>"
          }
        }
      ]
    },
    "application": {
      "rejectionNote": "<string>",
      "reviewedAt": "<string>"
    },
    "tags": [
      {
        "id": "<string>",
        "name": "<string>"
      }
    ],
    "earningsPerClick": 123,
    "averageLifetimeValue": 123,
    "clickToLeadRate": 123,
    "clickToConversionRate": 123,
    "leadToConversionRate": 123,
    "returnOnAdSpend": 123,
    "website": "<string>",
    "youtube": "<string>",
    "twitter": "<string>",
    "linkedin": "<string>",
    "instagram": "<string>",
    "tiktok": "<string>",
    "trustedAt": "<string>"
  }
]

Partners endpoints require an Advanced plan subscription or higher.

Authorizations

Authorization · string · header · required

Default authentication mechanism

Query Parameters

groupId · string

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

Example:

"grp_123"

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:

"[e-mail]"

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

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

200

application/json

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

username · string | null · required

The partner's unique username on Dub.

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).

companyName · string | null · required

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

Maximum string length: 190

networkStatus · enum<string> · required

The partner's network status on Dub.

Available options: draft, submitted, approved, rejected, trusted

defaultPayoutMethod · enum<string> | null · 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

Available options: connect, stablecoin, paypal

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.

identityVerifiedAt · string | null · required

The date when the partner's identity was verified.

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 · object[] | null · required

The partner's referral links in this program.

Show child attributes

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

referralRewardId · 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

referralFormData · object

Show child attributes

application · object

Linked program application, including review outcome when applicable.

Show child attributes

tags · object[]

The tags associated with the partner.

Show child attributes

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).

trustedAt · string | null · deprecated

DEPRECATED: Use networkStatus instead.