> ## 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.

# Get Started

> Your first steps with the paywise Partner API

## About the API

The paywise Partner API is based on REST best practices. Our API tries to provide predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Depending on the endpoint and/or the entity that is managed with this endpoint, some operations may not be available due to procedural and/or legal restrictinos.

You can use the paywise API in test mode, which doesn’t affect your live data. The API key you use to authenticate the request determines whether the request is live mode or test mode. See the Authentication guide

paywise APIs don't support bulk updates. You can work on only one object per request.

## Authentication

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

All API endpoints are authenticated using Bearer tokens.

* There are separate token types for test and production environments. Always start with test keys first.
* Generate a new API Key in your [Account](https://app.paywise.de/)
* Use the `Authorization: Bearer YOUR_TOKEN` in your request header.

```javascript theme={null}
$ curl -X GET https://api.paywise.de/partners/v1/info/ -H 'Authorization: Bearer YOUR_TOKEN'
```

## Postman

To kickstart development you can download the current [API Specification file](https://github.com/paywise-gmbh/developer-resources/blob/main/postman/partner-api/openapi.yaml) from our resources and import it to [Postman](https://www.postman.com/) as a collection.
We also provide an [environment](https://github.com/paywise-gmbh/developer-resources/blob/main/postman/partner-api/environment.json) that you can import alongside the collection to quickly start trying our API.

## Onboarding Approaches

In the context of the partner API we distinguish between two separate approaches to onboarding a new [Company](/api-docs/partner-api/entities#companies) and its [Users](/api-docs/partner-api/entities#users).

<Card title="Understanding the Entities" icon="link" href="/api-docs/partner-api/entities" horizontal="true">
  Make sure to make yourself acquainted with the Entities section before deciding on an onboarding approach.
</Card>

### Onboarding Web 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:

<Steps>
  <Step title="Create a Company">
    Create a [Company](/api-docs/partner-api/entities#companies). In this step you can provide as many of the data fields as possible - but you don't have to.
  </Step>

  <Step title="Start User onboarding">
    Using the new [Company](/api-docs/partner-api/entities#companies) you can start onboarding the first [User](/api-docs/partner-api/entities#users). To do this, Create a User Invite using the [User Invites](/api-docs/partner-api/userinvites/create-user-invite/) endpoint.
    The result of this operation is a URL on paywise that is used to complete the Onboarding process.
  </Step>

  <Step title="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
  </Step>

  <Step title="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.
    <Info>You also need to handle user cancellation and / or error cases appropriately.</Info>
  </Step>

  <Step title="Add additional Users (optional)">
    Repeating steps 2 - 4 you can onboard additional users to the company if required.
  </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/case-management-api/)</Check>
  </Step>
</Steps>

### API-only Onboarding

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>

<Steps>
  <Step title="Create a Company">
    Create a [Company](/api-docs/partner-api/entities#companies). In this step you MUST provide all input data that is relevant for your company.
    <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/partner-api/entities#companies) you can create the first [User](/api-docs/partner-api/entities#users). Again, you must provide all relevant data for the user.
  </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 validation that the user actually owns this email address and as a means for the user to set a password for their new account.
    <Info>Depending on your usecase you can skip this step using the `skip_email_validation` flag.</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/case-management-api/)</Check>
  </Step>
</Steps>

## Next Steps

Once you decided on a high-level onboarding approach, you can start following the detailed guides:

<CardGroup cols={2}>
  <Card title="Onboarding Web Flow" icon="square-1" href="/api-docs/partner-api/onboarding-web-flow">
    Detailed guide to onboarding users via the Onboarding Web Flow
  </Card>

  <Card title="API-only Onboarding" icon="square-2" href="/api-docs/partner-api/onboarding-api-only">
    Detailed guide to onboarding users using the API only
  </Card>
</CardGroup>