Onboarding API

Base path: onboarding/v1. A headless flow, independent of the browser/theme login, built for MCP, LLM, and external integrations.

Flow

POST /request-otp → POST /verify-otp → GET /status → GET /account-setup → POST /account-setup

After verify-otp, every call requires the onboarding_token (header X-Onboarding-Token or query param onboarding_token), valid for 1800 seconds — it is not a permanent credential.

Steps

1. POST /request-otp — validates the email, creates the account if it doesn’t exist, generates an OTP.
2. POST /verify-otp — verifies the OTP (or admin password), returns onboarding_token and next_action (if completed, the account is already set up).
3. GET /status — current wizard state.
4. GET /account-setup — full payload: saved values, lookup tables, capabilities.
5. POST /account-setup — saves the configuration, activates SdI/PEPPOL/KSeF/ZUGFeRD based on country.

Good to know

• the flow covers variants for IT/SM (SdI), other EU countries (PEPPOL), and Germany (ZUGFeRD/PEPPOL corridor)
• configurations returned by GET /account-setup only contains saved, coherent values
• this same flow is also exposed as 5 MCP tools (pop_onboarding_*) on the remote MCP server, meant to be driven by an AI assistant instead of calling the routes directly — see onboard-via-ai-assistant
• for GCC countries with no official e-invoicing network (AE, SA, BH, KW, OM, QA), the only available invoicing channel is the native Zoho connector (configurations.connector) — no official SdI/PEPPOL/ KSeF fiscal channel exists for these accounts
• general_store_vat_number validates the format for IT, SM, and 33 other countries; the 422 error message includes a country-specific format example when the value doesn’t match
• activating an integration that doesn’t match the account’s country returns an explicit 422 (e.g. active_sdipop_integration: 1 on a non-IT/SM account, active_peppol_integration: 1 on a non-PEPPOL country, active_ksef_integration: 1 on a country other than PL)