Create Claims Use Case

Create Claims

To create a claim, you will need to send a POST request to the following URL: https://api.receeve-demo.com/v1/import_claims

Be sure to include the Authorization header with the Bearer authentication scheme and the access_token as the credentials. The access_token is provided by the authentication request.

Below is an example:

Let’s assume that you expect a payment from John Doe of 20 euros and 50 cents of fees. You can create a new claim in the system by simply sending the following request:

POST /v1/3d132b18-6b6f-4f7c-b464-6a8ee7ca5235/import_claims HTTP/1.1
Host: api.receeve-demo.com
Content-Type: application/json
Authorization: {{access_token}}

{
  "claim1": {
    "amount": 2000,
    "totalFees": 50,
    "currency": "EUR",
    "currentDueDate": "2019-02-15",
    "originalDueDate": "2018-09-09",
    "primaryDebtor": {
      "lastName": "Doe",
      "firstName": "John",
      "debtorReference": "JOHN_DOE_ID",
      "contactInformation": {
        "country": "DE",
        "email": "john.doe@acme.com",
        "mobileNumber": "+49123456789"
      }
    }
  }
}

Notes:

• The 3d132b18-6b6f-4f7c-b464-6a8ee7ca5235 is the Client Instance ID for your account. This is provided by receeve together with the credentials for the API.
• The currency must be a valid ISO 4217 currency code.
• The amount and the fees (or any monetary value) must be expressed in cents. For example, 20 euros must be expressed as 2000 cents.
• The claim1 key is the claim reference. It can be any string, but it must be unique for each claim.
• The currentDueDate and originalDueDate are required and must be in the format YYYY-MM-DD.
• The originalDueDate is the claim’s original due date in your system. This is the day when it went past due.
• The debtorReference is the debtor’s unique identifier. It can be any string, but it must be unique for each debtor.
• The mobileNumber must be in the international format, including the country code. For example, this would be +49123456789 for Germany.
• The currentDueDate is the claim’s current due date in your system. Use originalDueDate unless you purchased the debt and need this distinction.
• The request can include multiple claims. The response will contain the status of each claim.

The response will be a JSON object with the following structure:

{
  "claim1": {
    "success": true,
    "data": {
      "amount": 2000,
      "totalFees": 50,
      "currency": "EUR",
      "currentDueDate": "2019-02-15",
      "originalDueDate": "2018-09-09",
      "primaryDebtor": {
        "lastName": "Doe",
        "firstName": "John",
        "debtorReference": "JOHN_DOE_ID",
        "contactInformation": {
          "country": "DE",
          "email": "john.doe@acme.com",
          "mobileNumber": "+49123456789"
        }
      }
    },
    "messageIds": ["edd74384-1bc8-4616-ae10-bf1c54adedaf"],
    "messages": ["Successfully imported claim claim1"]
  }
}

Notes

• The messages are human-readable messages that can be used for debugging.
• The messageIds represent the unique identifier for the intention of importing each claim. These can be used to track the side effects within the system.
• The result of the intention of importing each claim is reported back with the success flag. If it returns false, the claim was not imported and will include the details of the error.

FAQ

• How do I get an Access Token? You can get an Access Token using the process outlined in the Authentication Use Case document.
• I see that there is an endpoint called create_claims. How does this differ from the import_claims The shape of the request and the response are basically the same; the only difference is that create_claims only creates the claims. If the claim(s) already exist in the platform,  it will throw an error, and import_claims will attempt to update it if it already exists in the platform. We suggest using import_claims to simplify the flow, but the other endpoint exists if needed.
• Is there a hard limit on the number of claims that I can import at once? Yes, there are hard limits to consider. First, the claims’ total size cannot exceed 200 Kb max (including the metadata). Second, the rate limit is 30 Requests per minute. As described above, the request can include multiple claims, with limits depending on the type of request:
  • Asynchronous request: 30 Claims per request
  • Synchronous request: 5 Claims per request This means that we have a throughput of:
  • 900 Claims/min (async) - 150 Claims/min (sync)
  • 54,000 Claims/hr (async) - 9,000 Claims/hr (sync)

Related Pages

• Account Claims