API Reference

Endpoint

GET /v1/debt-collection/cases

Query Parameters

debtorId array

Unique ID of the debtor

collectionCaseId array

The case id provided by Magicline. This is returned from the 'Get Debtors' endpoint as 'collectionCaseId'

agencyCollectionCaseId array

The case ID used by the agency. This relates to the 'agencyCollectionCaseId' parameter used in the 'Update debt collection' endpoint.

caseAdjustmentRequestId integer (int64)

The request ID delivered by webhook entityId. It contains the latest changes to a case in the Magicline.

Responses

Response Body application/json

debtorId required

Debtor unique id

Example: "2334545"

agencyCollectionCases array[object] required

List of debt collection cases

agencyCollectionCaseId required

ID the agency has assigned to this case

Example: "agency-id-123"

publicCollectionCaseId

Optional customer facing identifier for this case, if there is one that differs from agencyCollectionCaseId and is used in human correspondence.

Example: "case-john-wayne-1"

collectionCaseIds array[object] required

List of collection case ids which we have created, aggregated for that collection case

Example: ["123e4567-e89b-42d3-a456-556642440000"]

closure

Must be set in case the case has been closed

type required

Closure type

Allowed values:

`POSITIVE`	This should be used, if mostly all or all open debts are paid. A positive closure reverses the dunning level of a customer, if all other debt collection cases are also closed. Closure parameters i.e. write off remaining claims will result into writing of all open claims of this debt collection case.
`NEGATIVE`	This should be used, if none debt is paid or no chance of further collection. A negative closure reverses the dunning level of a customer, if all other debt collection cases are also closed and no claim is open anymore. It will not reverse the dunning level in all other cases. Closure parameters i.e. write off remaining claims will result into writing of all open claims of this debt collection case.
`REVERSAL`	This should be used, if there was already progress on the case and no rejection reason can be taken. It ignores all other closure parameters and will reopen the claims.
`REJECTION`	This should be used, if the agency does not accept the case. The rejectionReason must be set in this case. It ignores all other closure parameters and will reopen the claims.

Example: "POSITIVE"

options array[object]

Additional settings for case closures

key required

Additional option key

Allowed values:

WRITE_OFF_REMAINING_DEBTS Indicates to the studio that all remaining, unpaid debts should be written off. E.g. if a case is closed due to bankruptcy of the debtor the collection agency can use this to indicate that the remaining debts are uncollectible. Allowed option values: 'true', 'false' (defaults to 'false' if this option isn't set)

Example: "WRITE_OFF_REMAINING_DEBTS"

value required

The option value, see the option key description for allowed values.

Example: "value"

date string(date) required

Closure date

Example: "2022-09-20"

rejectionReason

Mandatory if type is REJECTION. This defines why the case was rejected by the agency.

Allowed values:

`CLAIMS_ALREADY_IN_COURT`	A legal dispute is already pending regarding the claim, in which Magicline Studio is not represented by the contract partner's joint attorneys.
`MISSING_COMPENSATION_BLOCKING_DUNNING_PROCESS`	The claim depends on a consideration and prevents the execution of the judicial dunning procedure (BGB 688 para. 2 ZPO).
`NO_INFORMATION_ABOUT_LEGAL_REPRESENTATIVE`	The claims in the file are directed against minors, unless another personally liable person (e.g. the parents) is known to Magicline Studio and can be claimed against.
`NO_COLLECTION_ABROAD_POSSIBLE`	The claim concerns a debtor living abroad, unless the collection of the claim can be made from Germany.
`COLLECTING_FROM_INHERIT_NOT_POSSIBLE`	The claim is directed against an unknown heir who cannot be readily identified by inquiry at the probate court and civil status register.
`CLAIMS_TIME_BARRED_OR_RESIDUAL_DEBT_DISCHARGE_GRANTED`	The claim is no longer enforceable (plea of limitation raised or discharge of residual debt granted).
`REMAINING_CLAIM_BELOW_LIMIT`	The (residual) principal claim does not exceed EUR 10.
`NOTIFICATION_OBLIGATIONS_NOT_POSSIBLE`	The statutory information and notification obligations, in particular from Section 13a RDG, cannot be fulfilled.
`FRAUD`	The obligation was unlawfully entered into by an unknown third party on behalf of the alleged debtor (in particular, deception by a third party as to the identity of the debtor). Evidence within the meaning of this Agreement shall be deemed to have been provided if: (1) real data of third party users have been used to obtain services or (2) the invoice recipient has not become a contractual partner or (3) criminal charges have been filed by Magicline Studio.
`CONFLICT_OF_INTEREST`	There is a conflict of interest that cannot be resolved with the contractual partner or the lawyers to be commissioned by the contractual partner.
`WITHDRAWN_BY_STUDIO`	There are other comprehensible reasons on the part of the Contractual Partner and/or Magicline Studio.
`NO_PROCESSING_AT_ALL`	If the file is withdrawn or cancelled from the collection stage within 14 days after handover without being processed by the contractual partner. The contractual partner shall be released from any obligation to pay remuneration. After 14 days, the file can be withdrawn only for one of the other reasons.
`HARD_NEGATIVES_IN_DEBTOR_REGISTER`	There are already hard negatives in the debtor register and a court order would be unsuccessful.
`POSTAL_DELIVERY_NOT_POSSIBLE`	No postal delivery can be made on the basis of the membership data provided, and an address search is also unsuccessful.
`CLAIM_INCREASE_IMPORTED_SYSTEM`

Example: "CLAIMS_ALREADY_IN_COURT"

closureReason

Optional closure reason.

Example: "Not successful due to mail not successfully delivered"

debts array[object] required

Debts which were transferred to the agency. At least all changed debts must be included, also unchanged debts can be included.

debtId required

Debt id from the Transfer, identifying a debt, in UUID format

Example: "123e4567-e89b-42d3-a456-556642440000"

originalAmount required

Transferred amount to debt collection agency. Cancelled amount + paid amount should not be higher than original amount.

Example: 100

canceledAmount required

Not accepted amount. If the case is closed and writeOffRemainingDebts is set, they will be written off and not opened again.

Example: 0

paidAmount required

Paid amount, the status should always contain the amount which was paid to the debt collection agency. If paidAmount is higher than original amount, the loose rest will still be booked to the debtor.

Example: 100

currency required

ISO 4217 currency of the debt code

Example: "EUR"

block

limitType required

Option to set customer or debt to blocklist

Allowed values:

`DISABLED`	Customer or Debt will be removed from block list
`LIMITED`	Customer or Debt will added to block list until given date
`UNLIMITED`	Customer or Debt will added to block list indefinitely

Example: "LIMITED"

endDate string(date) required

Block customer or debt until

Example: "2022-09-20"

block

limitType required

Option to set customer or debt to blocklist

Allowed values:

`DISABLED`	Customer or Debt will be removed from block list
`LIMITED`	Customer or Debt will added to block list until given date
`UNLIMITED`	Customer or Debt will added to block list indefinitely

Example: "LIMITED"

endDate string(date) required

Block customer or debt until

Example: "2022-09-20"

Validation of the request failed.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

TIMESTAMP BOOLEAN DATE MONTH_DAY TIME TERM TERM_LIST INTEGER DECIMAL STRING MONEY LIMITABLE_CONFIG_PROPERTY I18N_KEY I18N_KEY_LIST PERMISSION_LIST ENUM AVAILABILITY_LIST

reference

Reference to validation error

Example: "parent.child"

Authentication failed. No api-key, wrong api-key or wrong header name.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

reference

Reference to validation error

Example: "parent.child"

Authorization failed. The caller has no privilege to the given resource.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

reference

Reference to validation error

Example: "parent.child"

Entity does not exists.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

reference

Reference to validation error

Example: "parent.child"

Concurrent modification detected. The entity was modified by another request.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

reference

Reference to validation error

Example: "parent.child"

Access denied - rate limit is exceeded.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

reference

Reference to validation error

Example: "parent.child"

Unexpected system error.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

reference

Reference to validation error

Example: "parent.child"