Bulk create links

Bulk create up to 100 links for the authenticated workspace.

1 min read

post/links/bulk

Request example

from dub import Dub


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

    res = d_client.links.create_many(request=[
        {
            "url": "https://google.com",
            "external_id": "123456",
            "tag_ids": [
                "clux0rgak00011...",
            ],
            "test_variants": [
                {
                    "url": "https://example.com/variant-1",
                    "percentage": 50,
                },
                {
                    "url": "https://example.com/variant-2",
                    "percentage": 50,
                },
            ],
        },
        {
            "url": "https://google.com",
            "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>",
    "domain": "<string>",
    "key": "<string>",
    "url": "<string>",
    "trackConversion": false,
    "externalId": "<string>",
    "tenantId": "<string>",
    "programId": "<string>",
    "partnerId": "<string>",
    "archived": false,
    "expiresAt": "<string>",
    "expiredUrl": "<string>",
    "disabledAt": "<string>",
    "password": "<string>",
    "proxy": false,
    "title": "<string>",
    "description": "<string>",
    "image": "<string>",
    "video": "<string>",
    "rewrite": false,
    "doIndex": false,
    "ios": "<string>",
    "android": "<string>",
    "geo": {},
    "publicStats": false,
    "tags": [
      {
        "id": "<string>",
        "name": "<string>",
        "color": "red"
      }
    ],
    "folderId": "<string>",
    "comments": "<string>",
    "shortLink": "<string>",
    "qrCode": "<string>",
    "utm_source": "<string>",
    "utm_medium": "<string>",
    "utm_campaign": "<string>",
    "utm_term": "<string>",
    "utm_content": "<string>",
    "testVariants": [
      {
        "url": "https://example.com/variant-1",
        "percentage": 50
      },
      {
        "url": "https://example.com/variant-2",
        "percentage": 50
      }
    ],
    "testStartedAt": "<string>",
    "testCompletedAt": "<string>",
    "userId": "<string>",
    "workspaceId": "<string>",
    "clicks": 0,
    "leads": 0,
    "conversions": 0,
    "sales": 0,
    "saleAmount": 0,
    "lastClicked": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "tagId": "<string>",
    "projectId": "<string>",
    "webhookIds": [
      "<string>"
    ]
  }
]

post/links/bulk

Warning

We currently do not send webhook events for bulk link creation.

Authorization

Authorizationstringheaderrequired#

Default authentication mechanism

Body

application/json

urlstringrequired#

The destination URL of the short link.

Length: max 32000

domainstring#

The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains).

Length: max 190

keystring#

The short link slug. If not provided, a random 7-character slug will be generated.

Length: max 190

keyLengthnumber#

The length of the short link slug. Defaults to 7 if not provided. When used with prefix, the total length of the key will be prefix.length + keyLength.

Range: 3–190

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

programIdstring#

The ID of the program the short link is associated with.

partnerIdstring#

The ID of the partner the short link is associated with.

prefixstring#

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

trackConversionboolean#

Whether to track conversions for the short link. Defaults to false if not provided.

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

folderIdstring#

The unique ID existing folder to assign the short link to.

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

geoobject#

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

Show child attributes

{key}string#

Length: max 32000

doIndexboolean#

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

utm_sourcestring#

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL.

Length: max 255

utm_mediumstring#

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL.

Length: max 255

utm_campaignstring#

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL.

Length: max 255

utm_termstring#

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL.

Length: max 255

utm_contentstring#

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL.

Length: max 255

refstring#

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL.

Length: max 255

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.

publicStatsbooleandeprecated#

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided.

tagIdstringdeprecated#

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link.

webhookIdsstring[]deprecated#

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data.

Responses

application/json

The created links

One of

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.

urlstringrequired#

The destination URL of the short link.

trackConversionbooleanrequired#

Whether to track conversions for the short link.

Default: false

externalIdstringrequired#

tenantIdstringrequired#

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.

programIdstringrequired#

The ID of the program the short link is associated with.

partnerIdstringrequired#

The ID of the partner the short link is associated with.

archivedbooleanrequired#

Whether the short link is archived.

Default: false

expiresAtstringrequired#

The date and time when the short link will expire in ISO-8601 format.

expiredUrlstringrequired#

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

disabledAtstringrequired#

The date and time when the short link was disabled. When a short link is disabled, it will redirect to its domain's not found URL, and its stats will be excluded from your overall stats.

passwordstringrequired#

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

proxybooleanrequired#

Whether the short link uses Custom Link Previews feature.

Default: false

titlestringrequired#

The title of the short link. Will be used for Custom Link Previews if proxy is true.

descriptionstringrequired#

The description of the short link. Will be used for Custom Link Previews if proxy is true.

imagestringrequired#

The image of the short link. Will be used for Custom Link Previews if proxy is true.

videostringrequired#

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

rewritebooleanrequired#

Whether the short link uses link cloaking.

Default: false

doIndexbooleanrequired#

Whether to allow search engines to index the short link.

Default: false

iosstringrequired#

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

androidstringrequired#

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

geoobjectrequired#

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. See https://d.to/geo for more information.

Show child attributes

{key}string#

publicStatsbooleanrequired#

Whether the short link's stats are publicly accessible.

Default: false

tagsobject[]required#

The tags assigned to the short link.

Show child attributes

idstringrequired#

The unique ID of the tag.

namestringrequired#

The name of the tag.

colorenum<string>required#

The color of the tag.

Options:redyellowgreenbluepurplebrowngraypink

folderIdstringrequired#

The unique ID of the folder assigned to the short link.

commentsstringrequired#

The comments for the short link.

shortLinkstringrequired#

The full URL of the short link, including the https protocol (e.g. https://dub.sh/try).

qrCodestringrequired#

The full URL of the QR code for the short link (e.g. https://api.dub.co/qr?url=https://dub.sh/try).

utm_sourcestringrequired#

The UTM source of the short link.

utm_mediumstringrequired#

The UTM medium of the short link.

utm_campaignstringrequired#

The UTM campaign of the short link.

utm_termstringrequired#

The UTM term of the short link.

utm_contentstringrequired#

The UTM content of the short link.

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.

userIdstringrequired#

The user ID of the creator of the short link.

workspaceIdstringrequired#

The workspace ID 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

lastClickedstringrequired#

The date and time when the short link was last clicked.

createdAtstringrequired#

The date and time when the short link was created.

updatedAtstringrequired#

The date and time when the short link was last updated.

tagIdstringrequireddeprecated#

Deprecated: Use tags instead. The unique ID of the tag assigned to the short link.

projectIdstringrequireddeprecated#

Deprecated: Use workspaceId instead. The project ID of the short link.

webhookIdsstring[]requireddeprecated#

linkanyrequired#

The link that caused the error.

errorstringrequired#

The error message.

codeenum<string>required#

The error code.

Options:bad_requestunauthorizedforbiddenexceeded_limitnot_foundconflictinvite_pendinginvite_expiredunprocessable_entityrate_limit_exceededinternal_server_error

Count links Bulk update links