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 listThe 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
typethat isn't listed here. We recommend building your integration so that it can handle new values without failing, for example by relying on thedisplay_namewhen showing a benefit to a customer.
| Display name | Type |
|---|---|
| Attendance Allowance | attendance_allowance |
| Bereavement Support Payment | bereavement_support_payment |
| Best Start Grant | best_start_grant |
| Carers Allowance | carers_allowance |
| Child Benefit | child_benefit |
| Child Maintenance | child_maintenance |
| Child Support Allowance | child_support_allowance |
| Child Tax Credit | child_tax_credit |
| Christmas Bonus | christmas_bonus |
| Cold Weather Payment | cold_weather_payment |
| Cost of Living Payment | cost_of_living_payment |
| Covid 19 Support | covid_19_support |
| Disability Living Allowance | disability_living_allowance |
| Disability Premium | disability_premium |
| Employment and Support Allowance | employment_and_support_allowance |
| Incapacity Benefits | incapacity_benefits |
| Income Support | income_support |
| Industrial Injuries Benefit | industrial_injuries_benefit |
| Job Seekers Allowance | job_seekers_allowance |
| Maternity Allowance | maternity_allowance |
| Pension Credit | pension_credit |
| Personal Independence Payment | personal_independence_payment |
| Scottish Child Payment | scottish_child_payment |
| Self Employment Income Support Scheme | self_employment_income_support_scheme |
| Severe Disablement Allowance | severe_disablement_allowance |
| Social Fund | social_fund |
| State Pension | state_pension |
| Universal Credit | universal_credit |
| Widow's Benefit | widows_benefit |
| Winter Fuel Payment | winter_fuel_payment |
| Working Tax Credit | working_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.
Updated 10 days ago

