API Reference

Endpoint

GET /v1/debt-collection/{debtCollectionRunId}/debtors

Path Parameters

debtCollectionRunId required integer (int64)

Unique ID of the debt collection run

Query Parameters

offset string

Offset from last request

Default: 0

sliceSize integer (int32)

Desired size of data chunk

Default: 10

Responses

Response Body application/json

result array[object] required

List of debtors

debtorId required

Debtor unique id

Example: "2334545"

membershipNr required

Membership number of the debtor

Example: "1568462597"

countryCode

Country code of the debtor

Example: "AT"

country

Country of the debtor

Example: "Austria"

identificationNumber

Identification number of the debtor

Example: "ATU143543"

paymentDetails

Describes the payment data.

accountNumber

Account number of the debtor

Example: "91 1000 0000 0123 4567 89"

bankCode

Bank code of the clients account

Example: "DE"

iban

Iban of the clients account

Example: "DE91 1000 0000 0123 4567 89"

bic

Bic of the clients account

Example: "DEUTDEFFXXX"

bank required

Bank name of the client

Example: "Deutsche Bank"

bankCountryCode

Bank country code of the client

Example: "DE"

accountHolder

The account holder of the bank account

Example: "Sven Hannawald"

contractDetails array[object]

Contract data of the debtor

id integer(int64) required

Id of the contract

Example: 123123213

rateName

Rate name of the contract

Example: "Gold"

startDate string(date) required

Start date of the contract

Example: "1952-05-04"

endDate string(date) required

End date of the contract

Example: "1953-05-04"

createdDate string(date) required

Creation date of the contract

Example: "2022-01-01"

cancelled required

If the contract is cancelled

Example: false

contractPeriod

Describes a recurrence with period and frequency

period required

Represents a period

Allowed values:

DAY MONTH WEEK YEAR ONCE

Example: "MONTH"

frequency integer(int32)

Frequency of the recurrence, eq. for period Month and frequency 2 this claim will appear every second month

Example: 2

extensionPeriod

Describes a recurrence with period and frequency

period required

Represents a period

Allowed values:

DAY MONTH WEEK YEAR ONCE

Example: "MONTH"

frequency integer(int32)

Frequency of the recurrence, eq. for period Month and frequency 2 this claim will appear every second month

Example: 2

cancellationPeriod

Describes a recurrence with period and frequency

period required

Represents a period

Allowed values:

DAY MONTH WEEK YEAR ONCE

Example: "MONTH"

frequency integer(int32)

Frequency of the recurrence, eq. for period Month and frequency 2 this claim will appear every second month

Example: 2

birthdate string(date)

Birth date of the debtor

Example: "1952-05-04"

firstName required

First name of the debtor

Example: "Sven"

lastName required

Last name of the debtor name

Example: "Hannawald"

secondLastName

Second last name of the debtor name

Example: "Shmidt"

sex required

Sex of the debtor

Example: "MALE"

postalCode

Postal code of the debtor

Example: "1180"

city required

City of the debtor

Example: "Vienna"

liablePerson

The LiablePerson is used for members not being responsible themself for payments. The complete element should identify the liable person with its details of address, contact data and bank account information. It includes also country specific elements.

firstName required

First name of liable person

Example: "Sven"

lastName required

Last name of liable person

Example: "Hannawald"

secondLastName

Second last name liable person

Example: "Shmidt"

birthdate string(date)

Birthdate of liable person

Example: "1952-05-04"

sex

Sex of liable person

Example: "MALE"

postalCode

Postal code of liable person

Example: "1180"

city

City of liable person

Example: "Vienna"

countryCode

Country code of liable person

Example: "AT"

contactDetails array[object]

Contact data of liable person

type required

Type of contact data

Allowed values:

`TEL_PRIVATE`	Private phone number
`TEL_PRIVATE_MOBILE`	Private mobile phone number
`TEL_BUSINESS`	Business phone number
`TEL_BUSINESS_MOBILE`	Business mobile phone number
`FAX`	Fax number
`EMAIL`	Email address

Example: "TEL_BUSINESS"

value required

Value of contact data

Example: "s.hannawald@sportaliance.com"

status

Describes the status of the contact data.

type required

Type of contact status

Allowed values:

`NO_EMAIL`	No email provided.
`NOT_YET_USED`	Email is provided, but not yet used to send one.
`VALIDATION_IN_PROGRESS`	Email is provided, but currently under validation.
`VALID`	At least one Email was sent successfully.
`VALID_READ`	At least one Email was sent successfully and read.
`INVALID`	Email is provided, but bounced on delivery as invalid email address. No further emailing will happen.
`WARNING`	Email is provided, but bounced on delivery without a reason. Delivery will be tried again.
`REFUSED`	Email is provided, but bounced on delivery with a reason. Delivery will be tried again.
`REFUSED_FULL`	Email is provided, but bounced on delivery because the postbox is full. Delivery will be tried again.
`REFUSED_VIRUS`	Email is provided, but bounced on delivery because it failed the virus test. Delivery will be tried again.

Example: "VALID"

statusInformation

More details to the overall status

Example: "The mail server for the recipient domain does not accept messages to this address."

identificationNumber

Identification number of liable person

Example: "ATU143543"

paymentDetails

Describes the payment data.

accountNumber

Account number of the debtor

Example: "91 1000 0000 0123 4567 89"

bankCode

Bank code of the clients account

Example: "DE"

iban

Iban of the clients account

Example: "DE91 1000 0000 0123 4567 89"

bic

Bic of the clients account

Example: "DEUTDEFFXXX"

bank required

Bank name of the client

Example: "Deutsche Bank"

bankCountryCode

Bank country code of the client

Example: "DE"

accountHolder

The account holder of the bank account

Example: "Sven Hannawald"

addressLine1

Address first line

Example: "Burgring 22"

addressLine2

Address second line

Example: "1180 Vienna"

addressLine3

Address third line

Example: "Austria"

region

Region of liable person

Example: "Vienna"

addressData

Describes the address in detail, so every country has its own fields filled. Use addressLines for preformatted address.

street

Street of the client

Example: "Burgring"

houseNumber

House number of the client

Example: "23A"

addressStatus

Describes the status of the address.

type required

Type of address status

Allowed values:

`VALID`	Default status of an address.
`INVALID`	The address status is proven as invalid.

Example: "VALID"

statusInformation

More details on the overall status

Example: "Letter could not be delivered"

since string(date)

Current status unchanged since

Example: "2000-01-01"

contactDetails array[object]

Contact numbers of the debtor

type required

Type of contact data

Allowed values:

`TEL_PRIVATE`	Private phone number
`TEL_PRIVATE_MOBILE`	Private mobile phone number
`TEL_BUSINESS`	Business phone number
`TEL_BUSINESS_MOBILE`	Business mobile phone number
`FAX`	Fax number
`EMAIL`	Email address

Example: "TEL_BUSINESS"

value required

Value of contact data

Example: "s.hannawald@sportaliance.com"

status

Describes the status of the contact data.

type required

Type of contact status

Allowed values:

`NO_EMAIL`	No email provided.
`NOT_YET_USED`	Email is provided, but not yet used to send one.
`VALIDATION_IN_PROGRESS`	Email is provided, but currently under validation.
`VALID`	At least one Email was sent successfully.
`VALID_READ`	At least one Email was sent successfully and read.
`INVALID`	Email is provided, but bounced on delivery as invalid email address. No further emailing will happen.
`WARNING`	Email is provided, but bounced on delivery without a reason. Delivery will be tried again.
`REFUSED`	Email is provided, but bounced on delivery with a reason. Delivery will be tried again.
`REFUSED_FULL`	Email is provided, but bounced on delivery because the postbox is full. Delivery will be tried again.
`REFUSED_VIRUS`	Email is provided, but bounced on delivery because it failed the virus test. Delivery will be tried again.

Example: "VALID"

statusInformation

More details to the overall status

Example: "The mail server for the recipient domain does not accept messages to this address."

collectionCases array[object]

Collection case of the debtor

collectionCaseId required

ID identifying this Collection case in UUID format

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

openAmount required

Total amount open of all debts

Example: 1231

debt array[object] required

List of debts the member needs to pay

debtId required

Unique Id for this debt in UUID format

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

debtDate string(date) required

Due date of the debt

Example: "1952-05-04"

contractStartDate string(date)

If contract debt, it is set to the start date of the contract, otherwise due date

Example: "1952-05-04"

amount required

Amount to collect for this debt

Example: 333

currency required

ISO 4217 currency code

Example: "USD"

type required

Type of debt collection

Allowed values:

`PRINCIPAL_CLAIM`	Additional created claim by the studio without further categorization
`SALE`	Sale of products on the cash register
`DEBT_CLAIM`	Claim of a contract, module or anything else not further defined
`FLAT_FEE`	Claim of a flat fee
`DUNNING_FEE`	Dunning claim, from a dunning run or debt collection handover
`BANK_FEE`	Added fee of a bank by chargeback

Example: "SALE"

designation required

Description of debt

recurrence required

Describes a recurrence with period and frequency

period required

Represents a period

Allowed values:

DAY MONTH WEEK YEAR ONCE

Example: "MONTH"

frequency integer(int32)

Frequency of the recurrence, eq. for period Month and frequency 2 this claim will appear every second month

Example: 2

servicePeriodStartDate string(date)

Start date of the rendered service, YYYY-MM-DD format

Example: "1952-05-04"

servicePeriodEndDate string(date)

End date of the rendered service, YYYY-MM-DD format

Example: "1952-05-04"

maturityType

Defines if a claim was changed due to rest maturity

Allowed values:

NORMAL RESIDUAL

Example: "NORMAL"

latestRejectionReason

Latest reason on why the payment was not successful

Allowed values:

`PURCHASE_LIMIT`	Purchase limit
`INVALID_IBAN`	Invalid IBAN
`CLOSED_BANKACCOUNT`	Closed bank account
`FRAUD`	Attempted fraud
`INSOLVENCY`	Insolvency
`DECEASED`	Member deceased
`INCOMPLETE_ADDRESS`	Address incomplete
`INVALID_ADDRESS`	Invalid address
`INVALID_OR_MISSING_INFORMATION`	Information missing / invalid
`CHARGED_BACK`	Claim charged back
`ALREADY_PURCHASED`	Debt claim has already been purchased
`ALREADY_CHARGED_BACK`	Debt claim has already been charged back
`CONTESTED_CONTRACT`	Denied contract
`WITHDRAWN_MANDATE`	Direct debit authorization withdrawn
`INVALID_SEPA_MANDATE`	Invalid SEPA mandate
`IBAN_BLACKLISTED`	IBAN blacklisted
`TERMINATED_CONTRACT`	Studio membership cancelled
`IBAN_NOT_SEPA_DIRECT_DEBIT_CAPABLE`	Bank does not participate in SEPA direct debit
`AMOUNT_EXCEEDS_LIMIT`	Maximum claim amount exceeded
`NON_CONTRACTUAL`	Maximum age of debt claim exceeded
`PURCHASING_SUSPENDED`	Purchasing temporarily suspended
`INSTRUCTED_BY_STUDIO`	Reimbursement by studio
`MISSING_LIABLE_PERSON`	Missing legal representative
`IBAN_INVALID_SINCE_LAST_PAYMENT_RUN`	Invalid IBAN
`ACCOUNT_CLOSED_BEFORE_COLLECTION`	Bank account closed
`DEBT_OVERAGED`	Old claim
`DUNNING_UNSUCCESSFUL`	Dunning process unsuccessful
`AUTOMATIC_CHARGEBACK`	Client wishes no collection
`STUDIO_CLOSED_DOWN`	Reimbursement due to administrative enforced studio closure
`REPEATED_INVALID_SEPA_MANDATE`	SEPA mandate repeatedly invalid
`SETTLEMENT_AGREEMENT`	The client agreed to chargeback every reversal of a direct debit
`INVALID_SEPA_CREDITOR_ID`	Invalid Creditor ID has been provided in SEPA mandate
`INSUFFICIENT_COVERING`	Lack of coverage
`OPPOSITION`	Objection of the account holder
`INVALID_BANK_INFORMATION`	Invalid bank data
`INVALID_MANDATE`	Invalid mandate
`AUTHORIZATION_DECLINED`	Authorization declined
`INVALID_CARD`	Invalid card
`CARD_EXPIRED`	Credit card expired
`REVOKED_BY_CUSTOMER`	Revoked by customer
`UNSUPPORTED_DEBT_CLAIM_TYPE`
`PURCHASESTOP_FRAUD`
`ALREADY_REJECTED`
`CONSUMPTION_CREDIT_CHARGEBACK_DEBT_CLAIM_TYPE`
`MANUALLY_REJECTED`
`MANUALLY_SET_PURCHASESTOP`
`OTHER`	Other reason
`OTHER_NO_FORWARDING_TO_EXTERNAL_COLLECTION_AGENCY`
`UNKNOWN`	Unknown reason

Example: "PURCHASE_LIMIT"

contractId integer(int64)

The field returns the contract_id from which the debt claim was created. It can be used to fetch the contract details using __GET /v1/customers/contracts/by__. In the case of non-contractual debt claims, this field is empty.

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)

Block customer or debt until

Example: "2022-09-20"

extHumanId

Human identifier given by the debt collection agency

extReferenceId

Identifier given by the debt collection agency

addressLine1

Address first line

Example: "Burgring 22"

addressLine2

Address second line

Example: "1180 Vienna"

addressLine3

Address third line

Example: "Austria"

region

Region of the debtor

Example: "Vienna"

addressData

Describes the address in detail, so every country has its own fields filled. Use addressLines for preformatted address.

street

Street of the client

Example: "Burgring"

houseNumber

House number of the client

Example: "23A"

addressStatus

Describes the status of the address.

type required

Type of address status

Allowed values:

`VALID`	Default status of an address.
`INVALID`	The address status is proven as invalid.

Example: "VALID"

statusInformation

More details on the overall status

Example: "Letter could not be delivered"

since string(date)

Current status unchanged since

Example: "2000-01-01"

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)

Block customer or debt until

Example: "2022-09-20"

hasNext required

True if there exists next data slice

Example: true

offset required

Offset for next query

Example: "1234567890"

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"