Create or update a partner

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.

1 min read

post/partners

Request example

from dub import Dub


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

    res = d_client.partners.create(request={
        "email": "Summer50@yahoo.com",
        "link_props": {
            "external_id": "123456",
            "tag_ids": [
                "clux0rgak00011...",
            ],
            "test_variants": [
                {
                    "url": "https://example.com/variant-1",
                    "percentage": 50,
                },
                {
                    "url": "https://example.com/variant-2",
                    "percentage": 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>"
}

post/partners

Authorization

Authorizationstringheaderrequired#

Default authentication mechanism

Body

application/json

namestring#

The partner's full name. If undefined, the partner's email will be used in lieu of their name (e.g. john@acme.com)

Length: max 100

emailstringrequired#

The partner's email address. Partners will be able to claim their profile by signing up at partners.dub.co with this email.

Length: max 190Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

usernamestring#

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.

Length: max 100

imagestring#

The partner's avatar image. If not provided, a default avatar will be used.

tenantIdstring#

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.

groupIdstring#

The group ID to add the partner to. If not provided, the partner will be added to the default group.

countrystring#

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.

descriptionstring#

A brief description of the partner and their background. Max 5,000 characters.

Length: max 5000

linkPropsobject#

Additional properties that you can pass to the partner's short link. Will be used to override the default link properties for this partner.

Show child attributes

externalIdstring#

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.

Length: 1–255

tenantIdstring#

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.

Length: max 255

prefixstring#

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

archivedboolean#

Whether the short link is archived. Defaults to false if not provided.

tagIdsstring · string[]#

The unique IDs of the tags assigned to the short link.

Show child attributes

Any of

tagNamesstring · string[]#

The unique name of the tags assigned to the short link (case insensitive).

Show child attributes

Any of

commentsstring#

The comments for the short link.

expiresAtstring#

The date and time when the short link will expire at.

expiredUrlstring#

The URL to redirect to when the short link has expired.

Length: max 32000

passwordstring#

The password required to access the destination URL of the short link.

proxyboolean#

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

titlestring#

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

descriptionstring#

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

imagestring#

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

videostring#

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewriteboolean#

Whether the short link uses link cloaking. Defaults to false if not provided.

iosstring#

The iOS destination URL for the short link for iOS device targeting.

Length: max 32000

androidstring#

The Android destination URL for the short link for Android device targeting.

Length: max 32000

doIndexboolean#

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

testVariantsobject[]#

An array of A/B test URLs and the percentage of traffic to send to each URL.

Items: 2–4

Show child attributes

urlstringrequired#

percentagenumberrequired#

Range: 10–90

testStartedAtstring#

The date and time when the tests started.

testCompletedAtstring#

The date and time when the tests were or will be completed.

Responses

application/json

The created or updated partner

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.

React Native List partners