Tokfluence
Tokfluence
API Docs
API reference

Campaigns

A campaign is a collection of creators and the TikTok posts they delivered, with attached fees so you can compute spend, GMV, and ROI in one shot.

Campaigns created via the API and via the Tokfluence app share the same numbering and the same dashboard. You can start a campaign from your code and inspect it in the UI later.

POST/v1/campaigns#

Create a new campaign with an optional set of posts. Each post needs a TikTok URL and the creator handle responsible for it; we resolve the creator, attach the post, and queue it for analysis.

Per-URL pricing
Creating a campaign with posts triggers the live analyze pipeline on every URL. Total cost is 1 + (25 × number of URLs) credits. A 50-URL campaign costs 1251 credits. Want to start with an empty campaign and add URLs in smaller batches via POST /v1/posts/analyze? You can — the campaign create call accepts an empty posts array.

Body

ParamTypeNotes
namerequiredstringDisplay name. Unique within your account.
currencystringISO-4217 code, e.g. USD. Defaults to your account currency.
postsobject[]Optional. Each entry: { url, creator_handle, fee_cents? }.
posts[].urlrequiredstringTikTok video URL.
posts[].creator_handlerequiredstringTikTok username or tkc_ id.
posts[].fee_centsintCreator fee for this post, in cents. Defaults to 0.
bash
curl -X POST "https://developers.tokfluence.com/v1/campaigns" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring 2026 launch",
    "currency": "USD",
    "posts": [
      {
        "url": "https://www.tiktok.com/@alice/video/7234567890123456789",
        "creator_handle": "alice",
        "fee_cents": 50000
      }
    ]
  }'

Response

json
{
  "data": {
    "id": 4711,
    "name": "Spring 2026 launch",
    "currency": "USD",
    "tracked_influencers_count": 1,
    "tracked_posts_count": 1,
    "archived": false,
    "created_at": "2026-05-15T10:00:00Z",
    "updated_at": "2026-05-15T10:00:00Z"
  },
  "meta": {
    "tracked_posts_created": 1,
    "api_results": [{ "postId": "7234...", "status": "analyzed" }],
    "rejected": []
  }
}
Partial success
Posts whose creator_handle can't be resolved or whose URL is malformed are returned in meta.rejected instead of failing the whole request. Inspect rejected to see what was skipped and why.

GET/v1/campaigns/:id#

Read a campaign's basic info. Returns 404 campaign_not_found if the campaign isn't yours.

bash
curl "https://developers.tokfluence.com/v1/campaigns/4711" \
  -H "Authorization: Bearer $TOKEN"

GET/v1/campaigns/:id/metrics#

The dashboard KPIs aggregated across the entire campaign: spend, GMV, ROI, total views, engagement, top hashtags, top mentions.

json
{
  "data": {
    "currency": "USD",
    "spend_cents": 50000,
    "agency_fee_cents": 0,
    "creator_fee_cents": 50000,
    "gmv_cents": 120000,
    "roi": 1.4,
    "cpm_cents": 40,
    "total_views": 1240000,
    "total_likes": 84000,
    "total_engagement": 91300,
    "engagement_rate": 0.0736,
    "posts_published": 1,
    "top_hashtags": [{ "value": "wwe", "count": 1 }],
    "top_mentions": []
  }
}

GET/v1/campaigns/:id/posts#

Per-post breakdown: every tracked post merged with its latest stats. Posts that haven't finished analysis yet have status: "pending".

GET/v1/campaigns/:id/influencers#

Per-creator breakdown: every collaborator on the campaign with their tkc_ id, status, post count, and fee splits.

json
{
  "data": [
    {
      "id": "tkc_a1b2c3d4e5f6a7b8",
      "username": "alice",
      "picture": "https://...",
      "status": "collaborating",
      "tracked_at": "2026-05-15T10:00:00Z",
      "tracked_posts_count": 1,
      "creator_fee_cents": 50000,
      "agency_fee_cents": 0,
      "gmv_cents": 120000
    }
  ]
}

DELETE/v1/campaigns/:id#

Permanently delete a campaign and all its tracked posts. The creators stay in your lists.

bash
curl -X DELETE "https://developers.tokfluence.com/v1/campaigns/4711" \
  -H "Authorization: Bearer $TOKEN"

Returns 204 No Content on success.

Previous Posts Next AI search