A valid request URL is required to generate request examples{
"checklists": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"completed": true,
"dismissed": true,
"hint_pending": "<string>",
"hint_done": "<string>",
"hint_locked": "<string>",
"locked": true,
"locked_by": "<string>",
"steps": [
{
"key": "<string>",
"title": "<string>",
"kind": "event",
"event_type": "<string>",
"position": 123,
"satisfied": true,
"satisfied_at": "2023-11-07T05:31:56Z",
"action_url": "<string>",
"action_label": "<string>",
"hint_pending": "<string>",
"hint_done": "<string>"
}
]
}
],
"options": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"selected": true,
"steps": 123
}
]
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}My onboarding checklist
What the widget renders: the active checklists of this environment that this contact is in the audience for, each with its steps and whether this person has satisfied them.
There is no write half of this surface. A step is satisfied by a fact having happened or by an entitlement being held, never by anybody saying so — which is what keeps the completion funnel a measure of what people did rather than of what they clicked.
An anonymous session answers 200 with an empty list rather than a refusal. The widget runs on the landing page where every page load mints a visitor, onboarding is something a person does, and an error in the console of your most-visited page would be a poor way to say “there is nothing to show you”.
It needs a verified session for the same reason GET /v1/contact/entitlements does: an entitlement step is a slice of the same grant, and the same fact reached through a second door is what that gate exists to stop. Entitlement steps are decided against the team the request names (X-Customer-Id, or the oldest membership); a contact on no team holds no plan, so they read as unsatisfied.
satisfied_at is present only for event steps — an entitlement step is true right now rather than at a moment, and inventing a timestamp would let a client order it against facts that actually happened.
A valid request URL is required to generate request examples{
"checklists": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"completed": true,
"dismissed": true,
"hint_pending": "<string>",
"hint_done": "<string>",
"hint_locked": "<string>",
"locked": true,
"locked_by": "<string>",
"steps": [
{
"key": "<string>",
"title": "<string>",
"kind": "event",
"event_type": "<string>",
"position": 123,
"satisfied": true,
"satisfied_at": "2023-11-07T05:31:56Z",
"action_url": "<string>",
"action_label": "<string>",
"hint_pending": "<string>",
"hint_done": "<string>"
}
]
}
],
"options": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"selected": true,
"steps": 123
}
]
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Authorizations
A contact session token, uk_ct_…. Belongs to one of the developer's own users, and reads only that user's data.
Headers
The customer this call is acting inside — the same arrangement as X-Organization-Id, one plane down. Switching customers is navigation, not a mutation: nothing is stored, you send a different header, and the membership JOIN behind it decides what you may do there. An id you are not a member of matches no row and answers 404. Absent, the contact's oldest membership answers.
Query Parameters
Return the checklists this person has CLOSED as well, each marked with dismissed.
For the dedicated setup page — a screen somebody navigated to on purpose, where honouring a dismissal made on the dashboard would answer an explicit request with an empty card.
It reaches past the dismissal and nothing else: a checklist that is off stays off, the audience still decides, and a selectable one still has to have been chosen. Those are facts about the checklist; a close is a preference about a screen.
Response
The checklists, or an empty list for an anonymous session.
Show child attributes
Show child attributes
The menu behind the guide's "edit": every selectable checklist this person could put on it, and whether it is on it. It travels with the guide on the same round trip, so the modal opens with the choices already made rather than filling in a frame later.
Steps do not travel here — the modal offers outcomes, not the work behind each one.
Show child attributes
Show child attributes