TaleFin Home

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.


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:


This endpoint accepts the following information:

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

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:

2  "full_name": "Donald Duck",
3  "email": "test@test.com",
4  "phone": 040000000,
5  "bank_id": 130,
6  "analysis": true

You can replace "analysis": true, with any option from above, or even extend it to include several different options. For example;

2  "full_name": " Donald Duck",
3  "email": "test@test.com",
4  "phone": 040000000,
5  "bank_id": 130,
6  "analysis": true,
7  "account_owner": true

For the bank_id, you can get a list of the most up to date supported banks from this endpoint:


In 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:

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"

Using this UUID you can now poll to collect updates and inputs required by the bank crawler:


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.

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": []

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:

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  }

Using this information, we can view the fruits of our labour, in HTML:


in JSON:


or PDF:


Error Handling

You can view an exhaustive list of all the possible errors and warnings that could occur by visiting the error docs.

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:


This endpoint has been simplified for the user, so now all that is required is your JSON payload and a bank ID. The default payload looks like this:

2  "accounts": null,
3  "bank": null,
4  "analyse_now": false,
5  "detect_dishonours": false,
6  "days_to_retrieve": null,
7  "days_to_display": null

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. Currently the only supported JSON type is a Plaid asset file, but other types will be added in the future.

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.

After a successful POST, you will receive a response that will look something like this:

2  "application_id": 123456,
3  "profile_id": 98765,
4  "vendor_label": "{vendor_label}",
5  "vendor_specific_id": "{vendor_specific_id}"

You can then view your application running at:


Start Now

Subscribe to our newsletters

Subscribe to our newsletter and stay up to date with the latest news about TaleFin.

TaleFin Home© Copyright 2024 TaleFin Australia Pty Ltd. ABN 71 632 551 770