A valid request URL is required to generate request examples{
"balance": 123,
"level": {
"name": "<string>",
"rank": 123,
"threshold": 123,
"icon": "<string>"
},
"next_level": {
"name": "<string>",
"rank": 123,
"threshold": 123,
"icon": "<string>",
"requirements": [
{
"kind": "points",
"met": true,
"have": 123,
"need": 123,
"target": "<string>",
"unit": "<string>"
}
]
},
"points_to_next": 123,
"achievements": [
{
"key": "<string>",
"name": "<string>",
"description": "<string>",
"icon": "<string>",
"unlocked_at": "2023-11-07T05:31:56Z"
}
],
"metrics": [
{
"key": "<string>",
"name": "<string>",
"unit": "<string>",
"icon": "<string>",
"value": 123
}
]
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}This person's points, level and badges
What the widget renders for the person holding the page: their balance, where it places them, and their shelf.
Nothing here writes, and there is no endpoint that does. A point is a fact landing — the same rule that gives an onboarding step no “mark as done”. The moment a page can ask for points, the page’s network tab is the game. Your own backend can grant one with POST /v1/points, which is a program you control.
An anonymous session is answered 200 with zeros rather than 401: the widget runs on your landing page, and nothing pays a visitor. What somebody earns after they sign in follows them — the anonymous-to-identified merge moves the ledger, so points earned in the session that became an account are not lost.
level and next_level are null when no level is defined or when there is nothing above — draw the progress bar off points_to_next, which is null at the top.
A badge’s CONDITION deliberately does not travel. Handing somebody “unlock at 40 invites” is handing them the rule to farm, and a hidden badge would stop being a surprise the moment anybody opened the network tab.
A LEVEL’s conditions travel and a BADGE’s do not, on the same response. It is the same principle twice: a badge is a surprise you are entitled to keep — handing somebody “unlock at 40 invites” hands them the rule to farm — while a rung is a goal your product is ASKING them to reach, and a progress bar that cannot say “2 courses to go” is a bar filling for reasons nobody can act on. The one thing withheld is the NAME of an audience.
A valid request URL is required to generate request examples{
"balance": 123,
"level": {
"name": "<string>",
"rank": 123,
"threshold": 123,
"icon": "<string>"
},
"next_level": {
"name": "<string>",
"rank": 123,
"threshold": 123,
"icon": "<string>",
"requirements": [
{
"kind": "points",
"met": true,
"have": 123,
"need": 123,
"target": "<string>",
"unit": "<string>"
}
]
},
"points_to_next": 123,
"achievements": [
{
"key": "<string>",
"name": "<string>",
"description": "<string>",
"icon": "<string>",
"unlocked_at": "2023-11-07T05:31:56Z"
}
],
"metrics": [
{
"key": "<string>",
"name": "<string>",
"unit": "<string>",
"icon": "<string>",
"value": 123
}
]
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Autorizações
A contact session token, uk_ct_…. Belongs to one of the developer's own users, and reads only that user's data.
Resposta
The standing.
The sum of their ledger. Zero for somebody who has earned nothing, and for an anonymous session.
The rung they are on, or null. null is the ordinary case rather than an error — most environments define no levels — and it must not be rendered as level zero.
Show child attributes
Show child attributes
The lowest rung above the current one that is not yet satisfied, or null at the top, with requirements saying what it is waiting for.
Show child attributes
Show child attributes
The POINTS gap to next_level, and zero when the next rung asks nothing about points. Kept for widgets built before metrics existed; next_level.requirements is what a bar should be drawn from now.
The shelf: every active badge that is not hidden, plus any hidden one they hold. Earned first, then the ones still to earn.
Show child attributes
Show child attributes
What this person has of each tally the environment counts, including the ones at zero — the badge shelf's own rule: a widget drawing "0 of 4 courses" is showing somebody a goal, while an absent key looks like a bug.
Show child attributes
Show child attributes