Create a referrals embed token

Create a referrals embed token for the given partner/tenant. The endpoint first attempts to locate an existing enrollment using the provided tenantId. If no enrollment is found, it resolves the partner by email and creates a new enrollment as needed. This results in an upsert-style flow that guarantees a valid enrollment and returns a usable embed token.

1 min read

post/tokens/embed/referrals

Request example

from dub import Dub


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

    res = d_client.embed_tokens.referrals(request={
        "partner": {
            "email": "Letha_Wuckert2@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

{
  "publicToken": "<string>",
  "expires": "<string>"
}

post/tokens/embed/referrals

Note

Referrals embed token endpoint require an Advanced plan subscription or higher.

Authorization

Authorizationstringheaderrequired#

Default authentication mechanism

Body

application/json

partnerIdstring#

tenantIdstring#

partnerobject#

Show child attributes

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 public embed token.

publicTokenstringrequired#

expiresstringrequired#