First run

Base URL: $BUSINESS_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"
}

Check the utility's payment connection

Logs

POST /first-run/payment-check

A payment connection check: asks the utility's payment connectors, through the payment service, which payment methods are operational right now, and succeeds when at least one connector method is. Nothing is charged. Success in the real account (not the test account) completes the utility_real connect_payments step. Codes: payments_inactive, no_payment_connector, connector_unavailable. Requires business:onboarding:write and a role that may read the utility's payment methods.

Returns

200 The check outcome

Show attributes
outcomestring · required

one of succeeded, failed

codestring · optional

one of payments_inactive, no_payment_connector, connector_unavailable

checked_atstring (date-time) · required
retryableboolean · required
connectorsarray of string · optional

Names of the connectors with an operational method

Errors 401 · 403

curl -X POST "$BUSINESS_API/first-run/payment-check" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "outcome": "succeeded",
  "code": "payments_inactive",
  "checked_at": "2026-11-19T09:30:00Z",
  "retryable": true,
  "connectors": [
    "connector"
  ]
}

Read first-use progress for one journey

Logs

GET /first-run/progress

Returns the durable progress of the signed-in utility user and their tenant for one journey (utility_test, utility_real, staff_field_reader, staff_cashier, staff_finance): 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 business:onboarding:read for the utility journeys. A staff member reads only their own role journey with the entitlement of their own first-run action: business:reading-assignments:read for staff_field_reader, and business:onboarding:read or cashier:write (staff_cashier) or billing_runs:read (staff_finance); no subject or tenant selector is accepted. From a test (sandbox) account, utility_test is the owning real account's tour (the record the tour's actions credit, also for skips and resumes) and utility_real answers 404.

Parameters

journeystring · query · required

Journey ID

one of utility_test, utility_real, staff_field_reader, staff_cashier, staff_finance

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 "$BUSINESS_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 business:onboarding:write. Staff journeys are completed only by their actions and cannot be patched (403).

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 "$BUSINESS_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. Utility journeys require business:onboarding:write. Staff journeys require only a valid run token issued to the same principal for their role journey plus the entitlement of their own role action; this records the exit and grants no other onboarding access.

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 "$BUSINESS_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