Next steps

Base URL: $CONSUMER_API

The object

audiencestring · required

one of platform, business, consumer, resident

localestring · required

one of pt-MZ, en-US

generated_atstring (date-time) · required
stepsarray of NextStep · required
Show child attributes
idstring · required
journey_idstring · required
titlestring · required
linestring · required
statestring · required

one of todo, blocked

ownerstring · required

one of you, platform_review, team_member, utility_owner

actionobject · optional
Show child attributes
idstring · required

Portable destination intent each client maps to its own screen

labelstring · optional

Localized action label

routestring · optional

In-app route on the platform dashboard (platform setup only)

helpobject · required
Show child attributes
article_idstring · required

Help registry category/slug

blocked_reasonobject · required · nullable
Show child attributes
codestring · optional
messagestring · optional
wait_linestring · optional

Optional, localized like line. On the utility's review step (documents) until approval: how long the platform's review usually takes. Present only when the server has a figure: the median of past decided reviews once there are at least 3, else the configured onboarding.review_wait (default 0, meaning absent).

doorsarray of NextStepChoice · optional

The two resident entry doors (public entry only)

Show child attributes
idstring · required
titlestring · required
linestring · required
helpobject · required
Show child attributes
article_idstring · required
actionsarray of NextStepChoice · optional

Public utility lookup and request-status actions (public entry only)

Show child attributes
idstring · required
titlestring · required
linestring · required
helpobject · required
Show child attributes
article_idstring · required
run_tokenstring · optional

Opaque run token for a staff journey or the anonymous resident entry

The object
{
  "audience": "platform",
  "locale": "pt-MZ",
  "generated_at": "2026-11-19T09:30:00Z",
  "steps": [
    {
      "id": "customer_import",
      "journey_id": "utility_real",
      "title": "Fuga na Rua 3",
      "line": "line",
      "state": "todo",
      "owner": "you",
      "action": {
        "id": "utility.real.customer_import",
        "label": "label",
        "route": "/platform/settings/branding"
      },
      "help": {
        "article_id": "getting-started/import-customers"
      },
      "blocked_reason": {
        "code": "review_pending",
        "message": "Leitura confirmada no local."
      },
      "wait_line": "A revisão costuma demorar cerca de 2 dias."
    }
  ],
  "doors": [
    {
      "id": "resident.link-existing-account",
      "title": "Fuga na Rua 3",
      "line": "line",
      "help": {
        "article_id": "residents/link-resident-account"
      }
    }
  ],
  "actions": [
    {
      "id": "resident.link-existing-account",
      "title": "Fuga na Rua 3",
      "line": "line",
      "help": {
        "article_id": "residents/link-resident-account"
      }
    }
  ],
  "run_token": "run token"
}

The next one to three first-use steps

Logs

GET /next-steps

Returns the next one to three actionable steps for the signed-in resident, chosen and ordered by the server from progress, review state, capabilities, counts and connectors; an empty list when nothing is waiting. Each step has a stable ID, localized title and line (saved language, then Accept-Language, then the platform default), the role that acts, a portable action ID the client maps to its own screen, and a help article ID from the shared help registry. Clients keep no step list or order of their own. GET is safe to retry and completes nothing. A linked resident with an open or partly paid invoice still due gets the single step pay_balance (journey resident_link, action resident.pay); a linked resident with nothing due never gets find_utility or verify_account. Requires an authenticated resident.

Parameters

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 Next steps

Show attributes
audiencestring · required

one of platform, business, consumer, resident

localestring · required

one of pt-MZ, en-US

generated_atstring (date-time) · required
stepsarray of NextStep · required
Show child attributes
idstring · required
journey_idstring · required
titlestring · required
linestring · required
statestring · required

one of todo, blocked

ownerstring · required

one of you, platform_review, team_member, utility_owner

actionobject · optional
Show child attributes
idstring · required

Portable destination intent each client maps to its own screen

labelstring · optional

Localized action label

routestring · optional

In-app route on the platform dashboard (platform setup only)

helpobject · required
Show child attributes
article_idstring · required

Help registry category/slug

blocked_reasonobject · required · nullable
Show child attributes
codestring · optional
messagestring · optional
wait_linestring · optional

Optional, localized like line. On the utility's review step (documents) until approval: how long the platform's review usually takes. Present only when the server has a figure: the median of past decided reviews once there are at least 3, else the configured onboarding.review_wait (default 0, meaning absent).

doorsarray of NextStepChoice · optional

The two resident entry doors (public entry only)

Show child attributes
idstring · required
titlestring · required
linestring · required
helpobject · required
Show child attributes
article_idstring · required
actionsarray of NextStepChoice · optional

Public utility lookup and request-status actions (public entry only)

Show child attributes
idstring · required
titlestring · required
linestring · required
helpobject · required
Show child attributes
article_idstring · required
run_tokenstring · optional

Opaque run token for a staff journey or the anonymous resident entry

Errors 401 · 403

curl -X GET "$CONSUMER_API/next-steps" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "audience": "platform",
  "locale": "pt-MZ",
  "generated_at": "2026-11-19T09:30:00Z",
  "steps": [
    {
      "id": "customer_import",
      "journey_id": "utility_real",
      "title": "Fuga na Rua 3",
      "line": "line",
      "state": "todo",
      "owner": "you",
      "action": {
        "id": "utility.real.customer_import",
        "label": "label",
        "route": "/platform/settings/branding"
      },
      "help": {
        "article_id": "getting-started/import-customers"
      },
      "blocked_reason": {
        "code": "review_pending",
        "message": "Leitura confirmada no local."
      },
      "wait_line": "A revisão costuma demorar cerca de 2 dias."
    }
  ],
  "doors": [
    {
      "id": "resident.link-existing-account",
      "title": "Fuga na Rua 3",
      "line": "line",
      "help": {
        "article_id": "residents/link-resident-account"
      }
    }
  ],
  "actions": [
    {
      "id": "resident.link-existing-account",
      "title": "Fuga na Rua 3",
      "line": "line",
      "help": {
        "article_id": "residents/link-resident-account"
      }
    }
  ],
  "run_token": "run token"
}