Savings Goals
What are Savings Goals?
Savings goals are a way for customers to track and reach their savings goals within the Bud platform.
Create a Savings Goal
The POST goals/v1/savings
endpoint allows a savings goal to be created against a given account_id
. The provided account_id
must be present in the Bud platform.
The target_amount
, target_date
, and recurrent_amount
are also validated to ensure the savings goal is achievable within these constraints. At least two of these parameters must be supplied, the third is calculated if not present. When only two parameters are supplied, it is assumed that no payment will be made towards the goal within the month of creation.
This endpoint will return the created savings goal with its id
and created_at
time. An example of a 201
response can be seen below.
{
"operation_id": "goals_v1_savings_post",
"data": {
"id": "f46d76c4-56d3-11ee-ac69-d6df71eb5902",
"account_id": "RxsYshVGded4JeilkXgWKdXA",
"name": "Car Savings",
"target_amount": {
"currency": "GBP",
"value": "3000.00"
},
"recurrent_amount": {
"currency": "GBP",
"value": "750.00"
},
"target_date": "2023-12-30",
"saved_amount": {
"currency": "GBP",
"value": "0.00"
},
"created_at": "2023-09-19T10:04:43Z"
}
}
curl --request POST \
--url https://api-sandbox.thisisbud.com/goals/v1/savings \
--header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
--header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
--header 'accept: application/json' \
--header 'authorization: Bearer dddd' \
--header 'content-type: application/json' \
--data '
{
"target_amount": {
"value": "3000",
"currency": "GBP"
},
"recurrent_amount": {
"value": "750",
"currency": "GBP"
},
"name": "Car Savings",
"account_id": "RxsYshVGded4JeilkXgWKdXA",
"target_date": "2023-12-30"
}
'
In the case that the provided account_id
does not exist within the Bud platform, 404
HTTP response will be given
If you receive a 400
response, please check the headers and body you're sending in the request before trying again.
Retrieve Savings Goals
The GET goals/v1/savings
endpoint retrieves all savings goals for a customer.
This endpoint can be filtered account_id
using the query parameter filter. An example of a 200
response can be seen below, the result is filtered by the account_id
RxsYshVGded4JeilkXgWKdXA
.
The response includes the saved_amount
field which is a running total of the Savings Goal Actions
against the goal.
{
"operation_id": "goals_v1_savings_get",
"data": [
{
"id": "f46d76c4-56d3-11ee-ac69-d6df71eb5902",
"account_id": "RxsYshVGded4JeilkXgWKdXA",
"name": "Car Savings",
"target_amount": {
"currency": "GBP",
"value": "3000.00"
},
"recurrent_amount": {
"currency": "GBP",
"value": "750.00"
},
"target_date": "2023-12-30",
"saved_amount": {
"currency": "GBP",
"value": "0.00"
},
"created_at": "2023-09-19T10:04:43Z"
},
{
"id": "265a4aed-348d-4ff1-802e-2d08d7cace77",
"account_id": "RxsYshVGded4JeilkXgWKdXA",
"name": "Holiday Savings",
"target_amount": {
"currency": "GBP",
"value": "1000.00"
},
"recurrent_amount": {
"currency": "GBP",
"value": "100.00"
},
"target_date": "2023-07-30",
"saved_amount": {
"currency": "GBP",
"value": "0.00"
},
"created_at": "2023-09-19T10:04:43Z"
}
],
"metadata": {
"results": 2,
"account_id": "RxsYshVGded4JeilkXgWKdXA"
}
}
curl --request GET \
--url https://api-sandbox.thisisbud.com/goals/v1/savings \
--header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
--header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
--header 'accept: application/json' \
--header 'authorization: Bearer dddd'
In the case that the customer has no savings goals, a 200
is still returned with a response as below.
{
"operation_id": "goals_v1_savings_get",
"data": [],
"metadata": {
"results": 0,
"account_id": null
}
}
curl --request GET \
--url https://api-sandbox.thisisbud.com/goals/v1/savings \
--header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
--header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
--header 'accept: application/json' \
--header 'authorization: Bearer dddd'
If you receive a 400
response, please check the headers you're sending in the request before trying again.
Update a Savings Goal
The PATCH goals/v1/savings/{goal_id}
endpoint is used to update a savings goal.
The goal's name
, target_amount
, target_date
, and recurrent_amount
can be updated.
If target_amount
, target_date
, and/or recurrent_amount
is updated, then another of the fields must be supplied as is the case with the POST goals/v1/savings
endpoint. Validation upon these fields is re-run when the goal is updated as it is on the POST goals/v1/savings
endpoint.
This endpoint will return the updated savings goal. An example of a 200
response can be seen below.
{
"operation_id": "goals_v1_savings_post",
"data": {
"id": "f46d76c4-56d3-11ee-ac69-d6df71eb5902",
"account_id": "RxsYshVGded4JeilkXgWKdXA",
"name": "Holiday",
"target_amount": {
"currency": "GBP",
"value": "3000.00"
},
"recurrent_amount": {
"currency": "GBP",
"value": "750.00"
},
"target_date": "2024-01-30",
"saved_amount": {
"currency": "GBP",
"value": "0.00"
},
"created_at": "2023-09-19T10:04:43Z"
}
}
curl --request PATCH \
--url https://api-sandbox.thisisbud.com/goals/v1/savings/goal_id \
--header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
--header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
--header 'accept: application/json' \
--header 'authorization: Bearer dddd' \
--header 'content-type: application/json' \
--data '{"name":"Holiday"}'
In the case that the provided goal_id
does not exist, 404
HTTP response will be given
If you receive a 400
response, please check the headers and body you're sending in the request before trying again.
Delete a Savings Goal
The DELETE goals/v1/savings
endpoint removes all savings goals for a given customer.
If you would like to delete a specific goal you can do so by specifying an id
in the URL of the endpoint such as
curl --request DELETE \
--url https://api-sandbox.thisisbud.com/goals/v1/savings/81a68821-dca6-4771-80d4-002c7fce412e \
--header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
--header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
--header 'accept: application/json' \
--header 'authorization: Bearer dddd'
This endpoint will return a 204
if the deletion has been successful.
In the case that the customer doesn't have a goal with an id
that matches the id
provided in the request, a 404
is returned.
If you receive a 400
response, please check the headers you're sending in the request before trying again.
Saving Goal Actions
Create a Savings Goal Action
The POST goals/v1/savings{goal_id}/actions
endpoint allows an action to be created against a given savings goal. An action is an indication from the customer that they have paid a contribution into the given account towards their savings goal.
The amount
can be a debit
or a credit
, denoted by the credit_debit_indicator
, should a customer withdraw or add money from or to the associated account.
The amount is validated against the balance of the account to ensure it is possible that this contribution has been paid into the account.
This endpoint will return the created action with its id
and created_at
time. An example of a 201
response can be seen below.
{
"operation_id": "goals_v1_savings_actions_post",
"data": {
"id": "23267253-5860-11ee-99e5-9ed0600d2630",
"amount": {
"currency": "GBP",
"value": "10.00"
},
"credit_debit_indicator": "credit",
"created_at": "2023-09-21T09:20:42Z"
},
"metadata": {
"goal_id": "19d1def3-5860-11ee-9342-3e1d60bc76f9"
}
}
curl --request POST \
--url https://api-sandbox.thisisbud.com/goals/v1/savings/goal_id/actions \
--header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
--header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
--header 'accept: application/json' \
--header 'authorization: Bearer dddd' \
--header 'content-type: application/json' \
--data '
{
"amount": {
"value": "10",
"currency": "GBP"
},
"credit_debit_indicator": "credit"
}
'
In the case that the action cannot have been made as it is not valid against the account's balance, then 400
is returned.
If you receive a 400
response, please check the headers and body you're sending in the request before trying again.
Retrieve Savings Goal Actions
The GET goals/v1/savings/{goal_id}/actions
endpoint retrieves all actions for a customer's savings goal.
This endpoint is paginated with a maximum page size of 200 and a default of 100, this can be set via the page_size
query parameter. If more pages are available, then a page_token
field will be present in the metadata of the response. The value of this field should be put in the page_token
query parameter to fetch the next page if results.
Below is an example response with a page_token
indicating there is a further page of actions available.
{
"operation_id": "goals_v1_savings_actions_get",
"data": [
{
"id": "23267253-5860-11ee-99e5-9ed0600d2630",
"amount": {
"currency": "GBP",
"value": "10.00"
},
"credit_debit_indicator": "credit",
"created_at": "2023-09-21T09:20:42Z"
},
{
"id": "23267253-5860-11ee-99e5-9ed0600d2630",
"amount": {
"currency": "GBP",
"value": "10.00"
},
"credit_debit_indicator": "credit",
"created_at": "2023-09-21T09:20:42Z"
}
],
"metadata": {
"results": 2,
"page_token": "b21055a9a9f46fc794a2e6855c65abd7e317181039fc6930daabac5822911d14a84895ecd947e2b5abdcb22e4fcc2c594e1f661dc63e34b9ba88760724047990896f7581a0786c2605dce19c6a9d80d1044f963b74fea0a929c0a4465a6e67378a74dce38ec5e26ae4cc804b62fd666d5df4cf2e7f524bd99e5523bc5d471768065c036dc0c73122705b280817fbbd7d9aa31f271d72cd3877d999dcb9a5b1c0be0c05",
"page_size": 100,
"goal_id": "19d1def3-5860-11ee-9342-3e1d60bc76f9"
}
}
curl --request GET \
--url https://api-sandbox.thisisbud.com/goals/v1/savings/goal_id/actions \
--header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
--header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
--header 'accept: application/json' \
--header 'authorization: Bearer dddd'
In the case that there are no further pages of results, the page_token
in the metadata will be empty.
{
"operation_id": "goals_v1_savings_actions_get",
"data": [..],
"metadata": {
"results": 2,
"page_token": "",
"page_size": 100,
"goal_id": "19d1def3-5860-11ee-9342-3e1d60bc76f9"
}
}
If you receive a 400
response, please check the headers you're sending in the request before trying again.
Update Savings Goal Actions
The PATCH goals/v1/savings/{goal_id}/actions/{goal_action_id}
endpoint is used to update a goal's action.
When a goal action is updated, the amount is once again validated against the associated account's balance as it is upon creation.
This endpoint will return the updated savings goal. An example of a 200
response can be seen below.
{
"operation_id": "goals_v1_savings_actions_patch",
"data": {
"id": "23267253-5860-11ee-99e5-9ed0600d2630",
"amount": {
"currency": "GBP",
"value": "10.00"
},
"credit_debit_indicator": "credit",
"created_at": "2023-09-21T09:20:42Z"
},
"metadata": {
"goal_id": "19d1def3-5860-11ee-9342-3e1d60bc76f9"
}
}
curl --request PATCH \
--url https://api-sandbox.thisisbud.com/goals/v1/savings/goal_id/actions/goal_action_id \
--header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
--header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
--header 'accept: application/json' \
--header 'authorization: Bearer dddd' \
--header 'content-type: application/json' \
--data '
{
"amount": {
"value": "15",
"currency": "GBP"
}
}
'
In the case that the provided goal_id
or goal_action_id
does not exist, 404
HTTP response will be given
If you receive a 400
response, please check the headers and body you're sending in the request before trying again.
Delete a Savings Goal Action
The DELETE goals/v1/savings/{goal_id}/actions/{goal_action_id}
endpoint removes a given action. The response from this endpoint will be 204
if the deletion is successful.
curl --request DELETE \
--url https://api-sandbox.thisisbud.com/goals/v1/savings/goal_id/actions/goal_action_id \
--header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
--header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
--header 'accept: application/json' \
--header 'authorization: Bearer dddd'
In the case that the customer has no action with a goal_id
and goal_action_id
that matches the goal_id
and goal_action_id
provided, a 404
is returned.
If you receive a 400
response, please check the headers you're sending in the request before trying again.
Dealing with 401
and 500
responses
401
and 500
responsesIf you receive a 401
response from any of these endpoints this 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.
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 7 months ago