​
The onboarding flow

The Web Flow onboarding approach is the default that is applicable for most usecases as it does mitigate the need for you to provide all data we need while also providing a transparent and secure user experience.

Onboarding a new Company and user works in the following steps:

1

Create a Company

Create a Company. In this step you can provide as many of the data fields as possible - but you don’t have to.

2

Start User onboarding

Using the new Company you can start onboarding the first User. To do this, Create a User Invite using the User Invites endpoint. The result of this operation is a URL on paywise that is used to complete the Onboarding process.

3

Redirect the User to the Onboarding URL

The user will be prompted for their personal data and can set a personal password for their paywise Account. Additionally, the first user that is onboarded to a new Company will be prompted to review and add any missing data on their company

4

Handle Onboarding Result

Once the user successfully completes providing their data, they will be redirected to a success_url you provided in Step 2. Now the onboarding of the company as a paywise client is considered complete.

You also need to handle user cancellation and / or error cases appropriately.

5

Add additional Users (optional)

Repeating steps 2 - 4 you can onboard additional users to the company if required.

6

Start handing over Claims

The client is onboarded successfully and you can start handing over data using the Case Management API

All Data in the Case Management API has to be managed by a user that is allowed to access this information. As such, you must provide information on the user performing the current request. To do so, add a custom Header X-User-Id to every request to the Case Management API alongside your Partner Token as the Authorization Header. The X-User-Id must contain the identifier of one of the users you created in the previous steps.

Please Note that when making requests to the Case Management API, both the user and the company must be fully onboarded, i.e. the data_submission_completed flag on the company must be set to true and the email_verified flag must be set for the user.

​
Error Handling

To provide your users with a smooth user experience it is important to be able to handle the most common error and edge cases:

​
Redirects to the Failure URL

The most common case to handle will be the user being redirected to the failure_url during onboarding. This might be due to several different reasons:

  • Expired User Invite: If the user fails to open the invite URL before the invite’s expiry, they will be immediately redirected to the failure_url
  • Manual Cancellation: If the user selects to cancel the onboarding process, they will be redirected to the failure_url. In this case, you’ll have to create a new User Invite to restart the onboarding process.
  • Duplicate Processing: If the invite was already processed, regardless of the outcome Please make sure to handle these cases accordingly.
    You can check the status of the invite via the Get User Invite endpoint to distinguish these cases.

​
Email Duplications

In rare cases, it might happen that you try to onboard a user that was already created, either through the API or by regular registration. In this case, the User API will respond with a 400 status code and you can prompt the user to choose a different email

If you want the existing account to be associated with the company you created, please contact our support

API-Only OnboardingList Companies