Earning events

An XP rule can only price an event type that one of your installed modules declares. This page catalogs the engagement events declared by the 4D Engagement module and the payload each expects, so your backend knows what to send. How events get in is covered in Events; what can stop an award is covered in XP. The machine-readable source of truth is the module version manifest your installation is pinned to: GET /v1/installations (partner admin session) gives you the module_id and pinned version_id, GET /v1/modules/{moduleId}/versions returns each version’s manifest, and the emits[] entry for your event type carries the JSON Schema for its payload. An installation stays on its pinned version until you adopt a newer one, so read the pinned manifest rather than assuming the newest catalog version.

The catalog

Event type	A member…	Same content item
`engagement.content.viewed`	read or viewed a content item	Pays once per item
`engagement.quiz.completed`	completed a quiz	Pays once per item
`engagement.video.completed`	watched a video to the end	Pays once per item
`engagement.profile.completed`	finished the profile the club asked for	Repeatable: cap it with a lifetime limit of 1
`engagement.venue.attended`	checked in at a club venue	Repeatable: each visit can pay
`engagement.reply.posted`	posted a reply in a club thread	Repeatable: each reply is its own event

“Pays once per item” is the always-on same-content guard described in XP: the first paid event claims that item (content_id, quiz_id, video_id) for the member, and a later event for the same item is declined as content_already_earned, even if it arrives under a fresh event_id. The repeatable types have no per-item identity to claim, so the brakes there are the per-action daily and lifetime award limits your organization configures in the console.

Payload contracts

Send these as the payload of your event. The schemas are closed: an undeclared field is rejected. Every event needs a member identity: your member_external_id at the envelope level or a platform user_id in the payload; an event with neither is recorded but earns nothing.

`engagement.content.viewed`

Field	Status	Type
`content_id`	Required	string, identifies the content item
`user_id`	Required	string
`content_type`	Optional	string
`duration_seconds`	Optional	non-negative integer

Send duration_seconds as a whole number of seconds. A fractional value such as 12.5 fails the platform’s check on the event, and the event earns nothing.

`engagement.quiz.completed`

Field	Status	Type
`quiz_id`	Required	string, identifies the quiz
`user_id`	Required	string
`score`	Required	integer from 0 to 100

Send score as a whole number. A fractional score fails the same check, and the event earns nothing.

`engagement.video.completed`

Completion is your claim; the measurement fields use Google Analytics 4’s parameter names so a video player integration can forward what it already emits.

Field	Status	Type
`video_id`	Required	string, identifies the video asset
`video_title`	Optional	string
`video_url`	Optional	string
`video_duration`	Optional	non-negative number
`video_current_time`	Optional	non-negative number
`video_percent`	Optional	number from 0 to 100
`user_id`	Optional	string

`engagement.profile.completed`

A profile milestone, not a field-change event. No required payload fields.

Field	Status	Type
`completion_percent`	Optional	number from 0 to 100
`completed_fields`	Optional	non-negative integer
`required_fields`	Optional	non-negative integer
`user_id`	Optional	string

`engagement.venue.attended`

Check-in evidence is yours: the platform validates the field shapes, stores them and passes them through, but does not verify a geofence, QR value or beacon signal.

Field	Status	Type
`checkin_id`	Required	string, your check-in record
`venue_id`	Required	string, the venue in your system
`venue_name`	Optional	string
`fixture_id`	Optional	string, the match or occasion; also scopes the event id
`verification_method`	Optional	one of `geofence`, `qr`, `beacon`, `manual`
`accuracy_meters`	Optional	non-negative number
`user_id`	Optional	string

`engagement.reply.posted`

One event per reply, so a member can have many.

Field	Status	Type
`reply_id`	Required	string, the reply in your system
`thread_id`	Required	string
`parent_id`	Optional	string, the reply this one answers
`character_count`	Optional	non-negative integer, for a later minimum-length condition
`user_id`	Optional	string

Choose your event ids deliberately

event_id is the deduplication anchor: a repeat send of the same id credits nothing a second time. Derive it from the identity of the moment, not at random, and reuse it on retries:

Profile completed: organization_id + member_id. One milestone per member.
Venue attended: organization_id + member_id + venue_id + fixture_id, or the UTC calendar date of occurred_at when there is no fixture. One check-in per member, venue and occasion.
Video completed: organization_id + member_id + video_id. The platform’s same-content guard backs this up regardless of event ids.
Reply posted: organization_id + reply_id. A different reply must get a different id.

Any collision-resistant deterministic string works, as long as the same identity always produces the same id and your organization id is part of what you hash. Finally, pick one event type per asset. engagement.content.viewed and engagement.video.completed are different types: if you emit both for the same asset and both are priced, both pay. The platform does not infer that they describe the same content.

Discover what each event pays

The manifest tells you what an event must look like. What it pays is your organization’s XP rules, which are set in the console. Your backend can read the current pricing with GET /v1/xp/event-definitions, so it doesn’t have to copy amounts out of the console. The answer has one rule set per event type. A rule set has an optional default and an ordered list of cases. Cases are checked in the order returned, and the first case whose condition matches pays. If no case matches, the default pays, and with no default the set pays nothing. Exactly one member of a set pays per event. Rules written outside the console’s sets appear under adds_on_top. Each one that matches adds its award to the set’s, so when that list isn’t empty the set is not the whole price. Retired rules and old versions are left out. A boost can still multiply the result, and the earning controls can still decline it. Creating definitions needs a partner admin session; an org key can only read them.

API reference

List XP event definitions

GET /v1/xp/event-definitions authenticates with your organization API key as a bearer header (see Authentication). It takes no parameters and returns your organization’s active pricing.

export API_BASE_URL="https://api.develop.fourdos.dev"
export API_KEY="org_…"

curl "$API_BASE_URL/v1/xp/event-definitions" \
  -H "Authorization: Bearer $API_KEY"

200 OK:

{
  "rule_sets": [
    {
      "event_key": "engagement.content.viewed",
      "resolution": "first_matching_case_else_default",
      "default": {
        "name": "Any article",
        "amount": "10",
        "funding_source": { "kind": "engagement_reserve" }
      },
      "cases": [
        {
          "name": "Match reports",
          "amount": "25",
          "condition": {
            "field": "content_type",
            "operator": "eq",
            "value": "match_report"
          },
          "condition_summary": "when content type is match_report",
          "funding_source": { "kind": "engagement_reserve" }
        }
      ],
      "adds_on_top": [
        {
          "name": null,
          "advanced_award": "formula",
          "funding_source": { "kind": "engagement_reserve" }
        }
      ]
    }
  ]
}

Field	Type	Notes
`event_key`	string	The event type the set prices.
`resolution`	string	Always `first_matching_case_else_default`.
`default`	object or null	The fallback member, `null` when the set has none.
`cases`	array	The cases in the order they are checked.
`cases[].name`, `default.name`	string or null	The name given in the console.
`cases[].amount`, `default.amount`	string	The award, an integer string in XP minor units.
`cases[].condition`	object	`{ "field", "operator": "eq", "value" }` or `{ "field", "operator": "in", "values" }`. `field` is a canonical payload field; values keep their JSON type.
`cases[].condition_summary`	string	The condition as display text. Show it, don’t parse it.
`adds_on_top`	array	Active rules outside the set that add their award when they match.
`adds_on_top[].name`	string or null	`null` for an unnamed rule.
`adds_on_top[].advanced_award`	string	The kind of award, for example `formula`.
`funding_source`	object	`{ "kind": "engagement_reserve" }`, or `{ "kind": "sponsor_campaign", "campaign_id", "campaign_name" }`.

An organization with no active rules returns { "rule_sets": [] }.

Get started

Concepts

Walkthroughs

Content API

SDK

The catalog

Payload contracts

`engagement.content.viewed`

`engagement.quiz.completed`

`engagement.video.completed`

`engagement.profile.completed`

`engagement.venue.attended`

`engagement.reply.posted`

Choose your event ids deliberately

Discover what each event pays

API reference

List XP event definitions

​The catalog

​Payload contracts

​engagement.content.viewed

​engagement.quiz.completed

​engagement.video.completed

​engagement.profile.completed

​engagement.venue.attended

​engagement.reply.posted

​Choose your event ids deliberately

​Discover what each event pays

​API reference

​List XP event definitions

The catalog

Payload contracts

`engagement.content.viewed`

`engagement.quiz.completed`

`engagement.video.completed`

`engagement.profile.completed`

`engagement.venue.attended`

`engagement.reply.posted`

Choose your event ids deliberately

Discover what each event pays

API reference

List XP event definitions