Tutorial: Get Balance Prediction
Balance Prediction product is available as a Private Beta version.
Introduction
This tutorial explains how to get Balance Prediction in the UK with the Modelo Sandbox.
Note: All requests made to the Yapily API require basic authentication.
1. Select bank
To find which banks support accessing account and transaction information use GET institutions to retrieve the list of your supported institutions.
Request:
curl -L -X GET 'https://api.yapily.com/institutions' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'Response:
{
"meta": {
"tracingId": "acbb76db4ab8f4ac7f039d000456c13f",
"count": 1
},
"data": [
{
"id": "modelo-sandbox",
"name": "Modelo Sandbox",
"fullName": "Modelo Sandbox",
"countries": [
{
"displayName": "United Kingdom",
"countryCode2": "GB"
}
],
"environmentType": "SANDBOX",
"credentialsType": "OPEN_BANKING_UK_AUTO",
"media": [
{
"source": "https://images.yapily.com/image/ce2bfdbf-1ae2-4919-ab7b-e8b3d5e93b36?size=0",
"type": "icon"
},
{
"source": "https://images.yapily.com/image/ca502f24-d6df-4785-b4b8-1034b100af77?size=0",
"type": "logo"
}
],
"features": [
"INITIATE_ACCOUNT_REQUEST",
"ACCOUNT_REQUEST_DETAILS",
"EXISTING_PAYMENTS_DETAILS",
"ACCOUNT_BALANCES",
"CREATE_BULK_PAYMENT",
"ACCOUNT_PERIODIC_PAYMENTS",
"ACCOUNT_STATEMENTS",
"INITIATE_BULK_PAYMENT",
"ACCOUNT_STATEMENT",
"ACCOUNT",
"INITIATE_DOMESTIC_PERIODIC_PAYMENT",
"INITIATE_SINGLE_PAYMENT_SORTCODE",
"ACCOUNT_DIRECT_DEBITS",
"ACCOUNTS",
"ACCOUNT_TRANSACTIONS",
"EXISTING_PAYMENT_INITIATION_DETAILS",
"CREATE_DOMESTIC_SINGLE_PAYMENT",
"INITIATE_DOMESTIC_SINGLE_PAYMENT",
"ACCOUNT_STATEMENT_FILE",
"CREATE_INTERNATIONAL_SINGLE_PAYMENT",
"IDENTITY",
"CREATE_DOMESTIC_SCHEDULED_PAYMENT",
"INITIATE_DOMESTIC_SCHEDULED_PAYMENT",
"CREATE_SINGLE_PAYMENT_SORTCODE",
"ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
"INITIATE_INTERNATIONAL_SINGLE_PAYMENT",
"PERIODIC_PAYMENT_FREQUENCY_EXTENDED",
"ACCOUNT_SCHEDULED_PAYMENTS",
"CREATE_DOMESTIC_PERIODIC_PAYMENT"
]
}
]
}Filter the list for all institutions that support the ACCOUNTS and ACCOUNT_TRANSACTIONS features. Then display these institutions in your application so the user can select which bank to share their account information from.
Once the user selects a bank, store the id of the institution to use in step 2.
2. Authorise
note
This example uses a single redirect flow using a callback URL.
Execute create account authorisation, including the institution ID and your callback URL.
Request:
curl -L -X POST 'https://api.yapily.com/account-auth-requests' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
"applicationUserId": "account-data-and-transactions-tutorial",
"institutionId": "modelo-sandbox",
"callback": "https://display-parameters.com/"
}'Response:
{
"meta": {
"tracingId": "ceab45e96f852afdb59ec8eaf8f93594"
},
"data": {
"id": "979f8a58-c955-46b5-b25d-bdc447c28a80",
"userUuid": "c78035e1-3140-44f7-9539-527785069356",
"applicationUserId": "account-data-and-transactions-tutorial",
"institutionId": "modelo-sandbox",
"status": "AWAITING_AUTHORIZATION",
"createdAt": "2021-03-04T11:05:17.234Z",
"featureScope": [
"ACCOUNT_STATEMENT_FILE",
"ACCOUNT_STATEMENTS",
"ACCOUNT_BALANCES",
"ACCOUNT_SCHEDULED_PAYMENTS",
"ACCOUNT_STATEMENT",
"ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
"ACCOUNT_TRANSACTIONS",
"ACCOUNT_DIRECT_DEBITS",
"IDENTITY",
"ACCOUNT",
"ACCOUNTS",
"ACCOUNT_PERIODIC_PAYMENTS"
],
"state": "e539228113de43b3a3d4c3b9944620d3",
"institutionConsentId": "aac-74e55df8-a673-48b4-b8ae-3e8d0e45080f",
"authorisationUrl": "{authorisationUrl}",
"qrCodeUrl": "https://images.yapily.com/image/d4113d96-9d6c-4e69-a840-2e327cff1b1d/1614855917?size=0"
}
}Redirect the user to the authorisationUrl returned in the response.
The user is then asked to login and authorise the account sharing request with their bank. The Modelo sandbox credentials are: mits / mits.
Upon completion, the user is redirected back to the callback URL supplied in the request. In this example, the callback is https://display-parameters.com/ which displays the parameters returned with the redirect.
Store the consentToken and userUuid from the API response to use when creating a financial profile in step 3.
3. Create financial profile consent
Create a financial profile consent specifying the userUuid in the path, and the consentToken in the header.
Request:
curl -L -X POST 'https://api.yapily.com/users/{userUuid}/profile/consents' \
-H 'consent: {consentToken}' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'Response:
{
"id": "bb76f9a7-f5ff-480d-8d40-4b0e1eb8f400",
"status": "PENDING",
"userId": "c78035e1-3140-44f7-9539-527785069356",
"referenceConsentId": "979f8a58-c955-46b5-b25d-bdc447c28a80",
"institutionId": "modelo-sandbox"
}The status of the financial profile consent is returned in the response.
The initial status is PENDING as the profile consent has been created but the financial data associated with that consent has not been retrieved yet. The requests to retrieve the financial data for a profile consent are handled by Yapily behind the scenes asynchronously.
You should poll GET /profile/consents/{id} until the status transitions to COMPLETED, and then move to step 4. This could take several minutes after creating the profile consent, depending on the amount of financial data available.
Note: If the user has multiple consents, repeat Steps 2-3 for each consent obtained from the user.
4. Get Balance Prediction
Get Balance Prediction for the user, specifying the userUuid.
Note: After 5 minutes the profileConsents.status will be EXPIRED. To retrieve balance prediction data again you need to create a new financial profile consent for the user.
Request:
curl -L -X GET 'https://api.yapily.com/users/{userUuid}/profile/predicted-balances' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'Response:
{
"status": "COMPLETED",
"profileConsents": [
{
"id": "bb76f9a7-f5ff-480d-8d40-4b0e1eb8f400",
"status": "COMPLETED",
"userId": "c78035e1-3140-44f7-9539-527785069356",
"referenceConsentId": "979f8a58-c955-46b5-b25d-bdc447c28a80",
"institutionId": "modelo-sandbox"
}
],
"enrichedBalances": [
{
"accountIds": [
"7cd08e5d-8e75-400b-8698-4e558123f0ef"
],
"institutions": [
"modelo-sandbox"
],
"historic": [
{
"date": "2022-07-01",
"balance": 0.39
},
{
"date": "2022-07-02",
"balance": 0.39
},
{
"date": "2022-07-03",
"balance": 0.39
},
{
"date": "2022-07-04",
"balance": 0.39
},
{
"date": "2022-07-05",
"balance": 0.39
},
{
"date": "2022-07-06",
"balance": 0.39
},
{
"date": "2022-07-07",
"balance": 0.39
},
{
"date": "2022-07-08",
"balance": 0.39
},
{
"date": "2022-07-09",
"balance": 0.39
},
{
"date": "2022-07-10",
"balance": 0.39
},
{
"date": "2022-07-11",
"balance": 0.39
},
{
"date": "2022-07-12",
"balance": 0.39
},
{
"date": "2022-07-13",
"balance": 0.39
},
{
"date": "2022-07-14",
"balance": 0.39
},
{
"date": "2022-07-15",
"balance": 0.39
},
{
"date": "2022-07-16",
"balance": 0.39
},
{
"date": "2022-07-17",
"balance": 0.39
},
{
"date": "2022-07-18",
"balance": 0.39
},
{
"date": "2022-07-19",
"balance": 0.39
},
{
"date": "2022-07-20",
"balance": 0.39
},
{
"date": "2022-07-21",
"balance": 0.39
},
{
"date": "2022-07-22",
"balance": 0.39
},
{
"date": "2022-07-23",
"balance": 0.39
},
{
"date": "2022-07-24",
"balance": 0.39
},
{
"date": "2022-07-25",
"balance": 0.39
},
{
"date": "2022-07-26",
"balance": 0.39
},
{
"date": "2022-07-27",
"balance": 0.39
},
{
"date": "2022-07-28",
"balance": 0.39
},
{
"date": "2022-07-29",
"balance": 0.39
},
{
"date": "2022-07-30",
"balance": 0.39
},
{
"date": "2022-07-31",
"balance": 0.39
},
{
"date": "2022-08-01",
"balance": 0.39
},
{
"date": "2022-08-02",
"balance": 0.39
},
{
"date": "2022-08-03",
"balance": 0.39
},
{
"date": "2022-08-04",
"balance": 0.39
},
{
"date": "2022-08-05",
"balance": 0.39
},
{
"date": "2022-08-06",
"balance": 0.39
},
{
"date": "2022-08-07",
"balance": 0.39
},
{
"date": "2022-08-08",
"balance": 0.38
},
{
"date": "2022-08-09",
"balance": 0.38
},
{
"date": "2022-08-10",
"balance": 0.38
},
{
"date": "2022-08-11",
"balance": 0.38
},
{
"date": "2022-08-12",
"balance": 0.38
},
{
"date": "2022-08-13",
"balance": 0.38
},
{
"date": "2022-08-14",
"balance": 0.38
},
{
"date": "2022-08-15",
"balance": 0.38
},
{
"date": "2022-08-16",
"balance": 0.38
},
{
"date": "2022-08-17",
"balance": 0.38
},
{
"date": "2022-08-18",
"balance": 0.38
},
{
"date": "2022-08-19",
"balance": 0.38
},
{
"date": "2022-08-20",
"balance": 0.38
},
{
"date": "2022-08-21",
"balance": 0.38
},
{
"date": "2022-08-22",
"balance": 0.38
},
{
"date": "2022-08-23",
"balance": 0.38
},
{
"date": "2022-08-24",
"balance": 0.38
},
{
"date": "2022-08-25",
"balance": 0.38
},
{
"date": "2022-08-26",
"balance": 0.38
},
{
"date": "2022-08-27",
"balance": 0.38
},
{
"date": "2022-08-28",
"balance": 0.38
},
{
"date": "2022-08-29",
"balance": 0.38
}
],
"predicted": [
{
"90percentileBalance": 0.43,
"10percentileBalance": -0.01,
"date": "2022-08-30",
"medianBalance": 0.31
},
{
"90percentileBalance": 0.47,
"10percentileBalance": 0.02,
"date": "2022-08-31",
"medianBalance": 0.31
},
{
"90percentileBalance": 0.48,
"10percentileBalance": 0.03,
"date": "2022-09-01",
"medianBalance": 0.32
},
{
"90percentileBalance": 0.47,
"10percentileBalance": 0.03,
"date": "2022-09-02",
"medianBalance": 0.32
},
{
"90percentileBalance": 0.47,
"10percentileBalance": 0.04,
"date": "2022-09-03",
"medianBalance": 0.33
},
{
"90percentileBalance": 0.5,
"10percentileBalance": 0.04,
"date": "2022-09-04",
"medianBalance": 0.33
},
{
"90percentileBalance": 0.49,
"10percentileBalance": 0.06,
"date": "2022-09-05",
"medianBalance": 0.34
},
{
"90percentileBalance": 0.52,
"10percentileBalance": 0.06,
"date": "2022-09-06",
"medianBalance": 0.34
},
{
"90percentileBalance": 0.52,
"10percentileBalance": 0.06,
"date": "2022-09-07",
"medianBalance": 0.33
},
{
"90percentileBalance": 0.52,
"10percentileBalance": 0.07,
"date": "2022-09-08",
"medianBalance": 0.34
},
{
"90percentileBalance": 0.53,
"10percentileBalance": 0.08,
"date": "2022-09-09",
"medianBalance": 0.35
},
{
"90percentileBalance": 0.53,
"10percentileBalance": 0.08,
"date": "2022-09-10",
"medianBalance": 0.35
},
{
"90percentileBalance": 0.53,
"10percentileBalance": 0.09,
"date": "2022-09-11",
"medianBalance": 0.35
},
{
"90percentileBalance": 0.53,
"10percentileBalance": 0.1,
"date": "2022-09-12",
"medianBalance": 0.36
},
{
"90percentileBalance": 0.53,
"10percentileBalance": 0.11,
"date": "2022-09-13",
"medianBalance": 0.36
},
{
"90percentileBalance": 0.54,
"10percentileBalance": 0.12,
"date": "2022-09-14",
"medianBalance": 0.36
},
{
"90percentileBalance": 0.54,
"10percentileBalance": 0.12,
"date": "2022-09-15",
"medianBalance": 0.36
},
{
"90percentileBalance": 0.55,
"10percentileBalance": 0.13,
"date": "2022-09-16",
"medianBalance": 0.37
},
{
"90percentileBalance": 0.55,
"10percentileBalance": 0.14,
"date": "2022-09-17",
"medianBalance": 0.38
},
{
"90percentileBalance": 0.56,
"10percentileBalance": 0.16,
"date": "2022-09-18",
"medianBalance": 0.38
},
{
"90percentileBalance": 0.54,
"10percentileBalance": 0.17,
"date": "2022-09-19",
"medianBalance": 0.38
},
{
"90percentileBalance": 0.54,
"10percentileBalance": 0.18,
"date": "2022-09-20",
"medianBalance": 0.39
},
{
"90percentileBalance": 0.55,
"10percentileBalance": 0.19,
"date": "2022-09-21",
"medianBalance": 0.39
},
{
"90percentileBalance": 0.55,
"10percentileBalance": 0.2,
"date": "2022-09-22",
"medianBalance": 0.39
},
{
"90percentileBalance": 0.56,
"10percentileBalance": 0.21,
"date": "2022-09-23",
"medianBalance": 0.4
},
{
"90percentileBalance": 0.56,
"10percentileBalance": 0.22,
"date": "2022-09-24",
"medianBalance": 0.41
},
{
"90percentileBalance": 0.56,
"10percentileBalance": 0.24,
"date": "2022-09-25",
"medianBalance": 0.41
},
{
"90percentileBalance": 0.55,
"10percentileBalance": 0.24,
"date": "2022-09-26",
"medianBalance": 0.41
},
{
"90percentileBalance": 0.56,
"10percentileBalance": 0.25,
"date": "2022-09-27",
"medianBalance": 0.41
},
{
"90percentileBalance": 0.56,
"10percentileBalance": 0.26,
"date": "2022-09-28",
"medianBalance": 0.4
}
]
}
]
}