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://TaleFin.io/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.