For most integrations we recommend you use the iFrame as implementing your own session management for the end user quickly becomes a more complicated than you'd first expect when you consider the mobile ecosystem and session interruption.
Quickstart Guide
This API quickstart guide is here to help you get up and running with TaleFin's API. In this guide, we will be connecting a user with their nominated bank account, extracting and analysing all of the transactions from the last year in that account and displaying it; all by using the API.
Access
To gain access, you must first create an account by using the demo (top right hand corner of this site). All the information you need will be sent to you in an email. Once that is done, you can use the iFrame and access the dashboard to view the analyses.
You will be provided with a vendor label; basically a small identifier that lets us know the application belongs to you. This label will be used in some API requests as a way of quickly and positively identifying your organisation.
Basic User Flow
There are three simple steps required to connect an end-user and analyse their transaction information.
- Submit the initial user information
- Handle any inputs that the bank requests, as necessary, including Multi-Factor Authentication (MFA)
- Retrieve data once the webhooks announce it's ready
We'll cover each of these steps in greater detail below.
Submit the Initial User Information
Submitting the user information creates what is referred to as a profile of that end user. A profile contains all the relevant information for that user. To create a profile POST the appropriate information to the following endpoint:
1https://banks.talefin.com/api/v1/{vendor_label}/{vendor_specific_id}/profileThis endpoint accepts the following information:
1{
2 "full_name": "string",
3 "email": "string",
4 "phone": "string",
5 "bank_id": int,
6 "days_to_retrieve": int,
7 "balances": boolean,
8 "transactions": boolean,
9 "interims": boolean,
10 "estatements": boolean,
11 "analysis": boolean,
12 "account_owner": boolean
13}You will notice one of the requirements as a vendor_specific_id.
This is a unique code created by yourself, that you should store
somewhere safe. It is your reference number that you can be used
to find your users' analysed transaction information in the future.
There are a whole bunch of paramaters that you can send to this API endpoint, however, to keep it simple let’s just send a few and rely on the defaults:
1{
2 "full_name": "Donald Duck",
3 "email": "test@test.com",
4 "phone": 040000000,
5 "bank_id": 130,
6 "analysis": true
7}You can replace "analysis": true, with any option from above, or even extend it to include several different options. For example;
1{
2 "full_name": " Donald Duck",
3 "email": "test@test.com",
4 "phone": 040000000,
5 "bank_id": 130,
6 "analysis": true,
7 "account_owner": true
8}For the bank_id, you can get a list of the most up to date supported banks from this endpoint:
1https://banks.talefin.com/api/v1/banksIn this case the test bank id, ‘Bank of TaleFin’, has been provided to run this initial test. Upon sending the POST request a UUID will be returned, looking something like this:
1{
2 "profile": 10000,
3 "uuid": "ba8f4a5e-be0b-4bcd-954a-483d86628e90",
4 "application": 100000,
5 "bank_id": 130,
6 "timestamp": "2020-09-10T11:26:25.576759+10:00",
7 "status": "QUEUED"
8}Using this UUID you can now poll to collect updates and inputs required by the bank crawler:
1https://banks.talefin.com/api/v1/{vendor_label}/{vendor_specific_id}/io/{uuid}Handle Inputs
This endpoint will tell you what you need to provide for the specific bank. For example,
username, password, mfa. Using this information you can then POST back the response to
the same input to provide this for the bank crawler extracting the information from
the bank account.
1{
2 "status": "AUTH",
3 "code": 1008,
4 "message": {
5 "status": "AUTH",
6 "standardError": {
7 "code": 1008,
8 "message": "Requesting users initial credential inputs"
9 },
10 "inputs": {
11 "pan": {
12 "name": "pan",
13 "label": "Personal Access Number",
14 "rel": "user",
15 "required": true,
16 "attrs": {
17 "autocomplete": "invalid-browser-string",
18 "type": "text"
19 },
20 "decorations": []
21 },
22 "securecode": {
23 "name": "securecode",
24 "label": "Secure Code",
25 "rel": "password",
26 "required": true,
27 "attrs": {
28 "autocomplete": "invalid-browser-string",
29 "type": "password"
30 },
31 "decorations": []
32 }
33 }
34 },
35 "pending_messages": [
36 {
37 "sequence": 6,
38 "message": {
39 "types": ["client", "input"],
40 "payload": {
41 "inputs": {
42 "pan": {
43 "name": "pan",
44 "label": "Personal Access Number",
45 "rel": "user",
46 "required": true,
47 "attrs": {
48 "autocomplete": "invalid-browser-string",
49 "type": "text"
50 },
51 "decorations": []
52 },
53 "securecode": {
54 "name": "securecode",
55 "label": "Secure Code",
56 "rel": "password",
57 "required": true,
58 "attrs": {
59 "autocomplete": "invalid-browser-string",
60 "type": "password"
61 },
62 "decorations": []
63 }
64 }
65 },
66 "sequence": 6
67 }
68 }
69 ],
70 "overflow": null,
71 "webhook_events": []
72}As you can see in this response, two inputs are
required pan and securecode. POSTing
these inputs with the provided key names e.g.
1{"pan": "username", "securecode": "password"}The crawler is able to log into the account and begin collecting the user information. This is the same for any MFA requests that are made by the bank account. Once the crawler has progressed to a point that it will no longer be needing to request any more input from you, the status will change to ‘RELEASED’ (see lifecycle documentation for more details).
Retrieve the data
Using the Dashboard you can add a webhook to webhook.site for testing. We recommend using Bank of TaleFin for testing as it is secure and allows a number of errors and successes to be generated. You can change or remove webhooks at any time either through the API or in the dashboard.
These webhooks will notify you when each component for the account has been processed and is ready for collection. To make it faster and more responsive, analyses are done in such a way that we send the data in segments as it’s ready for you to collect. However, for simplicity’s sake, we shall wait until all analyses are completed. When it’s done you will receive a webhook event called application.report_ready:
1{
2 "event": "application.report_ready",
3 "payload": {
4 "id": 100000,
5 "vendor_specific_id": "123456789",
6 "vendor_label": "test",
7 "timestamp": "2020-09-10T08:53:02.229592+10:00",
8 "crawler": [
9 {
10 "profile": 10000,
11 "uuid": "ba8f4a5e-be0b-4bcd-954a-483d86628e90",
12 "application": 100000,
13 "bank_id": 130,
14 "timestamp": "2020-09-10T08:53:04.039916+10:00",
15 "status": "COMPLETED"
16 }
17 ],
18 "full_name": "Donald Duck",
19 "email": "test@test.com",
20 "mobile": "04000000",
21 "finalised": true,
22 "analysed": true
23 }
24}Using this information, we can view the fruits of our labour, in HTML:
1https://banks.talefin.com/api/v1/applications/{application_id}/summary/htmlin JSON:
1https://banks.talefin.com/api/v1/applications/{application_id}/summaryor PDF:
1https://banks.talefin.com/api/v1/applications/{application_id}/summary/pdfError Handling
You can view an exhaustive list of all the possible errors and warnings that could occur by visiting the error docs.
Refresh applications
A refresh is an application created from the crawler seed which is generated from regular applications, without the need for client input. These seeds are only available for 7 days following the application. A refresh will not work for institutions that require MFA.
The refresh will carry over the same settings from the original application. This makes it an effective way to perform subsequent crawls for a repeat client. Rather than creating a profile and sending inputs, to perform a refresh you will need to hit the following endpoint:
1https://banks.talefin.com/api/v1/{vendor_label}/{vendor_specific_id}/refreshThe process is otherwise the same as above.
The default payload looks like this:
1{
2 "inputs": "string",
3 "id": "12345678",
4 "is_real_time": false,
5}inputs required
The encoded inputs from the crawler seed.
id required
The ID of the crawler seed.
is_real_time optional
This denotes whether the application should be performed as if it is a real-time application or not. The default behaviour for a refresh is not the same as a real-time application, therefore this should be set to false unless advised otherwise.
Analyse existing files
If you have account files from an external source that you wish to run through the Talefin analysis engine, then you can use the updated classify endpoint at:
1https://banks.talefin.com/api/v1/{vendor_label}/{vendor_specific_id}/classify/appendThis endpoint has been simplified for the user, so now all that is required is your JSON payload, the origin of that payload and a bank ID. The default payload looks like this:
1{
2 "accounts": null,
3 "bank": null,
4 "analyse_now": false,
5 "detect_dishonours": false,
6 "days_to_retrieve": null,
7 "days_to_display": null,
8 "adjust_time_to_today": false,
9 "origin": ""
10}accounts required
This is where you put your existing file, which should be a JSON packet containing the bank accounts and transactions belonging to a single bank profile.
For Plaid users, you will need to append the numbers values from their /auth endpoint to your asset file as these are not included by default.
bank required
This is the bank ID which you can find on the /banks endpoint above.
analyse_now optional
This determines when to run the analysis. Set this to true for single profile applications or to finalise a multiple profile application.
detect_dishonours optional
This determines whether to include the enhanced dishonour matching feature in the analysis.
days_to_retrieve optional
Set this to the date range of transactions you would like the analysis to run on. This would typically be the same as the date range of the data in your accounts payload. If no value is provided, it will default to your vendor label's days_to_retrieve setting.
days_to_display optional
Set this to the date range of transactions you would like displayed as a raw statement in the analysis. This can be used to truncate the data in the analysis without affecting the results. If no value is provided, it will default to your vendor label's days_to_display setting.
adjust_time_to_today optional
Set this to true to shift the date range of transactions such that the most recent occur on the current day. This can be used to analyse payloads containing data older than 365 days.
origin required
This determines where the provided payload comes from. Currently supported payloads include:
"illion" (Illion Report);
"creditsense" (Credit Sense Data Only Report);
"creditsense-detailed" (Credit Sense Detailed Report);
"plaid" (Canadian Bank Report);
"talefin" (Talefin bundle JSON).
After a successful POST, you will receive a response that will look something like this:
1{
2 "application_id": 123456,
3 "profile_id": 98765,
4 "vendor_label": "{vendor_label}",
5 "vendor_specific_id": "{vendor_specific_id}"
6}You can then view your application running at:
1https://banks.talefin.com/dashboard/lookup?vendor_specific_id={vendor_specific_id}Recategorise transactions for reanalysis
If you believe a transaction to be miscategorised you can modify it and perform reanalysis using the following endpoint:
1https://banks.talefin.com/api/v1/{vendor_label}/{vendor_specific_id}/classify/recategoriseTo use this endpoint, you need to have a completed (i.e. analysed and finalised) application.
The vendor_label and vendor_specific_id in the request URL should correspond to that of the completed application containing the transactions you wish to modify.
The default payload looks like this:
1{
2 "transaction_info_category_updates":
3 {
4 "updates": [
5 {
6 "transaction_info_id": int,
7 "category_id": int
8 }
9 ]
10 },
11 "analyse_now": false
12}transaction_info_category_updates required
This should be a JSON payload containing an array of the updates you wish to make.
An update should be a dict of transaction_info_id and category_id.
The endpoint will return with a status of 400 if no updates are provided, including an empty array.
transaction_info_id required
The ID of the transaction info object you want to make an update to. This can be found in the Talefin account analysis, application report and application bundle JSON files.
This can come from any account on any profile within the application matching the vendor_label and vendor_specific_id provided in the request URL.
category_id required
The ID of the new category you wish to update the transaction to. A list of valid categories can be found on the following endpoint:
1https://banks.talefin.com/api/v1/categoriesanalyse_now optional
This determines whether to run reanalysis, after which any updates made will be visible in the application's analysis documents.
This means you can continue to hit the endpoint with "analyse_now": false to keep making updates before reanalysing.
The default value is false.
After a successful POST, you will receive a response that will look something like this:
1{
2 "application_id": 123456,
3 "vendor_label": "{vendor_label}",
4 "vendor_specific_id": "{vendor_specific_id}"
5}You can then view your application running at:
1https://banks.talefin.com/dashboard/lookup?vendor_specific_id={vendor_specific_id}After reanalysis is completed, you can observe the updates you made in the analysis and summary documentation. Additionally, a log of any updates made will be created so that we may continue to improve our categorisation engine in the future.