Implementation Guide

Getting Started

To get started you need to use two simple API calls to upload the transactions to nrich, after that you can get the maximum benefit of your transactions:

Upload the transactions
Poll the status of transaction processing
Fetch the enriched transactions, a risk report, ...

1. Upload transactions

POST /uploads

{
  "accounts": [
    {
      "balance_date": "2024-07-02T00:00:00.000Z",
      "balance": 9.99,
      "currency": "EUR",
      "iban": "DE77900948150000002001",
      "bic": "MOCKBANKXXX",
      "owner": "Max Mustermann",
      "transactions": [
        {
          "iban": "DE88500700100175526303",
          "bic": "DEUTDEFFXXX",
          "amount": -9.99,
          "booking_text": "My booking text",
          "creditor_id": "LU96ZZZ0000000000000000058",
          "currency": "EUR",
          "end_to_end_reference": "My end to end reference",
          "mandate_reference": "My mandate reference",
          "name": "PayPal (Europe) S.a.r.l. et Cie., S.C.A.",
          "purpose": "PP.8419.PP . SPOTIFY,Ihr Einkauf bei SPOTIFY",
          "sepa_purpose_code": "My sepa purpose code",
          "booked_at": "2024-07-02T00:00:00.000Z",
          "settled_at": "2024-07-02T00:00:00.000Z"
        }
      ]
    }
  ]
}

Please note that the following mandatory parameters:

account.iban: IBAN of the account.
transaction.iban: IBAN of the counter party.
transaction.amount: Amount of the transaction. Default currency is EUR.
transaction.purpose Purpose text of the transaction.
transaction.booked_at: Booking date of the transaction.

The API returns the following status response if the request was successful:

{
  "id": "9556429e-378f-4c96-a7f0-44af2a9b7b38",
  "status": "QUEUED",
  "created_at": "2024-07-10T07:12:38.362682+00:00",
  "ended_at": null,
  "started_at": null
}

2. Poll status

Use the id from the previous response to query the status of the transaction processing via GET /uploads/{upload-id} . Wait until the status changes to COMPLETED and use the returned access_token for all subsequent API requests.

{
  "id": "9556429e-378f-4c96-a7f0-44af2a9b7b38",
  "status": "COMPLETED",
  "created_at": "2024-07-10T07:12:38.362682+00:00",
  "ended_at": "2024-07-10T07:12:39.039422+00:00",
  "started_at": "2024-07-10T07:12:38.462203+00:00",
  "access_token": "..."
}

That's it!

Now you can use the following endpoints of the API:

GET /rest/transactions: Fetch transactions with categories and payment partners
GET /rest/income-report: Disposable Income Verification
POST /rest/risk-reports and GET /rest/risk-report: Risk Insights
...

3. Example: Fetch transactions

Use GET /rest/transactions to fetch the enriched transactions including categories and payment_partner. Use the access_token from the previous response in the Authorization header.

{
  "transactions": [
    {
      "account_id": "A984794105855541249.1",
      "account_number": "175526303",
      "amount": -9.99,
      "booked": true,
      "booked_at": "2024-07-02T00:00:00.000Z",
      "booking_text": "My booking text",
      "categories": [
        {
          "id": 22,
          "parent_id": null,
          "name": "Leisure"
        },
        {
          "id": 33,
          "parent_id": 22,
          "name": "Music streaming"
        }
      ],
      "created_at": "2024-07-10T10:01:51.323637+00:00",
      "modified_at": "2024-07-10T10:01:53.512615+00:00",
      "payment_partner": {
        "id": "c9944518e86e46409e46a52b0f55dee0",
        "name": "Spotify AB"
      },
      "settled_at": "2024-07-02T00:00:00.000Z",
      "transaction_code": 999,
      "transaction_id": "T984794105855541249.1",
      "type": "Unknown",
      "end_to_end_reference": "My end to end reference",
      "bank_code": "50070010",
      "purpose": "PP.8419.PP . SPOTIFY,Ihr Einkauf bei SPOTIFY",
      "creditor_id": "LU96ZZZ0000000000000000058",
      "iban": "DE88500700100175526303",
      "bic": "DEUTDEFFXXX",
      "mandate_reference": "My mandate reference",
      "currency": "EUR",
      "name": "PayPal (Europe) S.a.r.l. et Cie., S.C.A.",
      "sepa_purpose_code": "My sepa purpose code"
    }
  ],
  "deleted": [],
  "statistics": {},
  "status": {
    "synced_at": "1950-01-01T00:00:00+00:00",
    "succeeded_at": "1950-01-01T00:00:00+00:00"
  }
}