Onboard a company

import requests

url = "https://api.paywise.de/partner/v2/companies/"

payload = {
    "name": "Example Manufacturing GmbH",
    "onboarding_mode": "api_only"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "address": {
    "city": "Berlin",
    "country": "DE",
    "postal_code": "10115",
    "street": "Example Avenue 5"
  },
  "case_access": "available",
  "case_submission_readiness": {
    "issues": [],
    "ready": true
  },
  "created_at": "2026-07-18T10:00:00Z",
  "customer_number": "5G0123",
  "default_claim_type": "H11",
  "external_reference": "crm-4711",
  "id": "12000000-0000-4000-8000-000000000001",
  "legal_form": "gmbh",
  "legal_representatives": [
    {
      "name": "Taylor Example",
      "type": "managing_director"
    }
  ],
  "name": "Example Manufacturing GmbH",
  "notification_channels": [
    {
      "notifications": [
        "requests_to_client",
        "status_updates",
        "statements"
      ],
      "type": "email",
      "value": "[email protected]"
    }
  ],
  "onboarding_mode": "api_only",
  "onboarding_status": "confirmation_not_required",
  "payout_bank_account": {
    "account_holder": "Example Manufacturing GmbH",
    "iban": "DE89370400440532013000"
  },
  "phone": "+49301234567",
  "sandbox_origin": "unclassified",
  "tax_treatment": "input_tax_deductible",
  "updated_at": "2026-07-18T10:00:00Z",
  "users": [
    {
      "created_at": "2026-07-18T10:00:00Z",
      "email": "[email protected]",
      "first_name": "Taylor",
      "id": "13000000-0000-4000-8000-000000000001",
      "invite_expires_at": "2026-07-28T10:00:00Z",
      "last_name": "Example",
      "revocation_reason": "",
      "revoked_at": null,
      "revoked_by_token_id": null,
      "role": "admin",
      "sandbox_origin": "unclassified",
      "setup_url": "https://app.paywise.de/account/einladung/14000000-0000-4000-8000-000000000001/",
      "status": "pending_setup",
      "updated_at": "2026-07-18T10:00:00Z"
    }
  ],
  "vat_number": "DE129273398"
}

POST

partner

companies

import requests

url = "https://api.paywise.de/partner/v2/companies/"

payload = {
    "name": "Example Manufacturing GmbH",
    "onboarding_mode": "api_only"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "address": {
    "city": "Berlin",
    "country": "DE",
    "postal_code": "10115",
    "street": "Example Avenue 5"
  },
  "case_access": "available",
  "case_submission_readiness": {
    "issues": [],
    "ready": true
  },
  "created_at": "2026-07-18T10:00:00Z",
  "customer_number": "5G0123",
  "default_claim_type": "H11",
  "external_reference": "crm-4711",
  "id": "12000000-0000-4000-8000-000000000001",
  "legal_form": "gmbh",
  "legal_representatives": [
    {
      "name": "Taylor Example",
      "type": "managing_director"
    }
  ],
  "name": "Example Manufacturing GmbH",
  "notification_channels": [
    {
      "notifications": [
        "requests_to_client",
        "status_updates",
        "statements"
      ],
      "type": "email",
      "value": "[email protected]"
    }
  ],
  "onboarding_mode": "api_only",
  "onboarding_status": "confirmation_not_required",
  "payout_bank_account": {
    "account_holder": "Example Manufacturing GmbH",
    "iban": "DE89370400440532013000"
  },
  "phone": "+49301234567",
  "sandbox_origin": "unclassified",
  "tax_treatment": "input_tax_deductible",
  "updated_at": "2026-07-18T10:00:00Z",
  "users": [
    {
      "created_at": "2026-07-18T10:00:00Z",
      "email": "[email protected]",
      "first_name": "Taylor",
      "id": "13000000-0000-4000-8000-000000000001",
      "invite_expires_at": "2026-07-28T10:00:00Z",
      "last_name": "Example",
      "revocation_reason": "",
      "revoked_at": null,
      "revoked_by_token_id": null,
      "role": "admin",
      "sandbox_origin": "unclassified",
      "setup_url": "https://app.paywise.de/account/einladung/14000000-0000-4000-8000-000000000001/",
      "status": "pending_setup",
      "updated_at": "2026-07-18T10:00:00Z"
    }
  ],
  "vat_number": "DE129273398"
}

Authorizations

Authorization

string

header

required

Partner API Bearer key: Authorization: Bearer <key>. Keys are created only through authorized portal or staff flows.

Headers

Idempotency-Key

string

required

Required client-supplied key scoped to the Partner owner, method, operation and path. An exact retry replays the original response while it is retained, including after credential rotation or replacement. Current permissions are required.

Body

application/json

Explicit create input; the selected mode belongs to the authorization.

name

string

required

Registered or trading name of the company. Changes follow the paywise UI identity lock: after transfer for processing, or once company data is complete and a case has been submitted.

Required string length: 1 - 255

onboarding_mode

enum<string>

required

Required choice of api_only or web_flow for this company. paywise must enable the exact corresponding Partner entitlement; wildcard scopes grant neither. Missing mode returns 400 onboarding_mode_required; an unentitled mode returns 403 onboarding_mode_not_allowed. The selected mode cannot be changed by PATCH (409 onboarding_mode_immutable).

Available options:

api_only,

web_flow

address

object | null

Postal address of the company. Omit or set null to create the company without an address.

Show child attributes

Legal basis on which the partner may share this company's data. The declaration is optional here; once recorded, repeating the same value is allowed but replacing it returns 409 data_sharing_basis_already_declared.

Available options:

not_secret_carrier,

self_authorized

default_claim_type

enum<string> | null

Default contract or transaction type for new principal claims.

H05 - Dienstleistungsvertrag
H43 - Warenlieferung/-en
H22 - Mitgliedsbeitrag
H21 - Miete
H11 - Kaufvertrag
H44 - Werkvertrag/Werklieferungsvertrag
H08 - Handwerkerleistung
H41 - Versicherungsprämie/-beitrag
H16 - Lehrgangs-/Unterrichtskosten
H10 - Hotelkosten
H02 - Ärztliche oder zahnärztliche Leistung
H28 - Schadenersatz aus Vertrag
H26 - Reparaturleistung
H24 - Rechtsanwalts-/Rechtsbeistandshonorar
H06 - Frachtkosten
H18 - Miete für Kraftfahrzeug
H34 - Speditionskosten
H19 - Miete für Wohnraum einschl. Nebenkosten
H42 - Versorgungsleistung - Strom, Wasser, Gas, Wärme-
H17 - Miete für Geschäftsraum einschl. Nebenkosten
H45 - Zeitungs-/Zeitschriftenbezug
H37 - Ungerechtfertigte Bereicherung
H29 - Schadenersatz aus Unfall/Vorfall
H01 - Anzeigen in Zeitungen u.a.
H78 - Tierärztliche Leistung
H14 - Lagerkosten
H77 - Krankentransportkosten
H40 - Vermittlungs-/Maklerprovision
H15 - Leasing/Mietkauf
H23 - Pacht
H04 - Darlehensrückzahlung
H20 - Mietnebenkosten - auch Renovierungskosten-
H79 - Verpflegungskosten
H75 - Reisevertrag
H33 - Schuldanerkenntnis
H39 - Vergleich, außergerichtlicher
H70 - Kindertagesstättenbeitrag
H90 - Wohngeld/Hausgeld für Wohnungseigentümergemeinschaft
H09 - Heimunterbringung
H03 - Bürgschaft
H07 - Geschäftsbesorgung durch Selbständige
H12 - Kontokorrentabrechnung
H13 - Krankenhauskosten-Pflege/Behandlung
H36 - Überziehung des Bankkontos
H61 - Wahlleistungen bei stationärer Behandlung
H76 - Telekommunikationsleistungen

Available options:

H05,

H43,

H22,

H21,

H11,

H44,

H08,

H41,

H16,

H10,

H02,

H28,

H26,

H24,

H06,

H18,

H34,

H19,

H42,

H17,

H45,

H37,

H29,

H01,

H78,

H14,

H77,

H40,

H15,

H23,

H04,

H20,

H79,

H75,

H33,

H39,

H70,

H90,

H09,

H03,

H07,

H12,

H13,

H36,

H61,

H76

external_reference

string | null

Your identifier for this company, unique within your partner organization. A duplicate returns 409 company_exists with the existing company_id. Omit or set null if you do not assign one. Filter by ?external_reference= on the company list.

Required string length: 1 - 120

legal_form

string | null

Permanent public code from GET /legal-forms/, or null when not set. A non-null legal_form is required when legal_representatives is nonempty. On PATCH, omission preserves the current form; it cannot be cleared while retaining representatives. Changes follow the paywise UI identity lock: after transfer for processing, or once company data is complete and a case has been submitted.

legal_representatives

object[]

People or organizations legally representing the company, up to three, with roles matching legal_form. A nonempty array requires a non-null legal_form. They cannot be changed once company data submission is complete, even before the first case submission. Maximum 3 entries; exceeding this limit returns 400 validation_error.

Show child attributes

notification_channels

object[]

Company-level email recipients for operational notifications, up to 10. Omit or send [] if no company-level recipients are supplied yet. Each recipient has its own notification selection.

Maximum array length: 10

Show child attributes

payout_bank_account

object | null

Account to which collected funds are transferred. Omit or set null if no account is provided yet. After the first case submission, changes must use the secured payout-account change process in the paywise UI.

Show child attributes

phone

string | null

Primary telephone number of the company in E.164 format; null clears it.

Required string length: 1 - 50

tax_treatment

enum<string> | null

Company VAT treatment, consistent with the address country. reverse_charge requires vat_number. Changes follow the paywise UI identity lock: after transfer for processing, or once company data is complete and a case has been submitted.

Available options:

input_tax_deductible,

not_input_tax_deductible,

reverse_charge,

third_country_non_taxable

users

object[]

Users to invite to the managed company during creation, up to 10. Omit or send [] to create the company without users. A nonempty array must include at least one entry with role admin; its position in the array does not matter. Each is created as pending_setup and gains access only after accepting the setup invitation. Manage memberships through the company users endpoints after creation. Each inline membership also consumes one of the Partner-wide 60 membership additions per hour; company creation consumes one of 30 company creations per hour. All credentials share these allowances. Only successful non-replay commands count. If either allowance is exceeded, the entire command returns 429 throttled with Retry-After and creates nothing.

Maximum array length: 10

Show child attributes

vat_number

string | null

Company VAT identification number. Required when tax_treatment is reverse_charge. Changes follow the paywise UI identity lock: after transfer for processing, or once company data is complete and a case has been submitted.

Maximum string length: 64

Response

The live 201 can reveal only setup links issued by this command.

case_access

enum<string>

required

Whether the partner may operate the Case Management API for this company.

Available options:

available,

unavailable

case_submission_readiness

object

required

Whether company data is complete enough to submit a case.

Show child attributes

created_at

string<date-time>

required

read-only

Time at which the managed company was created.

customer_number

string

required

read-only

paywise customer number assigned to the managed company.

string<uuid>

required

read-only

Stable identifier for this resource.

name

string

required

Registered or trading name of the company.

Maximum string length: 255

onboarding_mode

enum<string>

required

Selected mode for this Partner-company relationship. Read-only after creation.

Available options:

api_only,

web_flow

onboarding_status

enum<string>

required

Administrator confirmation status: confirmation_not_required for api_only; confirmation_pending for provisional web_flow; confirmed for confirmed web_flow. Poll this field independently of membership setup or email delivery.

Available options:

confirmation_not_required,

confirmation_pending,

confirmed

sandbox_origin

enum<string>

required

Provenance of this record. sandbox_native — created inside the sandbox and therefore a test resource you fully own. production_mirror — a read-only copy of a production record. unclassified — everything else, including every record in production. Determines what may be changed in the sandbox, so it is published rather than left to guesswork.

production_mirror - Production mirror
sandbox_native - Sandbox native
unclassified - Unclassified

Available options:

production_mirror,

sandbox_native,

unclassified

updated_at

string<date-time>

required

read-only

Time at which the managed company was last updated.

users

object[]

required

read-only

Inline memberships created by this command. A freshly issued invitation includes a secret setup_url only in the first live 201 response. Reused memberships, idempotent replay, list and detail omit the URL. Use membership resend to replace a lost setup token and receive a fresh URL once.

Show child attributes

address

object | null

Postal address of the company.

Show child attributes

default_claim_type

enum<string> | null

Default contract or transaction type for new principal claims.

H05 - Dienstleistungsvertrag
H43 - Warenlieferung/-en
H22 - Mitgliedsbeitrag
H21 - Miete
H11 - Kaufvertrag
H44 - Werkvertrag/Werklieferungsvertrag
H08 - Handwerkerleistung
H41 - Versicherungsprämie/-beitrag
H16 - Lehrgangs-/Unterrichtskosten
H10 - Hotelkosten
H02 - Ärztliche oder zahnärztliche Leistung
H28 - Schadenersatz aus Vertrag
H26 - Reparaturleistung
H24 - Rechtsanwalts-/Rechtsbeistandshonorar
H06 - Frachtkosten
H18 - Miete für Kraftfahrzeug
H34 - Speditionskosten
H19 - Miete für Wohnraum einschl. Nebenkosten
H42 - Versorgungsleistung - Strom, Wasser, Gas, Wärme-
H17 - Miete für Geschäftsraum einschl. Nebenkosten
H45 - Zeitungs-/Zeitschriftenbezug
H37 - Ungerechtfertigte Bereicherung
H29 - Schadenersatz aus Unfall/Vorfall
H01 - Anzeigen in Zeitungen u.a.
H78 - Tierärztliche Leistung
H14 - Lagerkosten
H77 - Krankentransportkosten
H40 - Vermittlungs-/Maklerprovision
H15 - Leasing/Mietkauf
H23 - Pacht
H04 - Darlehensrückzahlung
H20 - Mietnebenkosten - auch Renovierungskosten-
H79 - Verpflegungskosten
H75 - Reisevertrag
H33 - Schuldanerkenntnis
H39 - Vergleich, außergerichtlicher
H70 - Kindertagesstättenbeitrag
H90 - Wohngeld/Hausgeld für Wohnungseigentümergemeinschaft
H09 - Heimunterbringung
H03 - Bürgschaft
H07 - Geschäftsbesorgung durch Selbständige
H12 - Kontokorrentabrechnung
H13 - Krankenhauskosten-Pflege/Behandlung
H36 - Überziehung des Bankkontos
H61 - Wahlleistungen bei stationärer Behandlung
H76 - Telekommunikationsleistungen

Available options:

H05,

H43,

H22,

H21,

H11,

H44,

H08,

H41,

H16,

H10,

H02,

H28,

H26,

H24,

H06,

H18,

H34,

H19,

H42,

H17,

H45,

H37,

H29,

H01,

H78,

H14,

H77,

H40,

H15,

H23,

H04,

H20,

H79,

H75,

H33,

H39,

H70,

H90,

H09,

H03,

H07,

H12,

H13,

H36,

H61,

H76

external_reference

string | null

Your own identifier for this company (for example a CRM id). Unique per partner, compared byte-exact after trimming surrounding whitespace (case-sensitive): creating a second company with the same value returns 409 company_exists with the existing company_id. Filter with ?external_reference= on the list endpoint.

Maximum string length: 120

legal_form

string | null

Permanent public code from GET /legal-forms/.

legal_representatives

object[]

People or organizations legally representing the company.

Show child attributes

notification_channels

object[]

Company-level email recipients for operational notifications.

Show child attributes

payout_bank_account

object | null

Account to which collected funds are transferred.

Show child attributes

phone

string | null

Primary telephone number of the company in E.164 format; null clears it.

Maximum string length: 50

tax_treatment

enum<string> | null

Company's input-VAT or reverse-charge treatment.

input_tax_deductible - input_tax_deductible
not_input_tax_deductible - not_input_tax_deductible
reverse_charge - reverse_charge
third_country_non_taxable - third_country_non_taxable

Available options:

input_tax_deductible,

not_input_tax_deductible,

reverse_charge,

third_country_non_taxable

vat_number

string | null

VAT identification number of the company.

Maximum string length: 64

Start here

API essentials

Case Management API

Partner API

Mahnservice API

Integrations

Legacy APIs (v1)

Authorizations

Headers

Body

Response