Creator profiles

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

POST /social-accounts (admin)

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

GET /admin/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

POST /admin/creators/{userId}/refresh

Fetches the latest Instagram or TikTok profile data and replaces profileData. Returns the updated object in data. When the profile cannot be read, the route returns a scraping error.

Check a handle

GET /admin/creators/verify/{handle}

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

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

Disconnect a handle

POST /social-accounts/disconnect (admin)

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.