Fanvue API Documentation

By the end of this page you’ll have a tracking link the creator can share, campaign parameters riding on it, and a way to read back which fans it brought in. A tracking link records every click and attributes signed-in fans to the link. Engagement and earnings follow the fan’s first click across all of the creator’s links, while metadata follows their latest click on this one. You need an access token for the creator with these scopes:

Scope	Grants
`read:tracking_links`	List links, list a link’s clicks and users, read a user’s metadata
`write:tracking_links`	Create and delete links
`read:creator`	In addition, on the creator-scoped twins under `/creators/{creatorUserUuid}/tracking-links`

Create a link

POST /tracking-links takes name and externalSocialPlatform. The platform is one of facebook, instagram, other, reddit, snapchat, tiktok, twitter, youtube.

curl -X POST https://api.fanvue.com/tracking-links \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring launch - Instagram", "externalSocialPlatform": "instagram" }'

The 201 response is the full link object:

{
  "uuid": "f9c1a2b4-5d6e-4f70-8a91-2b3c4d5e6f70",
  "name": "Spring launch - Instagram",
  "linkUrl": "fv-3",
  "externalSocialPlatform": "instagram",
  "createdAt": "2026-03-01T09:00:00.000Z",
  "clicks": 0,
  "engagement": {
    "acquiredSubscribers": 0,
    "acquiredFollowers": 0,
    "totalSubscribers": 0,
    "totalFollowers": 0
  },
  "earnings": null
}

Field	Meaning
`uuid`	The link on the API.
`linkUrl`	The short slug the creator shares.
`clicks`	Every click, including clicks never matched to an account.
`engagement.acquiredSubscribers` / `acquiredFollowers`	Fans whose first click, across all of the creator’s links, was this one.
`engagement.totalSubscribers` / `totalFollowers`	Everyone who clicked this link and is a subscriber or follower now.
`earnings`	`{ totalGross, totalNet }` in USD cents, or `null` for a new link.

The shareable URL is the creator’s handle followed by the slug:

https://www.fanvue.com/ava-creates/fv-3

Attach your own metadata

Metadata is captured from the query string of the shared link, so there’s no API call and no field to set at creation time. Append plain query parameters, one per key:

https://www.fanvue.com/ava-creates/fv-3?utm_source=instagram&utm_campaign=spring_launch&ref=story_a&client_reference_id=crm-10482

Tracking links use plain query parameters. They do not use the metadata[<key>]=<value> bracket syntax that checkout links use. A bracketed key is not a tracking parameter and does not reach the allowlisted fields.

Capture limits, applied at click time:

Rule	Limit	On breach
Keys per click	10	Keys past the tenth are dropped, keeping the first ten in URL order
Value length	500 characters	The value is truncated
Repeated parameter	First value kept	`?a=1&a=2` stores `a=1`
Empty value	Not stored	`?utm_campaign=` is dropped and does not use a key slot
Reserved names	`handle`, `trackingLink`	Dropped and do not use a key slot

Nothing is rejected. Over-limit input is trimmed, so a click is never lost because of its query string.

Metadata is passthrough. Fanvue never interprets it, and it is readable by anyone holding the creator’s read:tracking_links scope. Do not put secrets or personal data in it.

Read clicks

GET /tracking-links/{uuid}/impressions returns every click, newest first, including clicks never matched to an account. It pages by cursor, with size from 1 to 50 (default 15); pass the previous response’s nextCursor as cursor until it is null.

curl "https://api.fanvue.com/tracking-links/f9c1a2b4-5d6e-4f70-8a91-2b3c4d5e6f70/impressions?size=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26"

{
  "data": [
    {
      "createdAt": "2026-03-02T14:05:11.000Z",
      "userUuid": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "metadata": { "utm_source": "instagram", "utm_campaign": "spring_launch", "ref": "story_a", "client_reference_id": "crm-10482" }
    },
    {
      "createdAt": "2026-03-02T13:58:40.000Z",
      "userUuid": null,
      "metadata": { "utm_source": "instagram" }
    }
  ],
  "nextCursor": null
}

userUuid is null for a click the visitor never followed with a sign-in. Expect plenty of these.

Read attributed fans

GET /tracking-links/{uuid}/users lists the fans whose clicks were matched to an account, with the same cursor pagination (limit and cursor). The list is a subset of clicks.

curl "https://api.fanvue.com/tracking-links/f9c1a2b4-5d6e-4f70-8a91-2b3c4d5e6f70/users" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26"

{
  "data": [
    {
      "uuid": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "handle": "sam-fan",
      "displayName": "Sam",
      "registeredAt": "2026-03-02T14:06:30.000Z",
      "subscribedAt": "2026-03-02T14:06:30.000Z",
      "currentSubscriptionStartedAt": "2026-03-02T14:06:30.000Z",
      "followedAt": null,
      "clickedAt": "2026-03-02T14:05:11.000Z",
      "status": "subscriber",
      "metadata": { "utm_source": "instagram", "utm_campaign": "spring_launch", "ref": "story_a", "client_reference_id": "crm-10482" }
    }
  ],
  "nextCursor": null
}

Field	Meaning
`registeredAt`	When the fan converted (subscribed or followed) through this link. `null` when there is no current relationship or the conversion predates the fan’s first click on this link. Not the account creation date.
`subscribedAt`	When the fan first subscribed to the creator, attributed or not. Does not move when a lapsed fan resubscribes.
`currentSubscriptionStartedAt`	Start of the subscription currently on file: the latest resubscribe, or `subscribedAt` if the fan never lapsed.
`followedAt`	When the fan followed the creator, attributed or not.
`clickedAt`	The fan’s first click on this link.
`status`	`subscriber`, `follower`, `expired`, `deleted`, or `null` for a fan with no current relationship.
`metadata`	Allowlisted parameters from the fan’s most recent click on this link, or `null`.

Read the metadata back

The users and impressions endpoints return only these keys, whatever else the landing URL carried:

Allowlisted key
`utm_campaign`
`utm_content`
`utm_medium`
`utm_source`
`utm_term`
`ref`
`click_id`
`clickid`
`clickId`
`fv_click_id`
`fvc_id`
`client_reference_id`

GET /tracking-links/{uuid}/users/{userUuid}/metadata returns every stored string key for one fan, with no allowlist:

curl https://api.fanvue.com/tracking-links/f9c1a2b4-5d6e-4f70-8a91-2b3c4d5e6f70/users/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/metadata \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26"

{
  "metadata": {
    "utm_source": "instagram",
    "utm_campaign": "spring_launch",
    "ref": "story_a",
    "client_reference_id": "crm-10482"
  }
}

Situation	Response
Link UUID is not one of the creator’s links, or was deleted	`404`
The fan has no attributed click on this link	`200` with `"metadata": null`
The fan’s most recent click on this link carried no parameters	`200` with `"metadata": null`

Metadata is never merged across clicks. A later click replaces the previous metadata wholesale, and a later click with no query parameters leaves it null. To keep values across visits, keep every parameter on every copy of the link you publish, or store the values in your own system the first time you read them.

Attribution rules

Signal	Rule	Where it applies
Engagement and earnings	First click. A fan counts for the first link they clicked across all of the creator’s links, including deleted ones.	`engagement`, `earnings`, `registeredAt`
Metadata	Latest click on this link.	`metadata` on users and impressions, the per-user metadata endpoint
Click count	Every click, matched or not.	`clicks`, the impressions endpoint

Timing:

A click made while signed in is attributed immediately.
A click made while signed out is recorded immediately and attributed when that visitor signs in from the same browser. Until then the fan does not appear in the users list and the metadata endpoint returns null.
A click made while signed in as the creator who owns the link is not recorded. Use a separate fan account when testing.

Metadata on webhooks

Creator webhook envelopes for creator.subscription.*, creator.follow.* and creator.purchase.* carry a tracking block with link_url and metadata for the fan’s most recent attributed click. The block is null when the fan has no tracking parameter and no click on one of the creator’s links. See Tracking on creator payment events. The legacy new follower and new subscriber events carry the same values as trackingLinkUrl and trackingLinkMetadata. The capture limits and the latest-click rule apply to both.

Start here

Authentication

API concepts

Guides

Track clicks and attribute fans with tracking links

Create a link

Attach your own metadata

Read clicks

Read attributed fans

Read the metadata back

Attribution rules

Metadata on webhooks

See also

​Create a link

​Attach your own metadata

​Read clicks

​Read attributed fans

​Read the metadata back

​Attribution rules

​Metadata on webhooks

​See also

Create a link

Attach your own metadata

Read clicks

Read attributed fans

Read the metadata back

Attribution rules

Metadata on webhooks

See also