Onboarding

Onboard a company before using enabled ZTL services for it. Onboarding state is scoped to the partner integration: a company associated with another ZTL partner does not complete onboarding for your integration.

Lifecycle

The diagram is supplemental. Implement the lifecycle using this table:

Status	Final	Meaning and action
Created	No	The onboarding has been started, but the user has not yet submitted the onboarding form for signing. Return the user to the existing URL when appropriate.
AwaitingCustomerAction	No	The onboarding form has been submitted, and one or more required signers still need to sign the agreement. Inspect signer-level status and continue polling.
Processing	No	Required signing is complete and ZTL is processing the onboarding. This status is typically short-lived; continue polling.
ManualHandling	No	The onboarding requires manual review by ZTL before it can continue to a final status. Continue polling. In production, this status is available only in Norway.
Accepted	Yes	Onboarding completed successfully. The company can proceed to enabled services.
Rejected	Yes	The onboarding was rejected, cancelled, or expired and cannot continue. A new flow may be started when eligible.

The status response can include Signed, PartiallySigned, or Unsigned for the signing process and Signed or Unsigned per signer. Do not collapse a multi-signer flow into a single “user returned” flag. A signer URL may allow a remaining signer to continue.

Existing-state behavior

Initiation behaves differently according to the partner’s existing state:

Existing state for the organization	Initiation result
No onboarding and no onboarded company	Creates a new onboarding
Onboarding in Created	Returns the existing onboarding ID and URL
Onboarding in AwaitingCustomerAction, Processing, or ManualHandling	Rejects a new initiation while that flow is active
Existing onboarded company	Rejects a new production initiation
Onboarding in Rejected	Allows a new onboarding

In production, only one active onboarding per company and partner can exist. An onboarding left in Created or AwaitingCustomerAction for more than 45 days moves to Rejected. The customer must then restart from the beginning.

Integration flow

1. Call POST /onboarding with country, organization number, and your browser return URL.
2. Store the returned onboarding ID and URL.
3. Send the user to the onboarding URL.
4. Interpret the browser return only as a signal to resume. It can represent completion or cancellation and does not prove the final state.
5. Poll GET /onboarding/{onboardingId}/status. Use the signer detail to guide remaining signers and continue until Accepted or Rejected.
6. If the original ID is unavailable, call GET /onboarding/status with the country and organization number.
7. Continue to consent only after Accepted.

The organization-number lookup also returns Accepted when the company exists but no onboarding record is available.

This is a browser callback and polling model, not server event delivery. See Callbacks.

International payments

International payments are automatically enabled or disabled according to the customer’s KYC answers during onboarding. To enable international payments for an onboarded company later, call POST /onboarding/enable-international-payments and send the customer to the returned form URL.

Cancellation and restart

Call POST /onboarding/{onboardingId}/cancel when the user explicitly cancels an eligible flow, then poll status. Cancellation is irreversible for that onboarding. After it reaches Rejected, initiate a new flow if the customer wants to restart.

Sandbox testing

Country-specific reserved scenarios, integrated test data, and signing instructions are on the single sandbox testing page:

• Norway
• Denmark
• Sweden