Concepts

Engagement verification models a post as part of a campaign, and a creator's engagement with it as an attempt. The data lookups use none of these objects: they take a post URL or a handle.

Brand, campaign and challenge

A brand owns campaigns, and each campaign has one challenge:

Brand

brandId

owns

owns

owns

Campaign

campaignId

has one

has one

has one

Challenge

challengeId

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. The challenge's stored comments and metrics, its likers and its attempts all take the challengeId; you never pass the post URL again.

In practice: one post, one campaign, one challengeId.

Creator and attempt

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. You register creators before their attempts can verify.

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