> ## 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 a debtor > Creates a new debtor on every call; this operation is not idempotent. Store the returned UUID for reuse. List debtors with customer_number and/or email to find existing matches first; neither field is unique and lookup does not prevent concurrent duplicate creates. **Draft documentation — API not yet rolled out.** This endpoint describes the preview contract and may change before release. Sandbox access is provided separately. See [access and limitations](/api-docs/mahnservice-api/introduction). ## OpenAPI ````yaml api-docs/mahnservice-api/openapi.json POST /mahnservice/v1/debtors/ openapi: 3.0.3 info: title: paywise Mahnservice API version: v1 description: >- Public REST API for the paywise Mahnservice (pre-collection dunning), an alternative input path to the bookkeeping integrations (Lexware Office, sevDesk) and the CSV import. Authentication uses a Bearer token (the same token works for the Inkasso API). Each token is bound to a company and a legacy access mode: `test` or `production`. Access mode is a data-isolation lane, not the API environment: modern credentials use `production` in both production and sandbox. Read `/info/`'s `environment` (`production` or `sandbox`) to identify the environment serving your request. Resources: token introspection (`/info/`), debtors (create/list/get), and the invoice lifecycle -- submit (held), upload the invoice PDF (multipart or base64; scanned asynchronously, poll the document `status`), release for dunning, report payments, cancel / write off, and read the dunning state (`dunning_state`, the dunning flow and the sent dunnings with their fees), pause and resume the dunning, and read the dunning-flow configuration (`/dunning-flows/`). Webhooks notify you about `invoice.created`, `invoice.paid`, `invoice.cancelled`, `invoice.written_off`, `dunning.level_advanced` and `dunning.handed_to_collection`. Test-mode invoices are visible everywhere but never dunned, and their events only reach test-mode endpoints. Contract: requests are JSON only (documents may also be multipart); unknown or read-only body fields and unknown query parameters are rejected with `400`; list pages take `limit` (1-100, default 10) and `offset`. Errors are English and machine-readable: every error body is `{detail, code[, errors]}` -- branch on `code` (`validation_error` with per-field `errors`, `not_authenticated`, `permission_denied` -- the token lacks the scope, `subscription_required` -- no active Mahnservice subscription (writes other than payment reporting), `company_locked` -- the account is locked by paywise (every write), `not_found`, `unsupported_media_type`, `request_too_large`, `throttled`, `unexpected_body`, and the documented `409` codes). A repeat submission of an invoice number that was cancelled, written off or archived is a `409` (`invoice_cancelled` / `invoice_written_off` / `invoice_archived`), not a replay. `HEAD` mirrors `GET` and never writes. Every response carries `X-Paywise-Request-Id`, `X-Paywise-Environment` and `Cache-Control: private, no-store`. Token scopes apply: `mahnservice:debtors:read` / `:write` and `mahnservice:invoices:read` / `:write` (a `:write` grant includes `:read`; keys minted with the full `*` grant have everything). Rate limits: 600 requests per minute per key and per company, shared with the Case Management API, plus per-operation windows of 600 reads or 120 writes per minute; a `429` carries `Retry-After`. servers: - url: https://api.paywise.de description: Production environment security: [] tags: - name: Info description: The authenticated credential and its context. - name: Debtors description: Debtors invoices are addressed to. - name: Invoices description: Held invoices, their release, payments and documents. - name: Dunning flows description: Dunning flow configurations referenced by invoices. externalDocs: url: https://docs.paywise.de/api-docs/mahnservice-api/introduction paths: /mahnservice/v1/debtors/: post: tags: - Debtors summary: Create a debtor description: >- Creates a new debtor on every call; this operation is not idempotent. Store the returned UUID for reuse. List debtors with customer_number and/or email to find existing matches first; neither field is unique and lookup does not prevent concurrent duplicate creates. operationId: create-debtor parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/DebtorRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/Debtor' description: '' headers: X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: type: string format: uuid X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string '400': description: Standard error response. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: type: string format: uuid X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string '401': description: Standard error response. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: type: string format: uuid X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string '403': description: Standard error response. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: type: string format: uuid X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string '409': description: Standard error response. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: type: string format: uuid X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string '429': description: Standard error response. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: type: string format: uuid X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string Retry-After: description: Integer seconds to wait before retrying a throttled request. schema: type: integer minimum: 1 '500': description: Standard error response. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: type: string format: uuid X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string security: - tokenAuth: [] components: schemas: DebtorRequest: type: object description: |- A Mahnservice debtor. Create it with a name and an optional email and address; those become the debtor's contact channels for dunning. The access mode and the owning company are taken from the token, never the payload, so a legacy test-mode token can only create test debtors. properties: name: type: string minLength: 1 maxLength: 255 type: allOf: - $ref: '#/components/schemas/TypeEnum' default: company description: >- Whether the debtor is a private person (person) or an organization (company). Defaults to company when omitted during creation. customer_number: type: string nullable: true maxLength: 50 description: >- Your customer number for this debtor. Optional and not unique; debtor creation always creates a new record. Use the debtor list customer_number filter to look up existing records. email: type: string format: email nullable: true minLength: 1 maxLength: 254 description: >- Primary email address used for dunning notices. Omit or set null to create the debtor without an email contact. address: $ref: '#/components/schemas/DebtorAddressRequest' description: >- Postal address for dunning letters. Optional as a whole; when present, street, zip_code and city are all required. required: - name Debtor: type: object description: |- A Mahnservice debtor. Create it with a name and an optional email and address; those become the debtor's contact channels for dunning. The access mode and the owning company are taken from the token, never the payload, so a legacy test-mode token can only create test debtors. properties: id: type: string format: uuid readOnly: true name: type: string maxLength: 255 type: allOf: - $ref: '#/components/schemas/TypeEnum' default: company description: >- Whether the debtor is a private person (person) or an organization (company). Defaults to company when omitted during creation. customer_number: type: string nullable: true maxLength: 50 description: >- Your customer number for this debtor. Optional and not unique; debtor creation always creates a new record. Use the debtor list customer_number filter to look up existing records. email: type: string format: email nullable: true maxLength: 254 description: >- Primary email address used for dunning notices. Null when no primary email is recorded. address: $ref: '#/components/schemas/DebtorAddress' description: >- Postal address for dunning letters. Missing street, postal code and city values are returned as empty strings. access_mode: allOf: - $ref: '#/components/schemas/AccessModeEnum' readOnly: true description: >- Legacy data-isolation mode inherited from the creating token. Modern credentials use production in both production and sandbox; this field does not select the API environment. created: type: string format: date-time readOnly: true updated: type: string format: date-time readOnly: true required: - access_mode - created - id - name - updated Error: type: object properties: detail: type: string description: Short human-readable summary of the error. code: type: string description: Machine-readable error category. errors: type: array items: $ref: '#/components/schemas/ErrorItem' description: Field-level validation errors, when applicable. required: - detail - code additionalProperties: false TypeEnum: enum: - person - company type: string description: |- * `person` - Privatperson * `company` - Unternehmen DebtorAddressRequest: type: object description: The debtor's postal address (the dunning-letter recipient). properties: street: type: string minLength: 1 maxLength: 255 zip_code: type: string minLength: 1 maxLength: 20 city: type: string minLength: 1 maxLength: 100 country: allOf: - $ref: '#/components/schemas/CountryEnum' default: DE description: >- Country of the debtor's postal address as a two-letter ISO 3166-1 code (case-insensitive on input, upper-case in responses). Defaults to DE (Germany) when omitted. required: - city - street - zip_code DebtorAddress: type: object description: The debtor's postal address (the dunning-letter recipient). properties: street: type: string maxLength: 255 zip_code: type: string maxLength: 20 city: type: string maxLength: 100 country: allOf: - $ref: '#/components/schemas/CountryEnum' default: DE description: >- Country of the debtor's postal address as a two-letter ISO 3166-1 code (case-insensitive on input, upper-case in responses). Defaults to DE (Germany) when omitted. required: - city - street - zip_code AccessModeEnum: enum: - test - production type: string description: |- * `test` - Test * `production` - Production ErrorItem: type: object properties: field: type: string nullable: true description: >- Path to the field that caused the error, using dots for objects and brackets for list indexes, for example `claims[0].amount`; null for an error without a field path. code: type: string description: Machine-readable field error code. message: type: string description: Human-readable explanation of the field error. required: - field - code - message additionalProperties: false CountryEnum: enum: - AF - AX - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - KP - MK - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - KR - SS - ES - LK - SD - SR - SJ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - UM - US - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW type: string description: |- * `AF` - AF * `AX` - AX * `AL` - AL * `DZ` - DZ * `AS` - AS * `AD` - AD * `AO` - AO * `AI` - AI * `AQ` - AQ * `AG` - AG * `AR` - AR * `AM` - AM * `AW` - AW * `AU` - AU * `AT` - AT * `AZ` - AZ * `BS` - BS * `BH` - BH * `BD` - BD * `BB` - BB * `BY` - BY * `BE` - BE * `BZ` - BZ * `BJ` - BJ * `BM` - BM * `BT` - BT * `BO` - BO * `BQ` - BQ * `BA` - BA * `BW` - BW * `BV` - BV * `BR` - BR * `IO` - IO * `BN` - BN * `BG` - BG * `BF` - BF * `BI` - BI * `CV` - CV * `KH` - KH * `CM` - CM * `CA` - CA * `KY` - KY * `CF` - CF * `TD` - TD * `CL` - CL * `CN` - CN * `CX` - CX * `CC` - CC * `CO` - CO * `KM` - KM * `CG` - CG * `CD` - CD * `CK` - CK * `CR` - CR * `CI` - CI * `HR` - HR * `CU` - CU * `CW` - CW * `CY` - CY * `CZ` - CZ * `DK` - DK * `DJ` - DJ * `DM` - DM * `DO` - DO * `EC` - EC * `EG` - EG * `SV` - SV * `GQ` - GQ * `ER` - ER * `EE` - EE * `SZ` - SZ * `ET` - ET * `FK` - FK * `FO` - FO * `FJ` - FJ * `FI` - FI * `FR` - FR * `GF` - GF * `PF` - PF * `TF` - TF * `GA` - GA * `GM` - GM * `GE` - GE * `DE` - DE * `GH` - GH * `GI` - GI * `GR` - GR * `GL` - GL * `GD` - GD * `GP` - GP * `GU` - GU * `GT` - GT * `GG` - GG * `GN` - GN * `GW` - GW * `GY` - GY * `HT` - HT * `HM` - HM * `VA` - VA * `HN` - HN * `HK` - HK * `HU` - HU * `IS` - IS * `IN` - IN * `ID` - ID * `IR` - IR * `IQ` - IQ * `IE` - IE * `IM` - IM * `IL` - IL * `IT` - IT * `JM` - JM * `JP` - JP * `JE` - JE * `JO` - JO * `KZ` - KZ * `KE` - KE * `KI` - KI * `KW` - KW * `KG` - KG * `LA` - LA * `LV` - LV * `LB` - LB * `LS` - LS * `LR` - LR * `LY` - LY * `LI` - LI * `LT` - LT * `LU` - LU * `MO` - MO * `MG` - MG * `MW` - MW * `MY` - MY * `MV` - MV * `ML` - ML * `MT` - MT * `MH` - MH * `MQ` - MQ * `MR` - MR * `MU` - MU * `YT` - YT * `MX` - MX * `FM` - FM * `MD` - MD * `MC` - MC * `MN` - MN * `ME` - ME * `MS` - MS * `MA` - MA * `MZ` - MZ * `MM` - MM * `NA` - NA * `NR` - NR * `NP` - NP * `NL` - NL * `NC` - NC * `NZ` - NZ * `NI` - NI * `NE` - NE * `NG` - NG * `NU` - NU * `NF` - NF * `KP` - KP * `MK` - MK * `MP` - MP * `NO` - NO * `OM` - OM * `PK` - PK * `PW` - PW * `PS` - PS * `PA` - PA * `PG` - PG * `PY` - PY * `PE` - PE * `PH` - PH * `PN` - PN * `PL` - PL * `PT` - PT * `PR` - PR * `QA` - QA * `RE` - RE * `RO` - RO * `RU` - RU * `RW` - RW * `BL` - BL * `SH` - SH * `KN` - KN * `LC` - LC * `MF` - MF * `PM` - PM * `VC` - VC * `WS` - WS * `SM` - SM * `ST` - ST * `SA` - SA * `SN` - SN * `RS` - RS * `SC` - SC * `SL` - SL * `SG` - SG * `SX` - SX * `SK` - SK * `SI` - SI * `SB` - SB * `SO` - SO * `ZA` - ZA * `GS` - GS * `KR` - KR * `SS` - SS * `ES` - ES * `LK` - LK * `SD` - SD * `SR` - SR * `SJ` - SJ * `SE` - SE * `CH` - CH * `SY` - SY * `TW` - TW * `TJ` - TJ * `TZ` - TZ * `TH` - TH * `TL` - TL * `TG` - TG * `TK` - TK * `TO` - TO * `TT` - TT * `TN` - TN * `TR` - TR * `TM` - TM * `TC` - TC * `TV` - TV * `UG` - UG * `UA` - UA * `AE` - AE * `GB` - GB * `UM` - UM * `US` - US * `UY` - UY * `UZ` - UZ * `VU` - VU * `VE` - VE * `VN` - VN * `VG` - VG * `VI` - VI * `WF` - WF * `EH` - EH * `YE` - YE * `ZM` - ZM * `ZW` - ZW securitySchemes: tokenAuth: type: http scheme: bearer ````