Create a Claim
Path
POST /claims Request Body
application/json
object
Contains all the customer data. Multiple customers can be provided.
customerNumber
string
Max length: 40
This is the identifier of the customer. Provided by the client.
segment
string
Max length: 70
This is the segment identifier of the client. If a client has multiple business lines, this field can be used for the separation of business lines.
identificationNumber
string
Max length: 128
This is the social security number of the customer or company registration number, when the customer is a company.
title
string
Max length: 32
This is the title of the customer. It will likely be used in mails or letters.
gender
string
Max length: 20
Enum:
- MALE
- FEMALE
- DIVERSE
This is the gender of the customer.
* `MALE` - The customer's gender is male.
* `FEMALE` - The customer's gender is female.
* `DIVERSE` - The customer's gender is diverse.
* `null` - The customer's gender is unknown.
firstName
string
Max length: 128
This is for the first name(s) of the customer, separated by either dashes or spaces.
lastName
string
Max length: 256
This is for the last name(s) of the customer, separated by either dashes or spaces.
companyName
string
Max length: 256
This is the company name of the customer, separated by either dashes or spaces.
dateOfBirth
string
yyyy-MM-dd
Max length: 10
This is the date of birth of the customer. It is needed for legal checks, eg. is the customer underaged.
type
string
Max length: 20
Enum:
- PRIVATE
- COMPANY
Represents the type of a customer.
* `PRIVATE` - The customer is a private individual.
* `COMPANY` - The customer is a company.
category
string
Max length: 128
This is the identifier of the customer. Provided by the client.
preferredLanguage
string
Max length: 2
This is the language in which the customer wants to be contacted, according to ISO 3166-1 alpha 2.
dateOfDeath
string
yyyy-MM-dd
Max length: 10
This is the date of death of the customer.
array
These are the addresses of the customer and his/her further contact persons.
street
string
Max length: 128
street or adresse line 1. The street could include the house number, but if possible please provide the house number as separate value in the field houseNumber
houseNumber
string
Max length: 10
The street / address line 1
addressLine2
string
Max length: 128
addressLine2, can be used, for example, for an additional address indication
zipCode
string
Max length: 10
The zip code.
city
string
Max length: 40
The city.
countryCode
string
Max length: 2
The country code according to ISO 3166-1 alpha 2.
careOf
string
Max length: 128
An optional contact person.
type
string
Max length: 20
Enum:
- BILLING
- SHIPPING
The type expresses which sort of customer address this is
* `BILLING` - The address where to send the bills to.
* `SHIPPING` - The address where to ship products to.
array
List of contact channels of the customer.
type
string
Enum:
- PHONE
- MOBILE_PHONE
value
string
Max length: 120
the contact information for person or company
array
List of bank accounts of the customer
iban
string
Max length: 32
bic
string
Max length: 32
array
Contains all known contacts needed for the collection process.
firstName
string
Max length: 128
This is for the first name(s) of the contact, separated by either dashes or spaces.
lastName
string
Max length: 256
This is for the last name(s) of the contact, separated by either dashes or spaces.
type
string
Max length: 20
Enum:
- SPOUSE
- GENERAL_PARTNER
- LAWYER
- LEGAL_GUARDIAN
- MANAGING_DIRECTOR
- EMPLOYEE
- INSOLVENCY_ADMINISTRATOR
- GARNISHEE
- BAILIFF
- GUARANTOR
The type represents the relationship between contact and custome.
liable
boolean
Max length: 5
This indicates whether a person is liable or not. In this way, non-liable persons such as lawyers or keepers can also be handed over.
object
An address of a contact or customer.
street
string
Max length: 128
street or adresse line 1. The street could include the house number, but if possible please provide the house number as separate value in the field houseNumber
houseNumber
string
Max length: 10
The street / address line 1
addressLine2
string
Max length: 128
addressLine2, can be used, for example, for an additional address indication
zipCode
string
Max length: 10
The zip code.
city
string
Max length: 40
The city.
countryCode
string
Max length: 2
The country code according to ISO 3166-1 alpha 2.
careOf
string
Max length: 128
An optional contact person.
type
string
Max length: 20
Enum:
- BILLING
- SHIPPING
The type expresses which sort of customer address this is
* `BILLING` - The address where to send the bills to.
* `SHIPPING` - The address where to ship products to.
array
List of contact channeles of the contact.
type
string
Enum:
- PHONE
- MOBILE_PHONE
value
string
Max length: 120
the contact information for person or company
array
List of contracts including invoives as base for the claims
contractNumber
string
Max length: 40
A client-assigned contract number associated with this claim. There may be several claims for the same contract number. If no contract number is available the invoice number or customer number could be used based on your business
description
string
Max length: 256
The description of the contract.
category
string
Max length: 128
This field can be used to group claims at the contract level (from the company's point of view).
startDate
string
yyyy-MM-dd
Max length: 10
The date when the contract has been created.
endDate
string
yyyy-MM-dd
Max length: 10
The date when the contract has been terminated.
array
Contains all the invoices. Multiple invoices can be provided.
invoiceNumber
string
Max length: 40
The invoice number assigned by the client for each invoice.
referenceNumber
string
Max length: 40
Can be used to specify an additional reference number. For example, if the accounting system prints a different document number than the invoice number on the invoice for teh customer.
invoiceDate
string
yyyy-MM-dd
Max length: 10
The invoice date represents the specific date on which the invoice was created or issued and indicates the time on which the claim arose.
remainingAmount
number
Max length: 12
This is the outstanding amount of the principal claim which needs to be collected by the Debt Collection Agency. A positive amount indicates a claim against the debtor. Negative amounts or 0 amounts are not allowed.
originalAmount
number
Max length: 12
This is the original amount of the principal claim. A positive amount indicates a claim against the debtor. Negative amounts or 0 amounts are not allowed.
taxRate
number
Max length: 12
The tax rate that was used.
currency
string
Max length: 3
This reflects all relevant currencies in ISO-4217.
dueDate
string
yyyy-MM-dd
Max length: 10
The original due date of the claim.
placementDate
string
yyyy-MM-dd
Max length: 10
The date when the client sent the claim to the debt collection agency.
object
Costs are occuring debts to pay by the customer.
type
string
Max length: 20
Enum:
- FIXED
- REFERENCE
- ABOVE_REFERENCE
- EURIBOR_1
- EURIBOR_3
WARNING: This values are not the finale one. The type of a interest calculation.
lastCalculationDate
string
yyyy-MM-dd
Max length: 10
The date when the last interest calculation was. This is the date wehere we start to caculate the interest in our system. The interest start date/“Verzugsdatum” is in Germany an import information to compute interest of the claim.
rate
number
Max length: 12
This is the rate for the interests from the client.
dunningDate
string
yyyy-MM-dd
Max length: 10
The date when the first dunning was sent to the debtor.
secondDunningDate
string
yyyy-MM-dd
Max length: 10
The date when the second dunning was sent to the debtor.
claimType
string
Max length: 40
Enum:
- PRINCIPAL_CLAIM
- INTEREST_BEARING_COMPENSATION
Most of the claims are of type 'PRINCIPAL_CLAIM'. There are exceptions, such as claims for damages due to unpaid or returned hardware, in which case the 'INTEREST_BEARING_COMPENSATION' type must be used. Claims for damages due to cancelled subscription fees are not allowed to be entered here, and must be handed over as costs.
legalBase
string
Max length: 40
This is a German specific requirement. Depending on the legalBase ("Ursprungsgeschäftsart") the period of sending a case to court differs. Please discuss possibilities with German collection team. The default value is an empty field.
description
string
Max length: 256
This is a free text field, which can be used to describe the claim in more detail or to provide further information.
disputed
boolean
Max length: 5
This field can be used to mark a claim as disputed by the client. The default value is "false".
array
A list of addtional properties, which belongs to the invoice.
key
string
value
string
array
A list of addtional properties, which belongs to the contract/claim.
key
string
value
string
object
This object provides fields for the industry utilities on the contract level.
energy
string
Max length: 20
the energy type that is the subject of the contract
consumptionStartDate
string
yyyy-MM-dd
Max length: 10
date on which consumption began
consumptionEndDate
string
yyyy-MM-dd
Max length: 10
date on which consumption ended
object
street
string
Max length: 128
street or adresse line 1. The street could include the house number, but if possible please provide the house number as separate value in the field houseNumber
houseNumber
string
Max length: 10
The street / address line 1
zipCode
string
Max length: 10
The zip code.
city
string
Max length: 40
The city.
meterNumber
string
Max length: 50
meter number belonging to the contract
isDisconnected
boolean
Max length: 10
object
Fields that are relevant, if industry PUBLIC_TRANSPORT is used.
object
Information about the identification of the person.
cardType
string
Max length: 40
The card type with which the identification of the customer took place
cardNumber
string
Max length: 20
The card number
cardScanAvailable
boolean
Max length: 10
An information about the availability of a card scan
addressVerification
string
Max length: 12
Enum:
- YES
- NO
- NOT_POSSIBLE
- ERROR
An information about the verification status of the customer's address.
comment
string
Max length: 150
A comment about the card with which the identification of the customer took place
photo
boolean
Max length: 10
An information about the availability of a photo of the customer
estimatedAge
boolean
Max length: 10
An information about whether the customer's age has been estimated
identifierName
string
Max length: 40
The identifier name (usually the name of the ticket inspector)
identifierNumber
string
Max length: 8
The identifier number (usually the number of the ticket inspector)
verifier
string
Max length: 50
The verifier (usually the police department called in to verify the identity of the customer)
policeCase
boolean
Max length: 5
An information about the availability of a card scan
withoutPermanentAddress
boolean
Max length: 5
An information about whether the customer has a permanent address or not
route
string
Max length: 15
The route
travelerClass
string
Max length: 1
The class
tariffZone
string
Max length: 30
The tariff zone
entryStop
string
Max length: 60
The entry stop
exitStop
string
Max length: 60
The exit stop
controllingStop
string
Max length: 60
The controlling stop
controllingTime
string
Max length: 8
The time when the inspection was carried out. Only time after ISO 8601
controllingArea
string
Max length: 1
The controlling point ("Control in the train” or “control on the platform")
trainNumber
string
Max length: 30
The train number
trainStationNumber
string
Max length: 30
Train Station Number/Station: A unique identifier or reference number assigned to the train station
transportCompany
string
Max length: 10
The transport company
transportCompanyIndicator
string
Max length: 3
The transport company indicator
coding
string
Max length: 2
The coding
codingDescription
string
Max length: 30
The coding description
realDamage
number
Max length: 12
The real damage
totalPriceForTheRoute
number
Max length: 12
The total price for the route
paymentTransactionId
string
Max length: 20
The payment transaction number used for a non-cash payment
adminNumber
string
Max length: 20
The administration number or identification of the network
fareChargeIncreaseHandedOut
string
Max length: 12
Enum:
- YES
- NO
- NOT_POSSIBLE
An information about whether a fare charge increase has been handed out to the customer
ticketConfiscated
boolean
Max length: 10
An information about whether a ticket has been confiscated
confiscatedTicketNumber
string
Max length: 30
The number of the ticket that has been confiscated
confiscatedTicketType
string
Max length: 128
The type of the ticket conficated.
commentTicketConfiscated
string
Max length: 256
A comment from the ticket inspector about the confiscation of the ticket
behaviourCustomer
string
Max length: 20
A comment from the ticket inspector about the behaviour of the customer
controllingSituation
string
Max length: 300
A comment from the ticket inspector about the controlling situation
machineMalfunction
string
Max length: 50
A comment about the ticket machine malfunction
airline
string
Max length: 50
The airline
comment
string
Max length: 300
An additional comment field
object
Fields that are relevant, if industry TELECOMMUNICATION is used.
isDisconnected
boolean
Max length: 5
An information about whether the customer has been disconnected or not
temporaryDisconnectionDate
string
yyyy-MM-dd
Max length: 10
The date when the temporary disconnection took place
permanentDisconnectionDate
string
yyyy-MM-dd
Max length: 10
The date when the permanent disconnection took place
disconnectionReason
string
Max length: 256
The reason for the disconnection
contractPhoneNumber
string
Max length: 20
The phone number of the contract
contractDuration
integer
Max length: 20
The duration of the contract in months
remainingContractDuration
integer
Max length: 20
The remaining duration of the contract in months
monthlyBasicChargeGross
number
Max length: 12
The monthly basic charge gross
monthlyBasicChargeNet
number
Max length: 12
The monthly basic charge net
registrationChannel
string
Max length: 40
The registration channel
registrationDate
string
yyyy-MM-dd
Max length: 10
The registration date
contractExtensionDate
string
yyyy-MM-dd
Max length: 10
The contract extension date
brandName
string
Max length: 40
The brand name
array
Contains all additional costs for the client.
currency
string
Max length: 3
This reflects all relevant currencies in ISO-4217.
remainingAmount
number
Max length: 12
This is the outstanding amount of the cost which needs to be collected by the Debt Collection Agency. A positive amount indicates a claim against the debtor. Negative amounts or 0 amounts are not allowed.
originalAmount
number
Max length: 12
This is the original amount of the cost. A positive amount indicates a claim against the debtor. Negative amounts or 0 amounts are not allowed.
taxRate
number
Max length: 12
The tax rate that was used.
date
string
yyyy-MM-dd
Max length: 10
The date when the costs occurred.
description
string
Max length: 256
This is a description of the costs.
invoiceNumber
string
Max length: 40
The invoice number assigned by the customer to the invoice to which the costs are to be allocated. If the costs cannot be allocated to a specific invoice, the field can be left blank (`null`).
type
string
Max length: 20
Enum:
- CHARGEBACK
- REMINDER_FEE
- COMPENSATION
- INTEREST_BEARING_COMPENSATION
- LOAN_FEE
- COSTS_OF_TURNING_OFF
- BLOCKING_FINE
- COURT_COSTS
- LAWYER_FEE
- TITLING_COSTS
- COST_ASSESSMENT_COSTS
- BAILIFF_COSTS
- AGREEMENT_REMUNERATION
- COLLECTION_COSTS
- CASH_EXPENSES
- TICKET_CONTROL_COSTS
- INVESTIGATION_COSTS
- INTEREST_BEARING_REMINDER_FEE
Represents the type of a cost.
array
Contains all interest.
invoiceNumber
string
Max length: 40
The invoice number assigned by the customer to the invoice to which the costs are to be allocated. If the interest cannot be allocated to a specific invoice, the field can be left blank (`null`).
currency
string
Max length: 3
This reflects all relevant currencies in ISO-4217.
originalAmount
number
Max length: 12
This is the original amount of the interest. A positive amount indicates a claim against the debtor. Negative amounts or 0 amounts are not allowed.
remainingAmount
number
Max length: 12
This is the outstanding amount of the interest which needs to be collected by the Debt Collection Agency. A positive amount indicates a claim against the debtor. Negative amounts or 0 amounts are not allowed.
fromDate
string
yyyy-MM-dd
Max length: 10
The date when the interest occurred.
toDate
string
yyyy-MM-dd
Max length: 10
When the interest rate has changed over time, an end date can be communicated here.
capitalized
boolean
Max length: 10
This information is particularly important in the context of loans, especially in Nordic countries, where creditors have the ability to charge interest on claims that are marked as capitalized, commonly known as compound interest.
description
string
Max length: 256
This is a description of the interest.
array
Contains all messages.
messageId
string
The Doc API id of the message. For internal communication only. Not to be set by client.
text
string
Max length: 1024
A message text.
concernId
string
Max length: 64
subject
string
Max length: 1024
replyToMessageId
string
Replying to the message with this ID
array
a list of documents that belongs to an message. It is also possible to create only doyuments with out a message text.
name
string
Max length: 128
Name of the file including the file extension.
category
string
Max length: 20
Enum:
- INVOICE
- CONTRACT
- DUNNING_LETTER
Category of the file.
data
string
Base64 encode data of the file. Must not be set if url is set.
checksum
string
Max length: 128
MD5 checksum to verify the data are correct. is only checked if present.
url
string
Max length: 1024
URL to the file. is only checked if present. Most not be set if data is set.
array
Contains all messages.
messageId
string
The Doc API id of the message. For internal communication only. Not to be set by client.
text
string
Max length: 1024
A message text.
concernId
string
Max length: 64
subject
string
Max length: 1024
replyToMessageId
string
Replying to the message with this ID
array
a list of documents that belongs to an message. It is also possible to create only doyuments with out a message text.
name
string
Max length: 128
Name of the file including the file extension.
category
string
Max length: 20
Enum:
- INVOICE
- CONTRACT
- DUNNING_LETTER
Category of the file.
data
string
Base64 encode data of the file. Must not be set if url is set.
checksum
string
Max length: 128
MD5 checksum to verify the data are correct. is only checked if present.
url
string
Max length: 1024
URL to the file. is only checked if present. Most not be set if data is set.
locked
boolean
Max length: 5
An information about whether an claim is locked or not. In case an claim is locked, the backend system will not start any processes until the claim gets unlocked.
industry
string
Max length: 20
Enum:
- UTILITY
- PUBLIC_TRANSPORT
- TELECOMMUNICATION
If the claim can be assigned to a specific industry, this can be entered in this field. Depending on the selected industry, there are specific fields that are available and must be partially filled.
array
Can be used to transfer payments that have already been made before the handover.
invoiceNumber
string
Max length: 40
The invoice number assigned by the client for each invoice.
paymentNumber
string
Max length: 40
The payment number assigned by the client for each payment. It is optional, but it should be included if possible, as it allows us to ensure that payments sent twice are only processed once.
contractNumber
string
Max length: 40
A client-assigned contract number associated with this payment.
date
string
yyyy-MM-dd
Max length: 10
The date of the payment.
description
string
Max length: 256
This is a description of the payment.
amount
number
Max length: 12
This is a description of the payment.
currency
string
Max length: 3
This reflects all relevant currencies in ISO-4217.
allocateTo
string
Max length: 20
Enum:
- PRINCIPAL_CLAIM
- CLIENT_COSTS
- CLIENT_INTERESTS
The bucket to allocate the payment to.
This is a desired allocation, which we try to follow. In certain cases depending on the legal basis or other restrictions, we might change the allocation accordingly.
array
Can be used to transfer credit waivers that have already been made before the handover.
invoiceNumber
string
Max length: 40
The invoice number assigned by the client for each invoice.
creditWaiverNumber
string
Max length: 40
The credit waiver number assigned by the client for each payment. It is optional, but it should be included if possible, as it allows us to ensure that payments sent twice are only processed once.
contractNumber
string
Max length: 40
A client-assigned contract number associated with this credit waiver.
date
string
yyyy-MM-dd
Max length: 10
The date of the credit waiver.
description
string
Max length: 256
This is a description of the credit waiver.
amount
number
Max length: 12
This is a description of the credit waiver.
currency
string
Max length: 3
This reflects all relevant currencies in ISO-4217.
array
A list of addtional properties, which belongs to the claim.
key
string
value
string
Responses
-
requestIdstringreference id for the request
-
errorIdstringInternal ID for tracing the error throughout systems.timestampstringstatusCodeintegerThis is the error code.messagestringarrayThis are the error messages.messagestringnamestringrefstring
-
errorIdstringInternal ID for tracing the error throughout systems.timestampstringstatusCodeintegerThis is the error code.messagestringarrayThis are the error messages.messagestringnamestringrefstring
Request Example
{
"customer": {
"type": "PRIVATE",
"title": "Ms.",
"gender": "female",
"lastName": "Hilll",
"addresses": [
{
"city": "West Mattiemouth",
"type": "billing",
"street": "640 Carrie Crest",
"zipCode": "56695-0518",
"countryCode": "TZ"
}
],
"firstName": "Bianka",
"dateOfBirth": "1946-01-01",
"customerNumber": "B1140280585"
},
"contracts": [
{
"endDate": "2023-06-23",
"invoices": [
{
"currency": "EUR",
"invoiceDate": "2023-06-23",
"invoiceNumber": "I5408705335",
"originalAmount": 120,
"remainingAmount": 100
}
],
"startDate": "2018-06-23",
"contractNumber": "V8157366331"
}
]
}
Response Example
{
"requestId": "8ec4f2b1-964b-42fd-9b1a-abd9274af9c1"
}