Implementation Guide

Getting Started

To get started, use three simple API calls to upload transactions to nrich and make full use of your transaction data:

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

1. Upload transactions

{
  "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 parameters are mandatory:

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 transaction processing status 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"
  }
}