Income Finder

Retrieve Income Transactions V2

The GET v2/income endpoint provides a list of a customer's income-based transactions and predicts whether each income transaction is related to a customer's salary_or_wages. Any credit transaction we detect as income that is not salary or wages is given the type other_incoming, which can include other income sources such as investments or pension income.

📘
Multiple Currency Limitations
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.

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

{
  "operation_id": "v2_income_get",
  "data": {
    "transactions": [
      {
        "transaction_id": "fdcc55c6-f347-4abc-8c66-61ff290d8bd4",
        "account_id": "fdcc55c6-f347-4abc-8c66-61ff290d8bd4",
        "transaction_description": "PayPal* Bud",
        "provider": "Barclays",
        "date": "2021-01-11T01:00:00+0100",
        "amount": {
          "value": "1234.56",
          "currency": "GBP"
        },
        "credit_debit_indicator": "Credit",
        "enrichment": {
          "categories": {
            "l1": [
              {
                "name": "finances",
                "confidence": "0.8057",
                "label": "Finances"
              }
            ],
            "l2": [
              {
                "name": "transfers_in",
                "confidence": "0.7811",
                "label": "Transfers In"
              }
            ],
            "l3": [
              {
                "name": "salary",
                "confidence": "0.6805",
                "label": "Salary"
              }
            ]
          },
          "merchant": {
            "id": "bud",
            "name": "Bud",
            "logo": "https://thisisbud.com/merchants/bud.png",
            "confidence": "0.9501"
          },
          "processor": {
            "id": "paypal",
            "name": "PayPal",
            "logo": "https://thisisbud.com/processors/paypal.png",
            "confidence": "0.9702"
          },
          "income": {
            "type": "salary_or_wages",
            "confidence": "0.9408"
          }
        }
      }
    ],
    "statistics": {
      "average": {
        "monthly": {
          "income": {
            "value": "1234.56",
            "currency": "GBP"
          },
          "regular_income": {
            "value": "1234.56",
            "currency": "GBP"
          }
        }
      }
    }
  },
  "metadata": {
    "from": "2021-01-01",
    "to": "2021-01-31",
    "results": 1
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/v2/income \
     --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 income 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 which contains information about the regularity of your income and what the expected monthly average is.

In the case that no income 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.

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

Retrieve Income Transactions V2

📘Multiple Currency Limitations

📘
Multiple Currency Limitations