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

# Create user

> Create a User. Only available in Instant Onboarding Mode

<Info>Note that this endpoint requires the permission **API\_ONLY\_ONBOARDING** on your API Key</Info>

<Info>This endpoint will return a 400 Status Code in case the email address provided is already in use</Info>

<Warning>
  Since September 02, 2026 the `email` field is validated for syntax. A malformed address is
  rejected with a 400 Status Code and the field-level error
  `{"email": ["Invalid email address. Please provide a valid address."]}`, and no user, membership,
  notification channel or invitation is created.

  Addresses longer than 128 characters are rejected the same way. The address is copied into
  several columns during onboarding, the narrowest of which hold 128 characters; a longer address
  previously created a user that could not be completed.

  Before this change the endpoint accepted any string. A malformed address was stored, the
  invitation email silently failed to deliver, and every later claim submitted for that company
  failed. If your integration forwards addresses typed by end users, expect a 400 where you
  previously received a 201.
</Warning>


## OpenAPI

````yaml post /partner/v1/users/
openapi: 3.0.3
info:
  title: paywise Partner API
  version: v1
  description: |

    Use our API to create and manage companies & users.

    Please refer to the [official docs][ref1] for more!

    [ref1]: https://docs.paywise.de/api-docs/partner-api/introduction
servers:
  - url: https://api.paywise.de
    description: Production environment
security: []
externalDocs:
  url: https://docs.paywise.de/api-docs/partner-api/
paths:
  /partner/v1/users/:
    post:
      tags:
        - users
      summary: Create user
      description: Create a User. Only available in Instant Onboarding Mode
      operationId: create-user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSerlializerRequest'
            examples:
              CreateUserRequestSample:
                value:
                  email: max@mustermann.com
                  first_name: Max
                  last_name: Mustermann
                  company: 6196ba03-83f2-46ea-83e1-a087bd0c5acc
                  skip_email_verification: true
                  notification_channels:
                    - channel_type: EMAIL
                      value: max@mustermann.com
                      notification_types:
                        - REQUESTS_TO_CLIENT
                        - STATUS_UPDATE
                        - STATEMENTS
                summary: Create User Request Sample
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UserSerlializerRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UserSerlializerRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSerlializer'
              examples:
                CreateUserResponseSample:
                  value:
                    href: >-
                      https://api.paywise.de/partner/v1/users/ab5fc850-7bb3-4c33-9741-d1305dfa41d9/
                    id: ab5fc850-7bb3-4c33-9741-d1305dfa41d9
                    email: max@mustermann.com
                    first_name: Max
                    last_name: Mustermann
                    company: 6196ba03-83f2-46ea-83e1-a087bd0c5acc
                    email_verified: true
                    notification_channels:
                      - channel_type: EMAIL
                        value: max@mustermann.com
                        notification_types:
                          - REQUESTS_TO_CLIENT
                          - STATUS_UPDATE
                          - STATEMENTS
                  summary: Create User Response Sample
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
          description: ''
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
      security:
        - tokenAuth: []
components:
  schemas:
    UserSerlializerRequest:
      type: object
      properties:
        id:
          type: string
          minLength: 1
        email:
          type: string
          minLength: 1
          description: E-Mail des Benutzers
        first_name:
          type: string
          minLength: 1
          description: Vorname des Benutzers
        last_name:
          type: string
          minLength: 1
          description: Nachname des Benutzers
        company:
          type: string
          format: uuid
          description: UUID of the company that the user is going to be part of
        notification_channels:
          type: array
          items:
            $ref: '#/components/schemas/NotificationChannelRequest'
          description: Notification settings for the user
        skip_email_verification:
          type: boolean
          writeOnly: true
          default: false
          description: >-
            Use this flag to indicate that you already validated the user's
            email address in advance. This way you can start sending claims
            right away, without waiting for user opt-in
      required:
        - company
        - email
        - first_name
        - last_name
    UserSerlializer:
      type: object
      properties:
        href:
          type: string
          format: uri
          readOnly: true
        id:
          type: string
        email:
          type: string
          description: E-Mail des Benutzers
        first_name:
          type: string
          description: Vorname des Benutzers
        last_name:
          type: string
          description: Nachname des Benutzers
        company:
          type: string
          format: uuid
          description: UUID of the company that the user is going to be part of
        email_verified:
          type: boolean
          readOnly: true
        notification_channels:
          type: array
          items:
            $ref: '#/components/schemas/NotificationChannel'
          description: Notification settings for the user
      required:
        - company
        - email
        - email_verified
        - first_name
        - href
        - last_name
    NotificationChannelRequest:
      type: object
      properties:
        channel_type:
          allOf:
            - $ref: '#/components/schemas/ChannelTypeEnum'
          description: >-
            Type of the communication channel to be used. Currently only
            supports email


            * `EMAIL` - E-Mail
        value:
          type: string
          minLength: 1
          description: Value of the communication channel (e.g. the email Address)
        notification_types:
          type: array
          items:
            $ref: '#/components/schemas/NotificationTypesEnum'
          nullable: true
      required:
        - channel_type
        - value
    NotificationChannel:
      type: object
      properties:
        channel_type:
          allOf:
            - $ref: '#/components/schemas/ChannelTypeEnum'
          description: >-
            Type of the communication channel to be used. Currently only
            supports email


            * `EMAIL` - E-Mail
        value:
          type: string
          description: Value of the communication channel (e.g. the email Address)
        notification_types:
          type: array
          items:
            $ref: '#/components/schemas/NotificationTypesEnum'
          nullable: true
      required:
        - channel_type
        - value
    ChannelTypeEnum:
      enum:
        - EMAIL
      type: string
      description: '* `EMAIL` - E-Mail'
    NotificationTypesEnum:
      enum:
        - STATUS_UPDATE
        - REQUESTS_TO_CLIENT
        - STATEMENTS
        - ADVANCE_REQUESTS
      type: string
      description: >-
        * `STATUS_UPDATE` - Status Updates

        * `REQUESTS_TO_CLIENT` - Rückfragen

        * `STATEMENTS` - Abrechnungen

        * `ADVANCE_REQUESTS` - Vorschussrechnungen (advance invoices, e.g. court
        cost advances). Channels carrying this type receive advance invoices by
        email. When you submit `notification_types` containing `STATEMENTS`
        without `ADVANCE_REQUESTS`, the API adds `ADVANCE_REQUESTS`
        automatically, so integrations written against the previous three-value
        list keep delivering advance invoices unchanged; excluding advance
        invoices from an address is done by the client in the paywise portal. If
        a company has no channel with this type at all, advance invoices fall
        back to its `STATEMENTS` channels.
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer

````