Register creators

A creator is a user identified by your externalId, with one or more linked Instagram or TikTok handles. Verification matches a creator's linked handle against the comments or likers on a post, so a creator must be registered before their attempts can verify.

Register a creator and link a handle

Needs a token with admin rights.

Registers the creator if externalId is new and links the handle in one call. You assert that the handle belongs to this creator; no ownership check runs.

curl -X POST {API_BASE_URL}/social-accounts \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "cust_abc123",
    "platform": "instagram",
    "handle": "creator_jane",
    "displayName": "Jane Doe"
  }'

{
  "data": {
    "user": { "id": 42, "externalId": "cust_abc123", "email": "jane@example.com" },
    "socialAccount": {
      "id": 7,
      "platform": "instagram",
      "platformUsername": "creator_jane",
      "profileData": { "followers": 12800, "full_name": "Jane Doe", "is_verified": false }
    }
  }
}

The call is idempotent on the triple externalId + platform + handle:

The same handle may be linked under different externalIds, and an existing externalId is reused rather than rejected.

List creators

Returns every registered creator with linked accounts and their campaign stats.

{
  "data": [
    {
      "userId": 42,
      "email": "jane@example.com",
      "displayName": "Jane Doe",
      "avatarUrl": null,
      "platform": "instagram",
      "platformUsername": "creator_jane",
      "connectedAt": "2026-06-01T09:00:00.000Z",
      "profileData": { "followers": 12800, "full_name": "Jane Doe" },
      "totalAttempts": 5,
      "totalVerified": 4,
      "totalRewarded": 3,
      "totalPoints": 300
    }
  ]
}

userId is the internal id you can use on admin attempt routes instead of externalId.

Refresh a profile

Fetches the latest Instagram or TikTok profile data and replaces profileData wholesale, rather than merging into it. data is the new profile object itself, not the creator.

When the profile cannot be read the route returns a data lookup error. When it is read but comes back empty, the route returns 200 and data is {} — which also clears the stored profile, so keep the previous copy if you need it.

Check a handle

Answers whether an Instagram handle is linked to a registered creator. Accepts the handle with or without @.

{ "data": { "verified": true } }

Disconnect a handle

Needs a token with admin rights.

Soft-disconnects the active link matching externalId + platform + handle (case-insensitive). The handle stops counting for verification and listings at once; past attempts, matched comments, and rewards are kept.

curl -X POST {API_BASE_URL}/social-accounts/disconnect \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "cust_abc123", "platform": "instagram", "handle": "creator_jane" }'

{
  "data": {
    "id": 7,
    "platform": "instagram",
    "platformUsername": "creator_jane",
    "disconnectedAt": "2026-07-01T00:00:00.000Z"
  }
}

After disconnecting, the creator may link a different handle, another externalId may claim the freed handle, and re-posting the same triple to POST /social-accounts reconnects it. 404 means no active link matched.