> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywise.de/llms.txt
> Use this file to discover all available pages before exploring further.

# API-Only Onboarding

> Onboarding users via API only

<Warning>
  This page documents a frozen v1 API. It receives only critical correctness or
  security corrections. For new integrations, use the [current API](/api-docs/overview)
  and follow the linked [migration guide](/api-docs/legacy/overview#migration-guides).
</Warning>

### The onboarding flow

In certain usecases it is not possible to guide the user through a web-based onboarding flow. For these use cases, you can use the API-only onboarding flow.
<Info>Your Account will require special permissions for this onboarding flow.</Info>

Onboading a company and its users entails the following steps:

<Steps>
  <Step title="Create a Company">
    Create a [Company](/api-docs/legacy/partner/entities#companies). In this step you MUST provide all input data that is relevant for your company. See the entities page for a description of required information.
    <Tip>To validate that you submitted all relevant information you can check the `data_submission_completed` flag on the company.</Tip>
  </Step>

  <Step title="Create users">
    Using the new [Company](/api-docs/legacy/partner/entities#companies) you can create the first [User](/api-docs/legacy/partner/entities#users). Again, you must provide all relevant data for the user.
    <Info>You have to create both the company as well as at least one user to start creating claim</Info>
  </Step>

  <Step title="Wait for user to confirm their Email">
    All newly created users will be issued an invitation email that serves both as a verification that the user actually owns this email address and as a means for the user to set a password for their new account.
    <Info>See [About Email Verification](/api-docs/legacy/partner/onboarding-api-only#about-email-verification).</Info>
  </Step>

  <Step title="Start handing over Claims">
    <Check>The client is onboarded successfully and you can start handing over data using the [Case Management API](/api-docs/legacy/case-management/)</Check>

    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.
    <Info>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.</Info>
  </Step>
</Steps>

### Notification channels

For `channel_type: "EMAIL"`, `value` must be a syntactically valid email
address of at most 128 characters. This applies to [Create User](/api-docs/legacy/partner/users/create-user),
[Create Company](/api-docs/legacy/partner/companies/create-company), and
[Update Company](/api-docs/legacy/partner/companies/update-company). An invalid
address or a longer value returns `400 Bad Request` before any data is created
or updated. Errors identify the channel's `value`, for example:

```json theme={null}
{
  "notification_channels": [
    {"value": ["Invalid email address. Please provide a valid address."]}
  ]
}
```

Accepted channel values retain their submitted case. Other channel types are
unaffected by this email-specific validation.

For each company or user email channel you supply, omitting
`notification_types`, sending `null`, or sending `[]` enables all default types:
`REQUESTS_TO_CLIENT`, `STATUS_UPDATE`, `STATEMENTS`, and `ADVANCE_REQUESTS`.
For example, this channel subscribes the address to all four:

```json theme={null}
{
  "notification_channels": [
    {"channel_type": "EMAIL", "value": "accounts@example.com"}
  ]
}
```

To select fewer types, provide a nonempty `notification_types` list. The
existing compatibility rule still adds `ADVANCE_REQUESTS` whenever you include
`STATEMENTS`. Use the paywise portal to configure those two independently or
disable a channel's subscriptions; an empty type list sent through the Partner
API now means the default selection.

This applies to company creation, replacement channels in company updates,
and user creation. User channels are associated with the user's specified
company so they can receive that company's notifications. Omitting the entire
`notification_channels` field remains unchanged: user creation generates a
default channel from the login email, company creation generates none, and a
company update preserves its existing channels. On company updates,
`notification_channels: []` still removes the channels.

### About Email Verification

When onboading a user you can decide whether they need to re-verify their email address with paywise. This is intended to further facilitate the onboarding process in cases where you already verified a user's address and want to sign them up immediately to begin handing over claims.
However, even if you choose to skip email verification, users will still receive an email prompting them to set an initial password for their paywise account.

#### 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
<Info>If you want the existing account to be associated with the company you created, please contact our support</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.