Benefits Finder

The Benefits Finder endpoints allow you to retrieve a customer's benefit-based transactions from within their connected accounts, as well as their total income under each benefit type. In this guide you will find how to use both the Benefits Transactions and Benefits Totals endpoints, as well as the list of benefit types that we currently support.

Retrieve Benefits Transactions

The GET v1/benefits endpoint provides a list of a customer's benefit-based transactions found within their connected accounts and transactions.

This endpoint will return a list of the given customer's benefit 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_benefits_get",
  "data": [
    {
      "transaction_id": "fdcc55c6-f347-4abc-8c66-61ff290d8bd4",
      "account_id": "fdcc55c6-f347-4abc-8c66-61ff290d8bd4",
      "transaction_description": "NATWEST DWP DLA GBR",
      "provider": "Natwest",
      "date": "2022-03-21T01:00:00+0100",
      "amount": {
        "amount": "333.28",
        "currency": "GBP"
      },
      "credit_debit_indicator": "Credit",
      "benefit": {
        "type": "disability_living_allowance",
        "display_name": "Disability Living Allowance"
      }
    }
  ],
  "metadata": {
    "from": "2025-01-01",
    "to": "2026-01-01",
    "results": 1
  }
}
curl --request GET \
     --url https://api-sandbox.thisisbud.com/v1/benefits \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'X-From: 2025-01-01' \
     --header 'X-To: 2026-01-01' \
     --header 'accept: application/json'

This response will contain a list of benefit transactions including an account_id, transaction description, date, amount, benefit type and a display_name. The display_name is intended to be in plain English, this is the value that we recommend displaying to a customer.

In the case that no benefit transactions can be found 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. If you continue to receive an error please consult the error responses guide.

Retrieve Benefits Totals

If you don't need the individual transactions, the GET v1/benefits/totals endpoint provides a customer's total income under each detected benefit type. This is useful when you want to understand which benefits a customer receives or how much a customer receives from each benefit, without having to add up the transactions yourself.

As with the transactions endpoint, you can use the X-From and X-To headers to set the date range you would like totals for. If you don't provide them, the totals will be calculated from the last 30 days up to today's date. An example request can be seen below.

curl --request GET \
     --url https://api-sandbox.thisisbud.com/v1/benefits/totals \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'X-From: 2025-01-01' \
     --header 'X-To: 2026-01-01' \
     --header 'accept: application/json'

In the case that no benefit transactions can be found for the customer you will receive a 204 response with an empty body. As with the transactions endpoint, if you receive a 400 response please check the headers you're sending in the request before trying again, and consult the error responses guide if the error continues.

Supported benefit types

In the table below you will be able to identify the benefit types that Benefits Finder currently supports, along with the type and display_name values you will receive in the response. These apply to both the Benefits Transactions and Benefits Totals endpoints.

📘

This is not an exhaustive list

The benefit types we support will continue to change over time as we add new benefits and update existing ones. This means you may receive a benefit type that isn't listed here. We recommend building your integration so that it can handle new values without failing, for example by relying on the display_name when showing a benefit to a customer.

Display nameType
Attendance Allowanceattendance_allowance
Bereavement Support Paymentbereavement_support_payment
Best Start Grantbest_start_grant
Carers Allowancecarers_allowance
Child Benefitchild_benefit
Child Maintenancechild_maintenance
Child Support Allowancechild_support_allowance
Child Tax Creditchild_tax_credit
Christmas Bonuschristmas_bonus
Cold Weather Paymentcold_weather_payment
Cost of Living Paymentcost_of_living_payment
Covid 19 Supportcovid_19_support
Disability Living Allowancedisability_living_allowance
Disability Premiumdisability_premium
Employment and Support Allowanceemployment_and_support_allowance
Incapacity Benefitsincapacity_benefits
Income Supportincome_support
Industrial Injuries Benefitindustrial_injuries_benefit
Job Seekers Allowancejob_seekers_allowance
Maternity Allowancematernity_allowance
Pension Creditpension_credit
Personal Independence Paymentpersonal_independence_payment
Scottish Child Paymentscottish_child_payment
Self Employment Income Support Schemeself_employment_income_support_scheme
Severe Disablement Allowancesevere_disablement_allowance
Social Fundsocial_fund
State Pensionstate_pension
Universal Credituniversal_credit
Widow's Benefitwidows_benefit
Winter Fuel Paymentwinter_fuel_payment
Working Tax Creditworking_tax_credit

A few benefits behave slightly differently to the rest, so it's worth being aware of the following:

  • Child Maintenance is paid by a parent rather than by the government.
  • Best Start Grant and Scottish Child Payment are available to customers in Scotland.
  • Cost of Living Payment, Covid 19 Support and Self Employment Income Support Scheme relate to one-off or time-limited schemes, so you are most likely to see them in historic transactions.

If you would like to know whether a specific benefit is supported, or you would like to request support for a new one, please raise a support ticket.


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



Did this page help you?