Overview

Create a campaign from a public Instagram or TikTok post, pull its comments, likers, and metrics, register creator handles, and confirm which registered creators engaged. Every route is authenticated with Authorization: Bearer <API_TOKEN> against your API base URL.

What you can do

Base URL and authentication

Examples write your API base URL as {API_BASE_URL}. Send your API token as a Bearer token on every request:

curl {API_BASE_URL}/campaigns \
  -H "Authorization: Bearer <API_TOKEN>"

A missing or invalid token returns 401. Routes under /admin/ need a token with admin rights and return 403 otherwise.

Core objects

• Brand: owns campaigns and webhooks. You pass brandId when creating a campaign and when registering a webhook.
• Campaign: a reward program with a title, pointsReward, and one challenge.
• Challenge: the post to engage with, parsed from the campaign's targetUrl. Every scrape and verification route takes challengeId; you never pass the post URL again.
• Creator: a user identified by your own externalId, with linked Instagram or TikTok accounts.
• Attempt: one creator's progress through one challenge, tracked as a state machine.

Response envelope

Successful responses wrap the result in data. List routes add pagination:

{
  "data": [ ... ],
  "pagination": { "page": 1, "limit": 20, "total": 150 }
}

Errors return an error code and a human-readable message. Branch on error; message may be reworded.

{ "error": "NOT_FOUND", "message": "Campaign 42 not found" }

Routes that read a post or profile can also return the scraping codes listed in Scraping errors.

Pagination

List routes accept page (default 1) and limit (default 20). The likers list caps limit at 100.

Typical integration

1. Register a webhook for your brand and store the whsec_* secret.
2. Create a campaign from the post URL. Keep the returned challengeId.
3. Register each creator with your externalId and their handle.
4. When a creator takes part, create an attempt and advance it to claim_completion.
5. Handle creator.verified and reward.issued on your webhook endpoint.

If you prefer to verify in batch, refresh comments and call verify-and-reward on the campaign instead of steps 4 and 5.

Parameter tables and schemas for every route are in the API reference.