API reference

Canonical profile, tip, subscribe and buy links

Every shareable link for the creator behind the key, in one call — never template Dropfans URLs by hand.

View as MarkdownUpdated Aug 19, 2026

GET/api/external/linksNew

Every shareable link for the creator behind the key, in one call — never template Dropfans URLs by hand.

The web block always exists. The telegram block (Mini App deep links) is null when the shared Dropfans bot is not configured — fall back to the web links. Fields ending in Template contain literal placeholders to substitute: {usd} (whole dollars, web tip), {cents} (Telegram tip — note the unit difference), {productId} (buy links).

Per-fan tips: tipWithRefTemplate adds your {externalRef}, which comes back on the tip (tip.paid webhook, GET /api/external/tips). On the web the reference is 1–32 of A-Z a-z 0-9 _ -; in the Telegram template it is 1–20 of A-Z a-z 0-9 - with no underscore, and {cents} = 0 lets the fan pick the amount.

Tip prefill bounds: web ?tip=<usd> opens the sheet prefilled when the amount is between $5 and $750; out-of-range amounts open the sheet unfilled rather than erroring.

Authentication

Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.

An agency's own key can call this for a creator it manages by adding X-Dropfans-Account: <account id>. See Agencies.

Responses

200The creator’s links.

Name Type Description

username string The creator’s @handle the links are built for.

web

object

Canonical web links. Templates contain literal placeholders — substitute before use.

Show child attributes

`profile`	string	The creator’s public profile. Format: uri
`tip`	string	Opens the profile with the tip sheet open. Format: uri
`tipTemplate`	string	Tip link with the amount prefilled — replace `{usd}` with whole US dollars. Amounts outside the allowed range open the sheet unfilled.
`tipWithRefTemplate`	string	Tip link with a per-fan reference — replace `{usd}` (use `1` to let the fan pick the amount) and `{externalRef}` (1–32 of `A-Z a-z 0-9 _ -`). It comes back on the tip (tip.paid webhook, GET /api/external/tips).
`subscribe`	string	Opens the profile with the subscribe sheet open. Format: uri
`buyTemplate`	string	Checkout link for any drop — replace `{productId}` with the id from create-drop.
`buyWithRefTemplate`	string	The same with a per-fan reference — replace `{externalRef}` (1–32 of `A-Z a-z 0-9 _ -`). It comes back on the order (drop.paid webhook, GET /api/external/orders).

telegram

object | null

Telegram Mini App deep links. **Null when the shared Dropfans bot is not configured** — fall back to the web links.

Show child attributes

`bot`	string	The shared bot username, without @.
`profile`	string	Opens the creator’s Mini App profile. Format: uri
`tip`	string	Opens the Mini App tip sheet. Format: uri
`tipTemplate`	string	Tip prefilled — replace `{cents}` with the amount in cents (the web template takes dollars; this one takes cents).
`tipWithRefTemplate`	string	Mini App tip with a per-fan reference — replace `{cents}` (`0` lets the fan pick the amount) and `{externalRef}`. Here the reference is 1–20 of `A-Z a-z 0-9 -` (no underscore): it sits in front of the username, which may contain underscores, and Telegram caps the start parameter at 64 characters.
`subscribe`	string	Opens the Mini App subscribe flow. Format: uri
`buyTemplate`	string	Mini App checkout for any drop — replace `{productId}`.
`buyWithRefTemplate`	string	Mini App checkout with a per-fan reference — replace `{productId}` and `{externalRef}` (1–32 of `A-Z a-z 0-9 _ -`; Telegram caps the whole start parameter at 64 characters).

Example response

{
  "username": "valeria",
  "web": {
    "profile": "https://www.dropfans.io/u/valeria",
    "tip": "https://www.dropfans.io/u/valeria?tip=1",
    "tipTemplate": "https://www.dropfans.io/u/valeria?tip={usd}",
    "tipWithRefTemplate": "https://www.dropfans.io/u/valeria?tip={usd}&m={externalRef}",
    "subscribe": "https://www.dropfans.io/u/valeria?subscribe=1",
    "buyTemplate": "https://www.dropfans.io/buy/{productId}",
    "buyWithRefTemplate": "https://www.dropfans.io/buy/{productId}?m={externalRef}"
  },
  "telegram": {
    "bot": "DropfansBot",
    "profile": "https://t.me/DropfansBot/app?startapp=p_valeria",
    "tip": "https://t.me/DropfansBot/app?startapp=t_valeria",
    "tipTemplate": "https://t.me/DropfansBot/app?startapp=pt_{cents}_valeria",
    "tipWithRefTemplate": "https://t.me/DropfansBot/app?startapp=tm_{cents}_{externalRef}_valeria",
    "subscribe": "https://t.me/DropfansBot/app?startapp=s_valeria",
    "buyTemplate": "https://t.me/DropfansBot/app?startapp=b_{productId}",
    "buyWithRefTemplate": "https://t.me/DropfansBot/app?startapp=b_{productId}_{externalRef}"
  }
}

Errors

Status	Body	When
401	`{"error":"Unauthorized","code":"unauthorized"}`	Missing or invalid API key.
409	`{"error":"Set a username first","code":"username_required"}`	The creator has no username yet — every link embeds it. Have the creator pick a handle in their Dropfans settings, then retry.
400	`{"error":"X-Dropfans-Account must be an account id (from GET /api/external/agency/creators), not a username.","code":"invalid_account_header"}`	`X-Dropfans-Account` is not an account id.
403	`{"error":"This key cannot act for that account.","code":"account_not_managed"}`	`X-Dropfans-Account` names an account this key cannot act for: not an agency’s own key, no ACCEPTED management, or the agency or account is suspended, banned or deleted (an unknown id gets the same answer).

Rate limiting

Every response carries the X-RateLimit-Tier header and, on limited tiers, the per-minute and per-day trios — read X-RateLimit-Remaining and X-RateLimit-Reset instead of hardcoding limits. Details in Rate limits.

Code samples

curl "https://www.dropfans.io/api/external/links" \
  -H "Authorization: Bearer $DROPFANS_API_KEY"

const res = await fetch(`https://www.dropfans.io/api/external/links`, {
  headers: {
    Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
  },
});
console.log(await res.json());

import os
import requests

res = requests.get(
    "https://www.dropfans.io/api/external/links",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
)
print(res.json())

Notes

There is no endpoint to create a checkout session or an arbitrary-amount payment link: buyers pay through these pages/Mini App flows. The tip templates are the closest thing to a "payment link" — the amount is prefilled, the buyer confirms on Dropfans.

← Previous

List paid tips (per-fan references)

Read the Telegram notification status

Questions? [email protected]