Claims Overview

The Claim

The claim is the outstanding payment owed by another party. You can use it to be the individual incident of non-payment per financial product in an account, or if it works more seamlessly with your other systems, the first date where the account goes past due. For example, if you have instalments, and two of them go past due (imagine two loan payments, spaced out 30 days), then you can either use the due date from the first one as the overall incident of non-payment, or you have the flexibility to keep them both separate. You will want to check what is easiest for you to work with.

Creating

Here we will focus on creating a claim via the API. If you are using the files in order to get up and running, then you can go check out the files section, or contact customer success in order to make sure that setup works properly.

When a new claim needs to be created, then you can use the create_claims API to do so. This endpoint can handle multiple claims in one call, but to keep it simple, we will just use one. The payload looks like:

{
  "claim-1-Id": {
    "amount": 13025,
    "currency": "EUR",
    "portfolioReference": "yourPortfolioReference1",
    "productReference": "yourProductReference",
    "totalFees": 9727,
    "originalDueDate": "2019-05-28",
    "currentDueDate": "2019-06-28",
    "paymentReference": "yourPaymentReference1",
    "accountNumber": "accountNumberReference1",
    "accountReference": "accountReference1",
    "meta": {
        "mySampleScore": "AAA"
    },
    "fees": [
      {
        "name": "Interest",
        "amount": 120
      }
    ],
    "primaryDebtor": {
      "birthday": "1980-06-28",
      "gender": "M",
      "firstName": "John",
      "lastName": "White",
      "middleName": "Benedict",
      "title": "Doctor",
      "companyName": "Acme Brick Co.",
      "debtorReference": "string",
      "contactInformation": {
        "country": "DE",
        "city": "Delbrück",
        "mobileNumber": 495555555555,
        "postalCode": 33129,
        "addressLine1": "Boikweg 24",
        "addressLine2": "c/o Acme",
        "addressLine3": "additional information",
        "landLine": 495555555555,
        "state": "Dortmund",
        "email": "testEmail@example.com"
      }
    }
  }

Let's take a closer look at the payload to become familiar with the details. Note: If you are using the Account API, then this call does not require as much data in order to work.

In our example, we have claim-1-id as the first object. This is the claim's reference ID while it runs through the system. What is critical here to understand is that this needs to be unique. Because a claim is an actual incident of non-payment, you can not reuse it later on.

The next part is that the amountis put into the payload. This is done in cents. It's not required to put fees into the payload, be it the fees property, or listing fees further down. Those fields can be considered optional, and it really comes down to whether you need to display fees separately in your content. You also need to send the currencyused in the claim.

In order to round out our outstanding payment owed by someone, you need to have some data in the primaryDebtor object. What is important to note is that there is some flexibility in what you send, but the rule of thumb is that there needs to be a name (person or company) and some way to reach out to the person (email, mobile, address, etc.) If there is no information on who or how to reach the other side, then receeve will throw an error. There's not much point trying to reach out to an unknown person.

Meta Data

We bring this up in several locations, but it's worth pointing it out each time. You can put your own data structure into the claims in order to use that in the strategy and content. In the example above mySampleScore is placed into the meta object, and I am able to use this to drive part of the strategy.

Meta data can be very helpful in making specific data usable. Be it country or product specific, or any other data that is helpful for agents (if you are using our agent setup).

Updating

You can at any point update details of a particular claim. This might things like the contact information or the potential late fees. You can effectively send the either data set that was in the claim creation if you like and the whole claim is updated.

This can be done via the update_claims endpoint.

About deletion

There is officially no deletion via the API.

ON THIS PAGE