Account Overview

What is an Account?

Detailed Account Relationships

Relationship Diagram An Account in receeve is the entire relationship between a particular debtor, the claims open against that particular debtor, the products that they may have, and all of the ledger entries relating to the Account.

Creating an Account

Although it is possible to have accounts created and then data linked via the Claims API, our focus here is on the deeper integration via the Account API.

The simplest account could be created with the following payload:

POST /v1/${clientId}/create_accounts HTTP/1.1
Content-Type: application/json

{
	"ACCOUNT_REFERENCE": {
        "currency": "EUR",
        "meta": {
            "key1": "value1"
        }
    }
}

If we have the data available to us at this moment, we can assign meta, scores, debtors, products, and ledgerEntries directly in the previous endpoint.

POST /v1/${clientI}/create_accounts HTTP/1.1
Content-Type: application/json

{
    "ACCOUNT_REFERENCE_0001": {
        "currency": "EUR",
        "meta": {},
        "scores": [
            {
                "type": "INTERNAL",
                "value": "V1"
            }
        ],
        "debtors": [
            {
                "lastName": "LAST_NAME",
                "firstName": "FIRST_NAME",
                "debtorReference": "EXTERNAL_DEBTOR_REF_0001",
                "contactInformation": {
                    "country": "DE",
                    "email": "debtor@company.com"
                }
            }
        ],
        "products": [
            {
                "productReference": "PRODUCT_REFERENCE"
            }
        ],
        "ledgerEntries": [
            {
                "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_1",
                "invoiceDetails": {
                    "amount": 100000,
                    "dueDate": "2021-08-08"
                },
                "context": {
                    "productReference": "PRODUCT_REFERENCE"
                }
            },
            {
                "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_2",
                "invoiceDetails": {
                    "amount": 100000,
                    "dueDate": "2021-09-08"
                },
                "context": {
                    "productReference": "PRODUCT_REFERENCE"
                }
            },
            {
                "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE_0001_3",
                "invoiceDetails": {
                    "amount": 200000,
                    "dueDate": "2021-10-08"
                },
                "context": {
                    "productReference": "PRODUCT_REFERENCE"
                }
            }
        ]
    }
}

Or we can use these other endpoints to add them to an existing account:

  • update_account_meta
  • add_account_ledger_entries
  • add_account_products (+update)
  • add_account_debtors (+update)
  • set_account_scores

This allows you to be flexible depending upon your setup to either do one large call, or split it up as different events happen in your systems and you have the rest of the data later on.

Retrieving an Account

To retrieve an account we can use the client API with the accountReference:

GET /v1/${clientId}/get_account?accountReference=ACCOUNT_REFERENCE HTTP/1.1

Updating the Account data

TODO

Creating Claims against the Account

In the claim API, you typically send all of the relevant debtor and account information in order to have full access to the data while processing the strategy or generating content.

Using the Account API as a starting point, we can now send a minimal dataset when creating a claim, the system will use the primary Account Debtor, the Currency and the Meta field from the Account for each Claim created. So the claim creation looks much smaller now:

POST /v1/${clientId}/create_claims HTTP/1.1
Content-Type: application/json

{
    "CLAIM_REFERENCE": {
        "amount": 2002,
        "currentDueDate": "2019-02-15",
        "originalDueDate": "2019-09-09",
        "productReference": "PRODUCT_REFERENCE",
        "accountReference": "ACCOUNT_REFERENCE",
        "portfolioReference": "EXTERNAL_PORTFOLIO_REFERENCE",
        "totalFees": 40
    }
}

Retrieve Account Claims

To retrieve the claims from a given accountReference:

GET /v1/${clientId}/get_account_claims?accountReference=ACCOUNT_REFERENCE HTTP/1.1

ON THIS PAGE