Onboarding an account

An account is a client of yours that wants to sell invoices. Onboarding collects the signed contract and the KYC information. You do not build any of it. You create an account, create a session and send the end user to the session url.

POST /accounts ──► wait for AWAITING_ONBOARDING ──► POST /accounts/{id}/sessions
                                                              │
                          end user opens session url ◄────────┘
                                   │
                       redirected to your callback
                                   │
                  poll GET /accounts/{id} until ENABLED

These endpoints need a partner key.

1. Create the account

Only the company's organisation number is required. You can also send addresses, a bank account and metadata. If you send bank accounts, exactly one is currently supported.

curl -X POST "$BASE_URL/accounts" \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": {
      "nationalOrgNumber": { "country": "SE", "orgNumber": "5591463327" },
      "addresses": [
        { "labels": ["contact"], "emailAddress": "[email protected]" }
      ],
      "bankAccounts": [
        { "bankAccountType": "IBAN", "bic": "SWEDSESS", "number": "SE35..." }
      ],
      "metadata": { "myCustomerNumber": 8 }
    }
  }'

You get 201 and the account. Calling this again for the same company returns 200 with the existing account. A Swedish organisation number may be written with or without a dash, and is returned without it.

2. Wait until the account is ready

Invoier checks that the company can be onboarded. Poll GET /accounts/{accountId} and look at accountStatus:

Status	Meaning
`CREATED`, `PREPARING`	Being checked. Keep polling.
`AWAITING_ONBOARDING`	Ready. You can create an onboarding session.
`DISABLED`	The company cannot be onboarded.

3. Create an onboarding session

curl -X POST "$BASE_URL/accounts/$ACCOUNT_ID/sessions" \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session": {
      "sessionType": "ACCOUNT_ONBOARDING",
      "parameters": { "locale": "en-US" },
      "callbacks": {
        "onComplete": { "url": "https://example.com/onboarding/done" },
        "onCancel": { "url": "https://example.com/onboarding/cancelled" },
        "onError": { "url": "https://example.com/onboarding/failed?message=$MESSAGE" }
      }
    }
  }'

onComplete, onCancel and onError are required. onProvisioning is optional.
locale is sv-SE (default) or en-US.
An account has at most one onboarding session at a time. Creating it again returns the existing session with 200.
You can only create a session while the account is AWAITING_ONBOARDING. If the account is not ready yet, you get an error telling you to try again.

The session has a sessionStatus and starts as CREATED. You can send the end user to the url right away. In production the session is provisioned when the end user first opens it, so it stays CREATED until then and the first visit takes a few seconds. expiresAt is set when provisioning is done, and is 7 days ahead by default.

Until the end user has opened the url, you can still change the session, for example to pre-fill the KYC form.

4. Send the end user to the session url

Redirect the end user's browser to session.url, or send it in a link. The url is the entry to the hosted flow. The end user signs the contract and answers the KYC questions, and the session is ACTIVE meanwhile.

5. Handle the callback

Callbacks are browser redirects. Invoier does not call your server. When the flow ends, the end user is redirected to the callback url you registered:

Callback	When
`onComplete`	The end user finished the flow.
`onCancel`	The end user cancelled. They can open the session `url` again.
`onError`	Something went wrong.
`onProvisioning`	Optional. Used when the session is opened before it is ready.

In a callback url, a path segment or a query parameter value that is exactly a token is replaced:

Callback	Tokens
`onCancel`	`$LOCALE`, `$URL`
`onComplete`	`$COUNTRY`, `$EXPORTS_URL`, `$LOCALE`, `$ORG_NUMBER`
`onError`	`$LOCALE`, `$MESSAGE`
`onProvisioning`	`$LOCALE`, `$URL`

Do not treat a visit to the callback as proof of anything. It only tells you where to take the end user next. Confirm by polling the account and session.

6. Confirm

After onComplete the session is COMPLETED and the account moves to ONBOARDING while Invoier processes it. When accountStatus is ENABLED, the account can sell invoices.

Other things you can do

Renew KYC with a session of type ACCOUNT_KYC_RENEWAL for an account that is ENABLED or DISABLED.
Delete a session with DELETE /sessions/{sessionId}. Active, ready and canceled sessions need ?force=true and the SESSION.DELETE role.
Update a session with POST /sessions/{sessionId}, for example to change callbacks. Sessions that are completed, expired, failed or deleted cannot be updated.
List with GET /accounts/{accountId}/sessions and GET /sessions.
Disable or delete an account with POST /accounts/{accountId} or DELETE /accounts/{accountId}. Only accounts that are not yet onboarded can be deleted.