Create debtor

The reusable debtors of your company.

List, retrieve, create, and PATCH. A supplied owned collection (addresses, bank accounts, communication channels, legal representatives) replaces that collection completely; omitted collections stay unchanged. A case’s debtor is the case’s own snapshot (published as MandateDebtor without an id) and is not a reusable debtor: it is neither listed nor readable here.

POST /v2/debtors/

Create debtor

Python

import requests

url = "https://api.paywise.de/v2/debtors/"

payload = {
    "acting_as": "consumer",
    "person": {
        "first_name": "Alex",
        "last_name": "Example",
        "salutation": "mx"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

201

{
  "acting_as": "consumer",
  "addresses": [
    {
      "city": "<string>",
      "country": "<string>",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "postal_code": "<string>",
      "primary": true,
      "street": "<string>"
    }
  ],
  "bank_accounts": [
    {
      "account_holder": "<string>",
      "bic": "<string>",
      "iban": "<string>",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "communication_channels": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "<string>",
      "value": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "events": [
    {
      "description": "<string>",
      "location": "<string>",
      "occurence": "2023-11-07T05:31:56Z",
      "title": "<string>",
      "type": "<string>",
      "your_reference": "<string>"
    }
  ],
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "legal_form": "<string>",
  "legal_representatives": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "legal_form": "<string>",
      "legal_representatives": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "legal_form": "<string>",
          "organization": {
            "commercial_register": "<string>",
            "commercial_registration_number": "<string>",
            "name": "<string>"
          },
          "person": {
            "birth_date": "2023-12-25",
            "first_name": "<string>",
            "last_name": "<string>",
            "salutation": "mr"
          },
          "role": "managing_director"
        }
      ],
      "organization": {
        "commercial_register": "<string>",
        "commercial_registration_number": "<string>",
        "name": "<string>"
      },
      "person": {
        "birth_date": "2023-12-25",
        "first_name": "<string>",
        "last_name": "<string>",
        "salutation": "mr"
      },
      "role": "managing_director"
    }
  ],
  "metadata": [
    {
      "type": "<string>",
      "value": "<string>"
    }
  ],
  "organization": {
    "commercial_register": "<string>",
    "commercial_registration_number": "<string>",
    "name": "<string>"
  },
  "person": {
    "birth_date": "2023-12-25",
    "first_name": "<string>",
    "last_name": "<string>",
    "salutation": "mr"
  },
  "updated_at": "2023-11-07T05:31:56Z",
  "your_reference": "<string>"
}

Authorizations

caseBearerAuthpartnerBearerAuth

Authorization · string · header · required

Company-bound Case Management API key — the standard credential for this API.

Headers

X-On-Behalf-Of-Company · string<uuid>

Required when a Partner key calls the Case Management API; rejected for direct Case keys. Contains the entitled paywise company UUID.

Idempotency-Key · string · required

Required client-supplied command key scoped to the selected Case company or 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.

Maximum string length: 255

Body

application/json

Consumer debtor

Business debtor

Debtor who incurred the obligation as a consumer: a natural person without organization or legal form. Unknown and read-only request fields are rejected with a validation error instead of being silently ignored.

acting_as · enum<string> · required

The debtor incurred the obligation as a consumer.

Available options: consumer

person · object · required

Natural-person identity of the consumer. Supply first_name and last_name; salutation is optional.

Show child attributes

addresses · object[]

Postal addresses. A debtor can be created without addresses, but at least one complete address is required before an order can be finalized. A non-empty list must have exactly one primary address. Maximum 5 entries.

Maximum array length: 5

Show child attributes

bank_accounts · object[]

Known bank accounts belonging to the debtor. Maximum 10 entries.

Maximum array length: 10

Show child attributes

communication_channels · object[]

Email addresses and telephone numbers for the debtor. Maximum 10 entries.

Maximum array length: 10

Show child attributes

events · object[]

Contextual events supplied when creating the debtor.

Show child attributes

legal_representatives · object[]

People or organizations legally representing the debtor. Maximum 10 entries. Representative nesting is limited to two levels, with at most 10 second-level representatives per first-level representative.

Maximum array length: 10

Show child attributes

metadata · object[]

Metadata supplied when creating the debtor; duplicate types are allowed.

Show child attributes

your_reference · string | null

Your reference for this debtor. Blank is stored as null.

Maximum string length: 255

Response

201

application/json

acting_as · enum<string> · required

Whether the debtor incurred the obligation as a consumer or in a business capacity.

• consumer - consumer
• business - business

Available options: consumer, business

addresses · object[] · required · read-only

Postal addresses associated with the debtor. API submissions are limited to 5 entries.

Show child attributes

bank_accounts · object[] · required · read-only

Known bank accounts belonging to the debtor. API submissions are limited to 10 entries.

Show child attributes

communication_channels · object[] · required · read-only

Email addresses and telephone numbers for the debtor. API submissions are limited to 10 entries.

Show child attributes

created_at · string<date-time> · required · read-only

Time at which the debtor was created.

events · object[] · required · read-only

Stored contextual events associated with this resource.

Show child attributes

id · string<uuid> · required · read-only

Stable identifier of this debtor.

legal_form · string | null · required · read-only

Permanent public legal-form code; look up its label and representation rules with GET /v2/legal-forms/. Null for consumers.

legal_representatives · object[] · required · read-only

People or organizations legally representing the debtor. API submissions are limited to 10 entries.

Show child attributes

metadata · object[] · required · read-only

Stored metadata entries; duplicate types remain separate entries.

Show child attributes

organization · object | null · required

Organization identity for a business debtor.

Show child attributes

person · object | null · required

Natural-person identity for a consumer or sole proprietor.

Show child attributes

updated_at · string<date-time> · required · read-only

Time at which the debtor was last updated.

your_reference · string | null · required · read-only

Your reference for this debtor.