Concepts

The API models a post as part of a campaign. That holds even when all you want is a post's comments or metrics, so three objects appear in every integration.

What every integration uses

A brand owns campaigns, each campaign has one challenge, and the challenge is what you look data up on:

Brand. Your tenant, identified by a brandId. It owns your campaigns and your webhooks. You pass brandId when you create a campaign.

Campaign. The container you create for a post, with a title, a pointsReward and exactly one challenge. See Create a campaign.

Challenge. The public post itself, parsed from the campaign's targetUrl and identified by a challengeId. Every data lookup on the post takes the challengeId; you never pass the post URL again.

In practice: one post, one campaign, one challengeId. To look up a second post, create a second campaign.

What engagement verification adds

Engagement verification answers a narrower question than a data lookup: did this particular person engage with the post? That needs two more objects.

Creator. A user identified by your own externalId, with linked Instagram or TikTok handles. In loyalty use cases this is any rewarded user, not only an influencer. Creators are also what the creator profile lookup reads; it is the one lookup addressed by a creator's userId instead of a challengeId.

Attempt. One creator's progress through one challenge, tracked as a state machine that ends in rewarded or failed_terminal. Attempt state changes are what webhooks report, and a verified attempt is what issues the campaign's pointsReward.

Where each object appears in the API