Utility invitations

Base URL: $PUBLIC_API

The object

utility_namestring · optional
country_codestring · optional
setup_modestring · optional

one of invite, platform_managed

owner_contact_maskedstring · optional
contact_kindstring · optional

one of email, phone

expires_atstring (date-time) · optional
The object
{
  "utility_name": "Ana Matsinhe",
  "country_code": "MZ",
  "setup_mode": "invite",
  "owner_contact_masked": "owner contact masked",
  "contact_kind": "email",
  "expires_at": "2026-11-19T09:30:00Z"
}

Resolve an invitation link

Logs

POST /utility-invitations/open

Resolves the one-time token from the invitation landing page and records the invitation as opened. Returns the utility name, country, setup mode, masked owner contact and expiry so the page can be prefilled. Expired, revoked or used tokens return 410 without saying whether any account exists.

Body application/json

tokenstring · required

One-time token from the invitation link

Returns

200 Invitation preview

Show attributes
utility_namestring · optional
country_codestring · optional
setup_modestring · optional

one of invite, platform_managed

owner_contact_maskedstring · optional
contact_kindstring · optional

one of email, phone

expires_atstring (date-time) · optional

Errors 400 · 410

curl -X POST "$PUBLIC_API/utility-invitations/open" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "token"
}'
Response 200
{
  "utility_name": "Ana Matsinhe",
  "country_code": "MZ",
  "setup_mode": "invite",
  "owner_contact_masked": "owner contact masked",
  "contact_kind": "email",
  "expires_at": "2026-11-19T09:30:00Z"
}

Accept an invitation and create the owner's own credentials

Logs

POST /utility-invitations/accept

Consumes a valid token once, with the owner's display name (for a new account) and chosen password. For an invitation the utility name, country and plan come from the record and the response's session is the owner's normal utility session. For an on-behalf invitation the owner becomes a member but the utility stays closed until they accept the handover: the response carries handover.state pending_owner_acceptance and the handover summary, and the same session can call only the handover routes. An existing person must give their current password. Replays, expired and revoked tokens return 410.

Body application/json

tokenstring · required
full_namestring · optional

Required for a new account

passwordstring (password) · required

Returns

200 Accepted

Show attributes
invitation_statestring · required

one of accepted

setup_modestring · required

one of invite, platform_managed

handoverobject · required
Show child attributes
statestring · optional

one of not_required, pending_owner_acceptance, accepted

handover_summaryobject · optional
Show child attributes
invitation_idstring · required
tenant_idstring · required
utility_namestring · required
handoverobject · required
Show child attributes
statestring · optional

one of not_required, pending_owner_acceptance, accepted

accepted_atstring (date-time) · optional
completedarray of object · required
Show child attributes
step_idstring · optional
responsibilitystring · optional

one of platform, utility

completed_by_namestring · optional
completed_atstring (date-time) · optional
outstandingarray of string · required
sessionobject · required

The owner's own session

Errors 400 · 409 · 410

curl -X POST "$PUBLIC_API/utility-invitations/accept" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "token",
  "full_name": "Ana Matsinhe",
  "password": "password"
}'
Response 200
{
  "invitation_state": "accepted",
  "setup_mode": "invite",
  "handover": {
    "state": "not_required"
  },
  "handover_summary": {
    "invitation_id": "ivt_2pf2g1TgOrLQ0HT6IxvyElNWgBz",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "utility_name": "Ana Matsinhe",
    "handover": {
      "state": "not_required",
      "accepted_at": "2026-11-19T09:30:00Z"
    },
    "completed": [
      {
        "step_id": "service_areas",
        "responsibility": "platform",
        "completed_by_name": "Ana Matsinhe",
        "completed_at": "2026-11-19T09:30:00Z"
      }
    ],
    "outstanding": [
      "company_details",
      "documents"
    ]
  },
  "session": {}
}