Loan & Debt Finders

Summary

Our loan and debt finders help to identify any outgoing transactions that are related to loan or debt collection payments.

GET v1/loans endpoint - Provides a list of a customer's loan transactions
GET v1/debt-collection endpoint - Provides a list of customer's debt collection transactions

📘
For both of these endpoints transactions with multiple currencies are supported, but the statistics objects is currently only calculated for one currency. The endpoint takes the currency of the first transaction and ignores non-matching currencies in its calculations. A future version of this endpoint will have full multiple currency support.

Retrieve Loan Transactions

This endpoint will return a list of the given customer's loan transactions between the provided X-From date and X-To date headers. An example of a 200 response can be seen below.

{
  "operation_id": "v1_loans_get",
  "data": {
    "transactions": [
      {
        "transaction_id": "fdcc55c6-f347-4abc-8c66-61ff290d8bd4",
        "account_id": "fdcc55c6-f347-4abc-8c66-61ff290d8bd4",
        "transaction_description": "Bud Loan Repayment",
        "provider": "Natwest",
        "date": "2022-03-21T01:00:00+0100",
        "amount": {
          "value": "133.28",
          "currency": "GBP"
        },
        "credit_debit_indicator": "Debit",
        "merchant": {
          "id": "bud",
          "name": "Bud",
          "logo": "https://thisisbud.com/merchants/bud.png",
          "confidence": "0.875"
        }
      }
    ],
    "statistics": {
      "total_debit": {
        "value": "133.28",
        "currency": "GBP"
      }
    }
  },
  "metadata": {
    "results": 1,
    "from": "2022-03-19",
    "to": "2022-04-19"
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/v1/loans \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'X-Customer-Secret: <customer_secret>' \ # Not required for hosted customers
     --header 'X-From: 2023-01-01' \
     --header 'X-To: 2024-01-01' \
     --header 'accept: application/json'

This response will contain a summary of the loan transactions including anaccount_id, transaction description, date, amount and merchant if it can be identified. In addition to this, we will also provide a statistics object that contains information about the total_debit amount.

In the case that no loan transactions can be found you will receive a 204 response with an empty body.

A 401 response would indicate that you are not authorised to make this request, if you believe this to be a mistake or are receiving persistent 500 responses please raise a support request support request.

Retrieve Debt Collection Transactions

This endpoint will return a list of the given customer's loan transactions between the provided X-From date and X-To date headers.. An example of a response can be seen below.

{
  "operation_id": "v1_debt_collection_get",
  "data": {
    "transactions": [
      {
        "transaction_id": "fdcc55c6-f347-4abc-8c66-61ff290d8bd4",
        "account_id": "fdcc55c6-f347-4abc-8c66-61ff290d8bd4",
        "transaction_description": "Bud Debt Collection Payment",
        "provider": "Barclays",
        "date": "2021-04-11T01:00:00+0100",
        "amount": {
          "value": "100.00",
          "currency": "GBP"
        },
        "credit_debit_indicator": "Debit",
        "merchant": {
          "id": "debtcollector",
          "name": "Debt Collector",
          "logo": "https://thisisbud.com/merchants/debtcollector.png",
          "confidence": "0.12345"
        }
      }
    ],
    "statistics": {
      "total_debit": {
        "value": "100.00",
        "currency": "GBP"
      },
      "income_relations": {
        "expense_to_income_ratio": "0.100",
        "total_income": {
          "value": "1000.00",
          "currency": "GBP"
        }
      }
    }
  },
  "metadata": {
    "results": 1,
    "from": "2022-03-19",
    "to": "2022-04-19"
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/v1/debt-collection \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
		 --header 'X-Customer-Secret: <customer_secret>' \ # Not required for hosted customers
     --header 'X-From: 2023-01-01' \
     --header 'X-To: 2024-01-01' \
     --header 'accept: application/json'

This response will contain a summary of the debt collection transactions including anaccount_id, transaction description, date, amount and merchant if it can be identified. In addition to this, we will also provide a statistics object that contains information about the total_debit amount and the expense_to_income_ratio which can be used to calculate how much of a customer's income they're spending on debt collection payments.

In the case that no debt collection transactions can be found you will receive a 204 response with an empty body.

If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.