> ## 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.
# Retrieve a mandate
> Retrieve a single mandate
## OpenAPI
````yaml get /v1/mandates/{id}/
openapi: 3.0.3
info:
title: paywise Case Management API
version: v1
description: |
Use our Case Management API to perform the debt entire collection process.
Please refer to the [official docs][ref1] for more!
[ref1]: https://docs.paywise.de/api-docs/case-management-api/introduction
servers:
- url: https://api.paywise.de
description: Production environment
security: []
externalDocs:
url: https://docs.paywise.de/api-docs/case-management-api/
paths:
/v1/mandates/{id}/:
get:
tags:
- mandates
summary: Retrieve a mandate
description: Retrieve a single mandate
operationId: get-mandate
parameters:
- in: path
name: id
schema:
type: string
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Mandate'
description: ''
security:
- tokenAuth: []
- tokenAuth: []
components:
schemas:
Mandate:
type: object
properties:
href:
type: string
format: uri
readOnly: true
id:
type: string
reference_number:
type: string
description: >-
Our case file reference number ("Aktenzeichen").
**Note:**
Usually a mandate bears only one reference number. But there are
edge cases where a mandate is assigned multiple reference numbers.
If a new reference number is added to the mandate, this field is
overwritten with the new reference number. This previous reference
number is then added to the array of *further_reference_numbers*.
See field below.
further_reference_numbers:
type: array
items:
type: string
maxLength: 200
description: >-
If a mandate bears multiple reference numbers, the most recent one
is saved in *reference_number* above. All others will be placed
here.
debtor:
$ref: '#/components/schemas/DebtorMinInfo'
legal_stage:
allOf:
- $ref: '#/components/schemas/LegalStageEnum'
readOnly: true
processing_state:
allOf:
- $ref: '#/components/schemas/ProcessingStateEnum'
readOnly: true
payment_state:
allOf:
- $ref: '#/components/schemas/PaymentStateEnum'
readOnly: true
legal_claim_balance:
allOf:
- $ref: '#/components/schemas/LegalClaimBalance'
description: The legal claim balance of the mandate ("Forderungsstand").
claims:
type: array
items:
$ref: '#/components/schemas/ClaimMinInfo'
total_mandate_amount:
$ref: '#/components/schemas/Amount'
status_updates:
type: array
items:
$ref: '#/components/schemas/StatusUpdates'
requests_to_client_summary:
allOf:
- $ref: '#/components/schemas/RequestToClientSummary'
readOnly: true
description: >-
Summary of requests to client (questions from paywise that require
your response).
archived:
type: boolean
readOnly: true
created:
type: string
format: date-time
readOnly: true
required:
- archived
- created
- debtor
- href
- legal_claim_balance
- legal_stage
- payment_state
- processing_state
- requests_to_client_summary
- status_updates
- total_mandate_amount
DebtorMinInfo:
type: object
properties:
name:
type: string
readOnly: true
required:
- name
LegalStageEnum:
enum:
- extrajudicial
- judicial_dunning
- foreclosure
- long_term_monitoring
- ended
type: string
description: |-
* `extrajudicial` - Außergerichtlich
* `judicial_dunning` - Gerichtliches Mahnverfahren
* `foreclosure` - Zwangsvollstreckung
* `long_term_monitoring` - In Langzeitüberwachung
* `ended` - Beendet
ProcessingStateEnum:
enum:
- in_progress
- paused
- canceled_by_client
- canceled_by_service_provider
- ended
type: string
description: |-
* `in_progress` - Laufend
* `paused` - Pausiert
* `canceled_by_client` - Abgebrochen durch Mandant
* `canceled_by_service_provider` - Abgebrochen durch uns
* `ended` - Beendet
PaymentStateEnum:
enum:
- unpaid
- partially_paid
- fully_paid
type: string
description: |-
* `unpaid` - Unbezahlt
* `partially_paid` - Teilweise bezahlt
* `fully_paid` - Voll bezahlt
LegalClaimBalance:
type: object
properties:
balance_of_costs_interest_bearing:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The balance of the interest-bearing costs.
balance_of_costs_interest_free:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The balance of the interest-free costs.
balance_of_interest_on_costs:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The balance of the interest on the costs.
balance_of_interest_on_principal_claim:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The balance of the interest on the principal claim.
balance_of_principal_claim:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The balance of the principal claim.
total_balance:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The current total balance of the legal claim.
legal_claim_of_costs_interest_bearing:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The legal claim of costs interest bearing.
legal_claim_of_costs_interest_free:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The legal claim of interest free costs.
legal_claim_of_interest_on_costs:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The legal claim of interests on costs.
legal_claim_of_interest_on_principal_claim:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The legal claim of interests on principal claim.
legal_claim_of_principal_claim:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The legal claim of principal claim.
total_legal_claim:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The total amount of the legal claim.
payment_on_costs_interest_bearing:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The debtor's payment on interest-bearing costs.
payment_on_costs_interest_free:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The debtor's payment on interest-free costs.
payment_on_interest_on_costs:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The debtor's payment on interests on costs.
payment_on_interest_on_principal_claim:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The debtor's payment on the principal claim's interest.
payment_on_principal_claim:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The debtor's payment on the principal claim.
total_payment:
allOf:
- $ref: '#/components/schemas/Amount'
readOnly: true
description: The total of payments on the legal claim.
updated:
type: string
format: date-time
readOnly: true
required:
- balance_of_costs_interest_bearing
- balance_of_costs_interest_free
- balance_of_interest_on_costs
- balance_of_interest_on_principal_claim
- balance_of_principal_claim
- legal_claim_of_costs_interest_bearing
- legal_claim_of_costs_interest_free
- legal_claim_of_interest_on_costs
- legal_claim_of_interest_on_principal_claim
- legal_claim_of_principal_claim
- payment_on_costs_interest_bearing
- payment_on_costs_interest_free
- payment_on_interest_on_costs
- payment_on_interest_on_principal_claim
- payment_on_principal_claim
- total_balance
- total_legal_claim
- total_payment
- updated
ClaimMinInfo:
type: object
description: |-
Only gives the claim's uuids and href for claims.
For use in MandateSerializer
properties:
href:
type: string
format: uri
readOnly: true
id:
type: string
payments:
type: array
items:
$ref: '#/components/schemas/PaymentMinInfo'
required:
- href
Amount:
type: object
description: Amount
properties:
value:
type: string
format: decimal
pattern: ^-?\d{0,14}(?:\.\d{0,2})?$
nullable: true
description: >-
A string representation of a positive integer or decimal with two
decimal places.
currency:
allOf:
- $ref: '#/components/schemas/CurrencyEnum'
description: |-
The three-character currency code (ISO-4217).
* `EUR` - Euro
* `USD` - US Dollar
StatusUpdates:
type: object
description: |-
Mixin to provide download URLs for status update file attachments.
Reusable across different status update serializers.
properties:
id:
type: string
title:
type: string
readOnly: true
description:
type: string
readOnly: true
nullable: true
title: Text
legal_stage:
allOf:
- $ref: '#/components/schemas/LegalStageEnum'
readOnly: true
processing_state:
allOf:
- $ref: '#/components/schemas/ProcessingStateEnum'
readOnly: true
created:
type: string
format: date-time
readOnly: true
downloads:
type: array
items:
$ref: '#/components/schemas/StatusUpdateDownload'
readOnly: true
description: List of file attachments with metadata and download URLs.
required:
- created
- description
- downloads
- legal_stage
- processing_state
- title
RequestToClientSummary:
type: object
description: |-
Summary of all RequestToClient items for a Mandate.
Used as a nested field in MandateSerializer.
Provides:
- total_count: Total number of requests
- unanswered_count: Number of unanswered requests
- has_pending: Boolean indicating if there are unanswered requests
- items: List of all requests with compact info
properties:
total_count:
type: string
readOnly: true
unanswered_count:
type: string
readOnly: true
has_pending:
type: string
readOnly: true
items:
type: array
items:
$ref: '#/components/schemas/RequestToClientSummaryItem'
readOnly: true
required:
- has_pending
- items
- total_count
- unanswered_count
PaymentMinInfo:
type: object
description: Only gives the payment's ids and href
properties:
href:
type: string
format: uri
readOnly: true
id:
type: string
required:
- href
CurrencyEnum:
enum:
- EUR
- USD
type: string
description: |-
* `EUR` - Euro
* `USD` - US Dollar
StatusUpdateDownload:
type: object
description: |-
Serializer for individual download objects in status updates.
Used for schema generation and documentation.
properties:
id:
type: string
format: uuid
description: Unique UUID identifier of the file attachment
filename:
type: string
description: Original filename of the attachment
mime_type:
type: string
description: MIME type of the file (e.g., application/pdf, image/jpeg)
file_size:
type: integer
nullable: true
description: File size in bytes
download_url:
type: string
format: uri
description: Secure download URL for the file
required:
- download_url
- file_size
- filename
- id
- mime_type
RequestToClientSummaryItem:
type: object
description: |-
Compact serializer for RequestToClient items in the Mandate summary.
Shows essential info without full details.
properties:
id:
type: string
format: uuid
href:
type: string
readOnly: true
title:
type: string
description_short:
type: string
readOnly: true
answered:
type: boolean
allowed_answer_types:
type: string
created:
type: string
format: date-time
answered_at:
type: string
format: date-time
nullable: true
readOnly: true
required:
- allowed_answer_types
- answered
- answered_at
- created
- description_short
- href
- id
- title
securitySchemes:
tokenAuth:
type: http
scheme: bearer
````