First run

Base URL: $CONSUMER_API

The object

journey_idstring · required

one of platform_setup, utility_test, utility_real, resident_link, resident_connection, staff_field_reader, staff_cashier, staff_finance

subjectobject · required

Who changed a step, by actor type and stable user ID

Show child attributes
typestring · required
idstring · required
tenant_idstring · required · nullable

The utility for utility and staff journeys; null for the platform journey

updated_atstring (date-time) · required
stepsarray of FirstRunStep · required
Show child attributes
idstring · required
statestring · required

one of todo, done, skipped, blocked

can_skipboolean · required
allowed_skip_reasonsarray of string · required
reasonstring · optional

Skip reason code

changed_atstring (date-time) · optional
changed_byobject · optional

Who changed a step, by actor type and stable user ID

Show child attributes
typestring · required
idstring · required
completion_sourcestring · optional

The qualifying domain action that completed the step

completed_atstring (date-time) · optional
responsibilitystring · optional

Who does the step on a checklist the platform sets up on a utility's behalf

one of platform, utility

completed_byobject · optional

Who changed a step, by actor type and stable user ID

Show child attributes
typestring · required
idstring · required
run_tokenstring · optional

Opaque funnel run token; absent once the journey is complete

The object
{
  "journey_id": "platform_setup",
  "subject": {
    "type": "utility_staff",
    "id": "usr_01"
  },
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "updated_at": "2026-11-19T09:30:00Z",
  "steps": [
    {
      "id": "customer_import",
      "state": "todo",
      "can_skip": true,
      "allowed_skip_reasons": [
        "not_needed"
      ],
      "reason": "Leitura confirmada no local.",
      "changed_at": "2026-11-19T09:30:00Z",
      "changed_by": {
        "type": "utility_staff",
        "id": "usr_01"
      },
      "completion_source": "service_area.created",
      "completed_at": "2026-11-19T09:30:00Z",
      "responsibility": "platform",
      "completed_by": {
        "type": "utility_staff",
        "id": "usr_01"
      }
    }
  ],
  "run_token": "run token"
}

Read first-use progress for one journey

Logs

GET /first-run/progress

Returns the durable progress of the signed-in resident for one journey (resident_link, resident_connection): every step by stable ID in server order, its state (todo, done, skipped or blocked with a reason), whether and why it can be skipped, who changed it and when, and the qualifying action that completed it. A journey with no record returns its steps as todo. The response also carries an opaque run token the client sends back in the X-First-Run-Token header so funnel events join without storing who ran them. Requires an authenticated resident.

Parameters

journeystring · query · required

Journey ID

one of resident_link, resident_connection

X-First-Run-Tokenstring · header · optional

Opaque run token from an earlier progress or next-steps response. It joins this request's first-use events to one run and carries no identity.

Returns

200 Journey progress

Show attributes
journey_idstring · required

one of platform_setup, utility_test, utility_real, resident_link, resident_connection, staff_field_reader, staff_cashier, staff_finance

subjectobject · required

Who changed a step, by actor type and stable user ID

Show child attributes
typestring · required
idstring · required
tenant_idstring · required · nullable

The utility for utility and staff journeys; null for the platform journey

updated_atstring (date-time) · required
stepsarray of FirstRunStep · required
Show child attributes
idstring · required
statestring · required

one of todo, done, skipped, blocked

can_skipboolean · required
allowed_skip_reasonsarray of string · required
reasonstring · optional

Skip reason code

changed_atstring (date-time) · optional
changed_byobject · optional

Who changed a step, by actor type and stable user ID

Show child attributes
typestring · required
idstring · required
completion_sourcestring · optional

The qualifying domain action that completed the step

completed_atstring (date-time) · optional
responsibilitystring · optional

Who does the step on a checklist the platform sets up on a utility's behalf

one of platform, utility

completed_byobject · optional

Who changed a step, by actor type and stable user ID

Show child attributes
typestring · required
idstring · required
run_tokenstring · optional

Opaque funnel run token; absent once the journey is complete

Errors 401 · 403 · 404

curl -X GET "$CONSUMER_API/first-run/progress" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "journey_id": "platform_setup",
  "subject": {
    "type": "utility_staff",
    "id": "usr_01"
  },
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "updated_at": "2026-11-19T09:30:00Z",
  "steps": [
    {
      "id": "customer_import",
      "state": "todo",
      "can_skip": true,
      "allowed_skip_reasons": [
        "not_needed"
      ],
      "reason": "Leitura confirmada no local.",
      "changed_at": "2026-11-19T09:30:00Z",
      "changed_by": {
        "type": "utility_staff",
        "id": "usr_01"
      },
      "completion_source": "service_area.created",
      "completed_at": "2026-11-19T09:30:00Z",
      "responsibility": "platform",
      "completed_by": {
        "type": "utility_staff",
        "id": "usr_01"
      }
    }
  ],
  "run_token": "run token"
}

Skip or resume one first-use step

Logs

PATCH /first-run/progress/{journey}/{step}

Records an explicit skip (state skipped with a reason_code from the step's allowed_skip_reasons) or resumes a skipped step (state todo). A client can never write done or blocked: domain actions complete steps and prerequisites block them. A done step cannot be reopened (409). Security, identity and legal steps and the moment-of-value steps have no skip reasons. Requires an authenticated resident.

Parameters

journeystring · path · required

Journey ID

stepstring · path · required

Step ID

X-First-Run-Tokenstring · header · optional

Opaque run token from an earlier progress or next-steps response. It joins this request's first-use events to one run and carries no identity.

Body application/json

statestring · required

one of skipped, todo

reason_codestring · optional

Required for skipped; one of the step's allowed_skip_reasons

Returns

200 Updated journey progress

Show attributes
journey_idstring · required

one of platform_setup, utility_test, utility_real, resident_link, resident_connection, staff_field_reader, staff_cashier, staff_finance

subjectobject · required

Who changed a step, by actor type and stable user ID

Show child attributes
typestring · required
idstring · required
tenant_idstring · required · nullable

The utility for utility and staff journeys; null for the platform journey

updated_atstring (date-time) · required
stepsarray of FirstRunStep · required
Show child attributes
idstring · required
statestring · required

one of todo, done, skipped, blocked

can_skipboolean · required
allowed_skip_reasonsarray of string · required
reasonstring · optional

Skip reason code

changed_atstring (date-time) · optional
changed_byobject · optional

Who changed a step, by actor type and stable user ID

Show child attributes
typestring · required
idstring · required
completion_sourcestring · optional

The qualifying domain action that completed the step

completed_atstring (date-time) · optional
responsibilitystring · optional

Who does the step on a checklist the platform sets up on a utility's behalf

one of platform, utility

completed_byobject · optional

Who changed a step, by actor type and stable user ID

Show child attributes
typestring · required
idstring · required
run_tokenstring · optional

Opaque funnel run token; absent once the journey is complete

Errors 400 · 401 · 403 · 404 · 409

curl -X PATCH "$CONSUMER_API/first-run/progress/{journey}/{step}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "state": "skipped",
  "reason_code": "later"
}'
Response 200
{
  "journey_id": "platform_setup",
  "subject": {
    "type": "utility_staff",
    "id": "usr_01"
  },
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "updated_at": "2026-11-19T09:30:00Z",
  "steps": [
    {
      "id": "customer_import",
      "state": "todo",
      "can_skip": true,
      "allowed_skip_reasons": [
        "not_needed"
      ],
      "reason": "Leitura confirmada no local.",
      "changed_at": "2026-11-19T09:30:00Z",
      "changed_by": {
        "type": "utility_staff",
        "id": "usr_01"
      },
      "completion_source": "service_area.created",
      "completed_at": "2026-11-19T09:30:00Z",
      "responsibility": "platform",
      "completed_by": {
        "type": "utility_staff",
        "id": "usr_01"
      }
    }
  ],
  "run_token": "run token"
}

Record an explicit exit from a first-use journey

Logs

POST /first-run/abandon

Records that the user explicitly exited or cancelled the journey at the given step. It is sent only after an explicit exit; closing a tab, losing the network or inactivity are never recorded. The body carries only the opaque run token and the stable step ID: no reason text or identity. Repeats are idempotent. Requires an authenticated resident and a run token issued to them or the anonymous resident entry token.

Body application/json

run_tokenstring · required

Opaque run token

step_idstring · required
journey_idstring · optional

Only for the public route

Returns

204 Exit recorded

Errors 400 · 401 · 403 · 409

curl -X POST "$CONSUMER_API/first-run/abandon" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "run_token": "run token",
  "step_id": "open_todays_route",
  "journey_id": "resident_link"
}'
Response 204

Exit recorded