Regular Payments Finder

Summary

Regular payments finder uses our regularity enrichment to provide two endpoints;

GET v1/regular-transactions - Provides a list of a customer's regular transactions based on their transaction history
GET v2/future-transactions - Provides a list of transactions predicted to occur in the future

Retrieve Regular Transactions

This endpoint will return a list of the given customer's regular transactions. An example of a 200 response can be seen below.

{
  "operation_id": "regular_transactions_get",
  "data": [
    {
      "label": "8a29913437a6d2e72a9576a15593f43d92cfc2eb-0",
      "period": "monthly",
      "score": "0.9892",
      "transactions": [
        {
          "provider": "Lloyds",
          "account_id": "688cb2e1-fca9-4d77-bbd3-604abb3c9d46",
          "transaction_id": "c5a50ce9-5523-47b4-8c08-3cd8e30e34a6",
          "transaction_description": "Foxtons - Rent",
          "date": "2019-06-02T00:00:00+0000",
          "amount": {
            "amount": "1325",
            "currency": "GBP"
          },
          "credit_debit_indicator": "Debit",
          "merchant": {
            "id": "foxtonslimited",
            "name": "FOXTONS LIMITED",
            "logo": "https://assets.thisisbud.com/bud-datasci-images/merchant_logo_placeholder.png"
          }
        },
        {
          "provider": "Lloyds",
          "account_id": "688cb2e1-fca9-4d77-bbd3-604abb3c9d46",
          "transaction_id": "70778a02-ea30-4465-b651-65189fd3c51d",
          "transaction_description": "Foxtons - Rent",
          "date": "2019-07-02T00:00:00+0000",
          "amount": {
            "amount": "1325",
            "currency": "GBP"
          },
          "credit_debit_indicator": "Debit",
          "merchant": {
            "id": "foxtonslimited",
            "name": "FOXTONS LIMITED",
            "logo": "https://assets.thisisbud.com/bud-datasci-images/merchant_logo_placeholder.png"
          }
        }
      ]
    }
  ]
}

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

This response contains a summary of the groups of regular transactions including a label, and period, as well as all transactions within the regular group. Currently, the following periods are supported:

daily
weekly
biweekly
monthly
quarterly
unknown

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

If you receive a 400 response like below, please check the headers you're sending in the request before trying again.

{
  "operation_id": "regular_transactions_get",
  "code_id": "failed_validation",
  "message": "Failed validation",
  "errors": {
    "client_id": "This value should not be blank"
  }
}

In the case that you receive a 500 response please retry your request and if the problem persists please raise a support request.

📘
Please note, Regular Transactions will only contains transaction within the last 12 months.

Retrieve Forecasted Transactions V2

This endpoint will return a list of a customer's forecasted transactions. This endpoint also contains two query parameters; months, which allows you to specify how many months we return the predicted transactions for (the default is 3 months) and change_percentage[subcategory], which can be a positive or negative float number and allows you to predict a customer's rising or falling transaction costs based on inflation/deflation.

{
  "operation_id": "v2_future_transactions_get",
  "data": [
    {
      "transaction_id": "fdcc55c6-f347-4abc-8c66-61ff290d8bd4",
      "account_id": "fdcc55c6-f347-4abc-8c66-61ff290d8bd4",
      "transaction_description": "Bud",
      "label": "8a29913437a6d2e72a9576a15593f43d92cfc2eb-0",
      "period": "monthly",
      "date_time": "2019-07-01T01:00:00Z",
      "amount": {
        "value": "100.00",
        "currency": "GBP"
      },
      "credit_debit_indicator": "credit",
      "confidence": "0.9892",
      "future_transactions": [
        {
          "date": "2022-08-01",
          "amount": {
            "value": "102.00",
            "currency": "GBP"
          }
        },
        {
          "date": "2022-09-01",
          "amount": {
            "value": "104.04",
            "currency": "GBP"
          }
        },
        {
          "date": "2022-10-01",
          "amount": {
            "value": "106.12",
            "currency": "GBP"
          }
        },
        {
          "date": "2022-11-01",
          "amount": {
            "value": "108.24",
            "currency": "GBP"
          }
        }
      ]
    }
  ],
  "metadata": {
    "results": 1,
    "months": 4,
    "change_percentages": [
      {
        "l2": "bills",
        "value": 2
      }
    ]
  }
}

curl --request GET \
     --url 'https://api-sandbox.thisisbud.com/v2/future-transactions?months=3&change_percentage[subcategory]=change_percentage%5Bloans%5D%3D2.0' \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'X-Customer-Secret: <customer_secret>' \ # Not required for hosted customers
     --header 'accept: application/json'

This response will contain a summary of the regular transaction including a label, transaction description, period and amount as well as the predicted future transactions for the regular group. Currently, the following periods are supported:

daily
weekly
biweekly
monthly
quarterly
unknown

In the case that there are no forecasted transactions you will receive a 204 response with an empty body.

If you receive a 400 response, please check the headers you're sending in the request before trying again.

In the case that you receive a 500 response please retry your request and if the problem persists please raise a support request.

📘
Please note, calculations for Forecasted Transactions will only take into consideration transactions that occurred within the last 12 months

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