Onboarding

Base URL: $BUSINESS_API

The object

idstring · optional
tenant_idstring · optional
statusstring · optional

one of not_started, in_progress, submitted, under_review, action_required, approved, rejected

business_profileobject · optional
representativeobject · optional
collection_channelsarray of object · optional
settlement_accountobject · optional
termsobject · optional
rejection_reasonstring · optional
custom_requirement_evidenceobject · optional
submitted_atstring (date-time) · optional
applicant_namestring · optional

The applicant utility's name as given at sign-up or invitation; on platform reads only

reviewed_atstring (date-time) · optional
requirementsobject · optional
Show child attributes
currently_duearray of string · optional
eventually_duearray of string · optional
past_duearray of string · optional
pending_verificationarray of string · optional
errorsarray of object · optional
Show child attributes
requirementstring · optional
codestring · optional

one of information_requested, document_rejected

reasonstring · optional
verification_requirementsarray of string · optional
capabilitiesobject · optional
Show child attributes
configurestring · optional

one of inactive, pending, active, restricted

customersstring · optional

one of inactive, pending, active, restricted

metersstring · optional

one of inactive, pending, active, restricted

draft_billingstring · optional

one of inactive, pending, active, restricted

invoicesstring · optional

one of inactive, pending, active, restricted

paymentsstring · optional

one of inactive, pending, active, restricted

messagesstring · optional

one of inactive, pending, active, restricted

public_profilestring · optional

one of inactive, pending, active, restricted

custom_domainstring · optional

one of inactive, pending, active, restricted

live_apistring · optional

one of inactive, pending, active, restricted

sandboxstring · optional

one of inactive, pending, active, restricted

billingstring · optional

one of inactive, pending, active, restricted

field_operationsstring · optional

one of inactive, pending, active, restricted

statesobject · optional
reasonsobject · optional

Actionable reason for each non-active capability.

documentsarray of OnboardingDocument · optional
Show child attributes
idstring · optional
typestring · optional

one of incorporation, tax_certificate, concession_licence, representative_id

file_namestring · optional
content_typestring · optional
size_bytesinteger · optional
statusstring · optional

one of pending, accepted, rejected

rejection_reasonstring · optional
current_terms_versionstring · optional
historyarray of object · optional

Review events, on platform responses only

Show child attributes
actorstring · optional
actionstring · optional
detailstring · optional
created_atstring (date-time) · optional
The object
{
  "id": "onb_2Q6dzKEzZcYlDE2ZR0Q99qW1JoE",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "not_started",
  "business_profile": {},
  "representative": {},
  "collection_channels": [
    {}
  ],
  "settlement_account": {},
  "terms": {},
  "rejection_reason": "rejection reason",
  "custom_requirement_evidence": {
    "key": {
      "value": "value",
      "status": "submitted",
      "reason": "Leitura confirmada no local."
    }
  },
  "submitted_at": "2026-11-19T09:30:00Z",
  "applicant_name": "Ana Matsinhe",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "requirements": {
    "currently_due": [
      "currently due"
    ],
    "eventually_due": [
      "eventually due"
    ],
    "past_due": [
      "past due"
    ],
    "pending_verification": [
      "pending verification"
    ],
    "errors": [
      {
        "requirement": "requirement",
        "code": "information_requested",
        "reason": "Leitura confirmada no local."
      }
    ]
  },
  "verification_requirements": [
    "verification requirement"
  ],
  "capabilities": {
    "configure": "inactive",
    "customers": "inactive",
    "meters": "inactive",
    "draft_billing": "inactive",
    "invoices": "inactive",
    "payments": "inactive",
    "messages": "inactive",
    "public_profile": "inactive",
    "custom_domain": "inactive",
    "live_api": "inactive",
    "sandbox": "inactive",
    "billing": "inactive",
    "field_operations": "inactive",
    "states": {
      "key": "inactive"
    },
    "reasons": {
      "key": {
        "code": "requirements_due",
        "requirements": [
          "requirement"
        ]
      }
    }
  },
  "documents": [
    {
      "id": "onb_2trMqh7CG1RYcPnI4f34YJd6q9z",
      "type": "incorporation",
      "file_name": "Ana Matsinhe",
      "content_type": "content type",
      "size_bytes": 1,
      "status": "pending",
      "rejection_reason": "rejection reason"
    }
  ],
  "current_terms_version": "current terms version",
  "history": [
    {
      "actor": "actor",
      "action": "action",
      "detail": "detail",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Get business onboarding

Logs

GET /onboarding

Get the utility onboarding application, created on first read

Returns the tenant's onboarding application with its status, the requirements currently due, pending verification and satisfied, any information requests from reviewers, and the capabilities the tenant has. If the tenant has no application yet, one is created in not_started status. Requires the business:onboarding:read permission.

Returns

200 Application with computed requirements, capabilities and documents

Show attributes
idstring · optional
tenant_idstring · optional
statusstring · optional

one of not_started, in_progress, submitted, under_review, action_required, approved, rejected

business_profileobject · optional
representativeobject · optional
collection_channelsarray of object · optional
settlement_accountobject · optional
termsobject · optional
rejection_reasonstring · optional
custom_requirement_evidenceobject · optional
submitted_atstring (date-time) · optional
applicant_namestring · optional

The applicant utility's name as given at sign-up or invitation; on platform reads only

reviewed_atstring (date-time) · optional
requirementsobject · optional
Show child attributes
currently_duearray of string · optional
eventually_duearray of string · optional
past_duearray of string · optional
pending_verificationarray of string · optional
errorsarray of object · optional
Show child attributes
requirementstring · optional
codestring · optional

one of information_requested, document_rejected

reasonstring · optional
verification_requirementsarray of string · optional
capabilitiesobject · optional
Show child attributes
configurestring · optional

one of inactive, pending, active, restricted

customersstring · optional

one of inactive, pending, active, restricted

metersstring · optional

one of inactive, pending, active, restricted

draft_billingstring · optional

one of inactive, pending, active, restricted

invoicesstring · optional

one of inactive, pending, active, restricted

paymentsstring · optional

one of inactive, pending, active, restricted

messagesstring · optional

one of inactive, pending, active, restricted

public_profilestring · optional

one of inactive, pending, active, restricted

custom_domainstring · optional

one of inactive, pending, active, restricted

live_apistring · optional

one of inactive, pending, active, restricted

sandboxstring · optional

one of inactive, pending, active, restricted

billingstring · optional

one of inactive, pending, active, restricted

field_operationsstring · optional

one of inactive, pending, active, restricted

statesobject · optional
reasonsobject · optional

Actionable reason for each non-active capability.

documentsarray of OnboardingDocument · optional
Show child attributes
idstring · optional
typestring · optional

one of incorporation, tax_certificate, concession_licence, representative_id

file_namestring · optional
content_typestring · optional
size_bytesinteger · optional
statusstring · optional

one of pending, accepted, rejected

rejection_reasonstring · optional
current_terms_versionstring · optional
historyarray of object · optional

Review events, on platform responses only

Show child attributes
actorstring · optional
actionstring · optional
detailstring · optional
created_atstring (date-time) · optional

Permissions business:onboarding:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/onboarding" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "onb_2Q6dzKEzZcYlDE2ZR0Q99qW1JoE",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "not_started",
  "business_profile": {},
  "representative": {},
  "collection_channels": [
    {}
  ],
  "settlement_account": {},
  "terms": {},
  "rejection_reason": "rejection reason",
  "custom_requirement_evidence": {
    "key": {
      "value": "value",
      "status": "submitted",
      "reason": "Leitura confirmada no local."
    }
  },
  "submitted_at": "2026-11-19T09:30:00Z",
  "applicant_name": "Ana Matsinhe",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "requirements": {
    "currently_due": [
      "currently due"
    ],
    "eventually_due": [
      "eventually due"
    ],
    "past_due": [
      "past due"
    ],
    "pending_verification": [
      "pending verification"
    ],
    "errors": [
      {
        "requirement": "requirement",
        "code": "information_requested",
        "reason": "Leitura confirmada no local."
      }
    ]
  },
  "verification_requirements": [
    "verification requirement"
  ],
  "capabilities": {
    "configure": "inactive",
    "customers": "inactive",
    "meters": "inactive",
    "draft_billing": "inactive",
    "invoices": "inactive",
    "payments": "inactive",
    "messages": "inactive",
    "public_profile": "inactive",
    "custom_domain": "inactive",
    "live_api": "inactive",
    "sandbox": "inactive",
    "billing": "inactive",
    "field_operations": "inactive",
    "states": {
      "key": "inactive"
    },
    "reasons": {
      "key": {
        "code": "requirements_due",
        "requirements": [
          "requirement"
        ]
      }
    }
  },
  "documents": [
    {
      "id": "onb_2trMqh7CG1RYcPnI4f34YJd6q9z",
      "type": "incorporation",
      "file_name": "Ana Matsinhe",
      "content_type": "content type",
      "size_bytes": 1,
      "status": "pending",
      "rejection_reason": "rejection reason"
    }
  ],
  "current_terms_version": "current terms version",
  "history": [
    {
      "actor": "actor",
      "action": "action",
      "detail": "detail",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Update business onboarding

Logs

PATCH /onboarding

Partially update onboarding sections, validated field by field

Updates only the sections and fields sent (business profile, representative, collection channels, settlement account, terms acceptance) and returns the recomputed application; a not_started application moves to in_progress. Fields that fail validation are all reported in one 400 response, and updating a field clears the reviewer's information request for it. Returns 409 when the application is not editable; an approved application may still change payment details or correct its tax number.

Body application/json

business_profileobject · optional
Show child attributes
legal_namestring · optional
trading_namestring · optional
nuitstring · optional

Nine-digit Mozambican NUIT including the Modulo 11 check digit

registration_numberstring · optional
addressstring · optional
licence_referencestring · optional
phonestring · optional
support_contactstring · optional

E-mail or phone

representativeobject · optional
Show child attributes
namestring · optional
rolestring · optional
id_document_numberstring · optional
date_of_birthstring (date) · optional
contactstring · optional
collection_channelsarray of object · optional
Show child attributes
typestring · required

One of collection_channel_types.

referencestring · required
collection_channel_typesarray of string · optional

The channel types the server accepts; configuration forms offer these.

settlement_accountobject · optional
Show child attributes
bankstring · optional
account_holderstring · optional
account_numberstring · optional

21-digit NIB or IBAN; returned masked

termsobject · optional
Show child attributes
acceptedboolean · required
versionstring · required

Must equal current_terms_version

Returns

200 Updated application

Show attributes
idstring · optional
tenant_idstring · optional
statusstring · optional

one of not_started, in_progress, submitted, under_review, action_required, approved, rejected

business_profileobject · optional
representativeobject · optional
collection_channelsarray of object · optional
settlement_accountobject · optional
termsobject · optional
rejection_reasonstring · optional
custom_requirement_evidenceobject · optional
submitted_atstring (date-time) · optional
applicant_namestring · optional

The applicant utility's name as given at sign-up or invitation; on platform reads only

reviewed_atstring (date-time) · optional
requirementsobject · optional
Show child attributes
currently_duearray of string · optional
eventually_duearray of string · optional
past_duearray of string · optional
pending_verificationarray of string · optional
errorsarray of object · optional
Show child attributes
requirementstring · optional
codestring · optional

one of information_requested, document_rejected

reasonstring · optional
verification_requirementsarray of string · optional
capabilitiesobject · optional
Show child attributes
configurestring · optional

one of inactive, pending, active, restricted

customersstring · optional

one of inactive, pending, active, restricted

metersstring · optional

one of inactive, pending, active, restricted

draft_billingstring · optional

one of inactive, pending, active, restricted

invoicesstring · optional

one of inactive, pending, active, restricted

paymentsstring · optional

one of inactive, pending, active, restricted

messagesstring · optional

one of inactive, pending, active, restricted

public_profilestring · optional

one of inactive, pending, active, restricted

custom_domainstring · optional

one of inactive, pending, active, restricted

live_apistring · optional

one of inactive, pending, active, restricted

sandboxstring · optional

one of inactive, pending, active, restricted

billingstring · optional

one of inactive, pending, active, restricted

field_operationsstring · optional

one of inactive, pending, active, restricted

statesobject · optional
reasonsobject · optional

Actionable reason for each non-active capability.

documentsarray of OnboardingDocument · optional
Show child attributes
idstring · optional
typestring · optional

one of incorporation, tax_certificate, concession_licence, representative_id

file_namestring · optional
content_typestring · optional
size_bytesinteger · optional
statusstring · optional

one of pending, accepted, rejected

rejection_reasonstring · optional
current_terms_versionstring · optional
historyarray of object · optional

Review events, on platform responses only

Show child attributes
actorstring · optional
actionstring · optional
detailstring · optional
created_atstring (date-time) · optional

Errors 400 · 409

Permissions business:onboarding:write · Roles: admin, owner

curl -X PATCH "$BUSINESS_API/onboarding" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "business_profile": {
    "legal_name": "Ana Matsinhe",
    "trading_name": "Ana Matsinhe",
    "nuit": "400123456",
    "registration_number": "REG-2026-000142",
    "address": "Av. Julius Nyerere 1420, Maputo",
    "licence_reference": "LIC-2026-000142",
    "phone": "+258841234567",
    "support_contact": "support contact"
  },
  "representative": {
    "name": "Ana Matsinhe",
    "role": "role",
    "id_document_number": "IDD-2026-000142",
    "date_of_birth": "2026-11-19",
    "contact": "contact"
  },
  "collection_channels": [
    {
      "type": "active",
      "reference": "REF-2026-000142"
    }
  ],
  "collection_channel_types": [
    "collection channel type"
  ],
  "settlement_account": {
    "bank": "bank",
    "account_holder": "account holder",
    "account_number": "ACC-2026-000142"
  },
  "terms": {
    "accepted": true,
    "version": "version"
  }
}'
Response 200
{
  "id": "onb_2Q6dzKEzZcYlDE2ZR0Q99qW1JoE",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "not_started",
  "business_profile": {},
  "representative": {},
  "collection_channels": [
    {}
  ],
  "settlement_account": {},
  "terms": {},
  "rejection_reason": "rejection reason",
  "custom_requirement_evidence": {
    "key": {
      "value": "value",
      "status": "submitted",
      "reason": "Leitura confirmada no local."
    }
  },
  "submitted_at": "2026-11-19T09:30:00Z",
  "applicant_name": "Ana Matsinhe",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "requirements": {
    "currently_due": [
      "currently due"
    ],
    "eventually_due": [
      "eventually due"
    ],
    "past_due": [
      "past due"
    ],
    "pending_verification": [
      "pending verification"
    ],
    "errors": [
      {
        "requirement": "requirement",
        "code": "information_requested",
        "reason": "Leitura confirmada no local."
      }
    ]
  },
  "verification_requirements": [
    "verification requirement"
  ],
  "capabilities": {
    "configure": "inactive",
    "customers": "inactive",
    "meters": "inactive",
    "draft_billing": "inactive",
    "invoices": "inactive",
    "payments": "inactive",
    "messages": "inactive",
    "public_profile": "inactive",
    "custom_domain": "inactive",
    "live_api": "inactive",
    "sandbox": "inactive",
    "billing": "inactive",
    "field_operations": "inactive",
    "states": {
      "key": "inactive"
    },
    "reasons": {
      "key": {
        "code": "requirements_due",
        "requirements": [
          "requirement"
        ]
      }
    }
  },
  "documents": [
    {
      "id": "onb_2trMqh7CG1RYcPnI4f34YJd6q9z",
      "type": "incorporation",
      "file_name": "Ana Matsinhe",
      "content_type": "content type",
      "size_bytes": 1,
      "status": "pending",
      "rejection_reason": "rejection reason"
    }
  ],
  "current_terms_version": "current terms version",
  "history": [
    {
      "actor": "actor",
      "action": "action",
      "detail": "detail",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Submit the application for review

Logs

POST /onboarding/submit

Moves the application to submitted so the platform can review it, records the submission time and returns the updated application. Returns 409 listing every outstanding requirement while anything is currently due, and 409 when the application is not in not_started, in_progress or action_required. Requires the business:onboarding:submit permission.

Returns

200 Submitted application

Show attributes
idstring · optional
tenant_idstring · optional
statusstring · optional

one of not_started, in_progress, submitted, under_review, action_required, approved, rejected

business_profileobject · optional
representativeobject · optional
collection_channelsarray of object · optional
settlement_accountobject · optional
termsobject · optional
rejection_reasonstring · optional
custom_requirement_evidenceobject · optional
submitted_atstring (date-time) · optional
applicant_namestring · optional

The applicant utility's name as given at sign-up or invitation; on platform reads only

reviewed_atstring (date-time) · optional
requirementsobject · optional
Show child attributes
currently_duearray of string · optional
eventually_duearray of string · optional
past_duearray of string · optional
pending_verificationarray of string · optional
errorsarray of object · optional
Show child attributes
requirementstring · optional
codestring · optional

one of information_requested, document_rejected

reasonstring · optional
verification_requirementsarray of string · optional
capabilitiesobject · optional
Show child attributes
configurestring · optional

one of inactive, pending, active, restricted

customersstring · optional

one of inactive, pending, active, restricted

metersstring · optional

one of inactive, pending, active, restricted

draft_billingstring · optional

one of inactive, pending, active, restricted

invoicesstring · optional

one of inactive, pending, active, restricted

paymentsstring · optional

one of inactive, pending, active, restricted

messagesstring · optional

one of inactive, pending, active, restricted

public_profilestring · optional

one of inactive, pending, active, restricted

custom_domainstring · optional

one of inactive, pending, active, restricted

live_apistring · optional

one of inactive, pending, active, restricted

sandboxstring · optional

one of inactive, pending, active, restricted

billingstring · optional

one of inactive, pending, active, restricted

field_operationsstring · optional

one of inactive, pending, active, restricted

statesobject · optional
reasonsobject · optional

Actionable reason for each non-active capability.

documentsarray of OnboardingDocument · optional
Show child attributes
idstring · optional
typestring · optional

one of incorporation, tax_certificate, concession_licence, representative_id

file_namestring · optional
content_typestring · optional
size_bytesinteger · optional
statusstring · optional

one of pending, accepted, rejected

rejection_reasonstring · optional
current_terms_versionstring · optional
historyarray of object · optional

Review events, on platform responses only

Show child attributes
actorstring · optional
actionstring · optional
detailstring · optional
created_atstring (date-time) · optional

Errors 409

Permissions business:onboarding:submit · Roles: admin, owner

curl -X POST "$BUSINESS_API/onboarding/submit" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "onb_2Q6dzKEzZcYlDE2ZR0Q99qW1JoE",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "not_started",
  "business_profile": {},
  "representative": {},
  "collection_channels": [
    {}
  ],
  "settlement_account": {},
  "terms": {},
  "rejection_reason": "rejection reason",
  "custom_requirement_evidence": {
    "key": {
      "value": "value",
      "status": "submitted",
      "reason": "Leitura confirmada no local."
    }
  },
  "submitted_at": "2026-11-19T09:30:00Z",
  "applicant_name": "Ana Matsinhe",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "requirements": {
    "currently_due": [
      "currently due"
    ],
    "eventually_due": [
      "eventually due"
    ],
    "past_due": [
      "past due"
    ],
    "pending_verification": [
      "pending verification"
    ],
    "errors": [
      {
        "requirement": "requirement",
        "code": "information_requested",
        "reason": "Leitura confirmada no local."
      }
    ]
  },
  "verification_requirements": [
    "verification requirement"
  ],
  "capabilities": {
    "configure": "inactive",
    "customers": "inactive",
    "meters": "inactive",
    "draft_billing": "inactive",
    "invoices": "inactive",
    "payments": "inactive",
    "messages": "inactive",
    "public_profile": "inactive",
    "custom_domain": "inactive",
    "live_api": "inactive",
    "sandbox": "inactive",
    "billing": "inactive",
    "field_operations": "inactive",
    "states": {
      "key": "inactive"
    },
    "reasons": {
      "key": {
        "code": "requirements_due",
        "requirements": [
          "requirement"
        ]
      }
    }
  },
  "documents": [
    {
      "id": "onb_2trMqh7CG1RYcPnI4f34YJd6q9z",
      "type": "incorporation",
      "file_name": "Ana Matsinhe",
      "content_type": "content type",
      "size_bytes": 1,
      "status": "pending",
      "rejection_reason": "rejection reason"
    }
  ],
  "current_terms_version": "current terms version",
  "history": [
    {
      "actor": "actor",
      "action": "action",
      "detail": "detail",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Submit custom onboarding requirement

Logs

POST /onboarding/requirements/{key}

Submit text evidence for a configured manual verification requirement

Stores the given text value (1 to 4000 characters) as evidence for a manual-review requirement configured in the verification catalog and marks it submitted for platform review. Returns 400 when the key is not a manual requirement or is not required for this tenant, and 409 when the requirement is already verified or the application is submitted or under review.

Parameters

keystring · path · required

Key of a manual-review requirement from the verification catalog, in the form custom.<name> where the name uses lower-case letters, digits, dots, underscores and hyphens, up to 80 characters in total.

Body application/json

valuestring · required

Returns

200 Application with submitted evidence state

Show attributes
idstring · optional
tenant_idstring · optional
statusstring · optional

one of not_started, in_progress, submitted, under_review, action_required, approved, rejected

business_profileobject · optional
representativeobject · optional
collection_channelsarray of object · optional
settlement_accountobject · optional
termsobject · optional
rejection_reasonstring · optional
custom_requirement_evidenceobject · optional
submitted_atstring (date-time) · optional
applicant_namestring · optional

The applicant utility's name as given at sign-up or invitation; on platform reads only

reviewed_atstring (date-time) · optional
requirementsobject · optional
Show child attributes
currently_duearray of string · optional
eventually_duearray of string · optional
past_duearray of string · optional
pending_verificationarray of string · optional
errorsarray of object · optional
Show child attributes
requirementstring · optional
codestring · optional

one of information_requested, document_rejected

reasonstring · optional
verification_requirementsarray of string · optional
capabilitiesobject · optional
Show child attributes
configurestring · optional

one of inactive, pending, active, restricted

customersstring · optional

one of inactive, pending, active, restricted

metersstring · optional

one of inactive, pending, active, restricted

draft_billingstring · optional

one of inactive, pending, active, restricted

invoicesstring · optional

one of inactive, pending, active, restricted

paymentsstring · optional

one of inactive, pending, active, restricted

messagesstring · optional

one of inactive, pending, active, restricted

public_profilestring · optional

one of inactive, pending, active, restricted

custom_domainstring · optional

one of inactive, pending, active, restricted

live_apistring · optional

one of inactive, pending, active, restricted

sandboxstring · optional

one of inactive, pending, active, restricted

billingstring · optional

one of inactive, pending, active, restricted

field_operationsstring · optional

one of inactive, pending, active, restricted

statesobject · optional
reasonsobject · optional

Actionable reason for each non-active capability.

documentsarray of OnboardingDocument · optional
Show child attributes
idstring · optional
typestring · optional

one of incorporation, tax_certificate, concession_licence, representative_id

file_namestring · optional
content_typestring · optional
size_bytesinteger · optional
statusstring · optional

one of pending, accepted, rejected

rejection_reasonstring · optional
current_terms_versionstring · optional
historyarray of object · optional

Review events, on platform responses only

Show child attributes
actorstring · optional
actionstring · optional
detailstring · optional
created_atstring (date-time) · optional

Errors 400 · 401 · 409

Permissions business:onboarding:write · Roles: admin, owner

curl -X POST "$BUSINESS_API/onboarding/requirements/{key}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "value": "value"
}'
Response 200
{
  "id": "onb_2Q6dzKEzZcYlDE2ZR0Q99qW1JoE",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "not_started",
  "business_profile": {},
  "representative": {},
  "collection_channels": [
    {}
  ],
  "settlement_account": {},
  "terms": {},
  "rejection_reason": "rejection reason",
  "custom_requirement_evidence": {
    "key": {
      "value": "value",
      "status": "submitted",
      "reason": "Leitura confirmada no local."
    }
  },
  "submitted_at": "2026-11-19T09:30:00Z",
  "applicant_name": "Ana Matsinhe",
  "reviewed_at": "2026-11-19T09:30:00Z",
  "requirements": {
    "currently_due": [
      "currently due"
    ],
    "eventually_due": [
      "eventually due"
    ],
    "past_due": [
      "past due"
    ],
    "pending_verification": [
      "pending verification"
    ],
    "errors": [
      {
        "requirement": "requirement",
        "code": "information_requested",
        "reason": "Leitura confirmada no local."
      }
    ]
  },
  "verification_requirements": [
    "verification requirement"
  ],
  "capabilities": {
    "configure": "inactive",
    "customers": "inactive",
    "meters": "inactive",
    "draft_billing": "inactive",
    "invoices": "inactive",
    "payments": "inactive",
    "messages": "inactive",
    "public_profile": "inactive",
    "custom_domain": "inactive",
    "live_api": "inactive",
    "sandbox": "inactive",
    "billing": "inactive",
    "field_operations": "inactive",
    "states": {
      "key": "inactive"
    },
    "reasons": {
      "key": {
        "code": "requirements_due",
        "requirements": [
          "requirement"
        ]
      }
    }
  },
  "documents": [
    {
      "id": "onb_2trMqh7CG1RYcPnI4f34YJd6q9z",
      "type": "incorporation",
      "file_name": "Ana Matsinhe",
      "content_type": "content type",
      "size_bytes": 1,
      "status": "pending",
      "rejection_reason": "rejection reason"
    }
  ],
  "current_terms_version": "current terms version",
  "history": [
    {
      "actor": "actor",
      "action": "action",
      "detail": "detail",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ]
}

List uploaded onboarding documents

Logs

GET /onboarding/documents

Returns, under data, every document uploaded for the tenant's onboarding application with its type, file name, content type, size and review status. The file contents are not included; use the file download operation for that. Requires the business:onboarding:read permission.

Returns

200 Documents

Show attributes
dataarray of OnboardingDocument · optional
Show child attributes
idstring · optional
typestring · optional

one of incorporation, tax_certificate, concession_licence, representative_id

file_namestring · optional
content_typestring · optional
size_bytesinteger · optional
statusstring · optional

one of pending, accepted, rejected

rejection_reasonstring · optional

Permissions business:onboarding:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/onboarding/documents" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "onb_2trMqh7CG1RYcPnI4f34YJd6q9z",
      "type": "incorporation",
      "file_name": "Ana Matsinhe",
      "content_type": "content type",
      "size_bytes": 1,
      "status": "pending",
      "rejection_reason": "rejection reason"
    }
  ]
}

Upload a document

Logs

POST /onboarding/documents

Upload a document (PDF, JPEG or PNG, up to 10 MiB)

Accepts a multipart form with a type field (incorporation, tax_certificate, concession_licence or representative_id) and a file field, and stores the document in pending status with 201. The file type is detected from its content; anything other than PDF, JPEG or PNG returns 415, and a file over 10 MiB returns 413. Returns 409 when the application is not editable (not_started, in_progress or action_required).

Returns

201 Stored document

Show attributes
idstring · optional
typestring · optional

one of incorporation, tax_certificate, concession_licence, representative_id

file_namestring · optional
content_typestring · optional
size_bytesinteger · optional
statusstring · optional

one of pending, accepted, rejected

rejection_reasonstring · optional

Errors 400 · 413 · 415

Permissions business:onboarding:write · Roles: admin, owner

curl -X POST "$BUSINESS_API/onboarding/documents" \
  -H "Authorization: Bearer sk_test_..."
Response 201
{
  "id": "onb_2trMqh7CG1RYcPnI4f34YJd6q9z",
  "type": "incorporation",
  "file_name": "Ana Matsinhe",
  "content_type": "content type",
  "size_bytes": 1,
  "status": "pending",
  "rejection_reason": "rejection reason"
}

Get document metadata

Logs

GET /onboarding/documents/{id}

Returns the document's type, file name, content type, size and review status without its contents. Returns 404 when the document does not exist in the caller's tenant. Requires the business:onboarding:read permission.

Parameters

idstring · path · required

Resource identifier

Returns

200 Document

Show attributes
idstring · optional
typestring · optional

one of incorporation, tax_certificate, concession_licence, representative_id

file_namestring · optional
content_typestring · optional
size_bytesinteger · optional
statusstring · optional

one of pending, accepted, rejected

rejection_reasonstring · optional

Permissions business:onboarding:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/onboarding/documents/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "onb_2trMqh7CG1RYcPnI4f34YJd6q9z",
  "type": "incorporation",
  "file_name": "Ana Matsinhe",
  "content_type": "content type",
  "size_bytes": 1,
  "status": "pending",
  "rejection_reason": "rejection reason"
}

Delete a document while the application is editable

Logs

DELETE /onboarding/documents/{id}

Removes the document record and its stored file and returns 204. Returns 409 when the application is no longer editable (for example once it has been submitted), and 404 when the document does not exist. Requires the business:onboarding:write permission.

Parameters

idstring · path · required

Resource identifier

Returns

204 Deleted

Permissions business:onboarding:write · Roles: admin, owner

curl -X DELETE "$BUSINESS_API/onboarding/documents/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Deleted

Download the stored document

Logs

GET /onboarding/documents/{id}/file

Streams the stored file as an attachment with its original file name and the content type detected at upload. Returns 404 when the document or its stored file is missing. Requires the business:onboarding:read permission.

Parameters

idstring · path · required

Resource identifier

Returns

200 File bytes

Permissions business:onboarding:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/onboarding/documents/{id}/file" \
  -H "Authorization: Bearer sk_test_..."
Response 200

File bytes

The handover summary of a utility the platform set up

Logs

GET /onboarding/handover

Returns, to the invited owner only, what the platform completed (step IDs, who and when) and the outstanding real-account steps, before and after acceptance. Requires business:onboarding:read; other principals get 404.

Returns

200 Handover summary

Show 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

Errors 401 · 403 · 404

curl -X GET "$BUSINESS_API/onboarding/handover" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "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"
  ]
}

Accept the handover of a utility the platform set up

Logs

POST /onboarding/handover/accept

The invited owner accepts the summary: the utility becomes owner managed, the event is audited with the operator's ID and name, platform-completed steps are carried into the owner's checklist with their attribution, and the operator's setup access ends. The owner's existing session then reaches every business route without signing in again. Only the owner can call it, with business:onboarding:write. Repeating it returns the summary.

Returns

200 Accepted handover summary

Show 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

Errors 401 · 403 · 404 · 409

curl -X POST "$BUSINESS_API/onboarding/handover/accept" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "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"
  ]
}