Finch XP Data Intelligence Platform Getting Started

Welcome to the Finch XP API!

The Finch XP API is a powerful data intelligence solution used by leading financial services and institutions across Australia.

You can use this API to access all our products, although this documentation covers our Lending API and Personal Finance API.

The Finch XP API is built around the REST architecture and uses predictable, resource-oriented URLs. Requests are made with HTTP methods and returns JSON-encoded responses.

Base URL
https://api.finchxp.com
Schemes: https

API Overview

Data Sourcing

The FinchXP Data Intelligence platform is equipped to handle card or bank data (up to 10million transactions) from a range of data sources including:

  • Scheme providers (Amex, Eftpos, Mastercard, Visa)
  • Banks (+55 Australian banks)
  • Data aggregators (Basiq, Moneytree, Proviso/Illion, and more)
  • Open banking platforms

While we currently don’t connect directly with a Data Aggregator or Open Banking API (“Data Providers”), please contact us for our data mapping guides for each Data Provider to ensure easy integration.


Real Time vs Standard Service


Real Time Service

Real Time Service API processes up to 100 transactions per request (JSON) in less than 2 seconds. This is commonly used in cases of real-time spending/card notifications, transaction identification, and on-demand lending.

For more information on our Real Time Service, please view the Products and API Endpoints sections of this documentation.


alt text


Standard Service

Standard Service API processes up to 10 million transactions/1 million end-users per job request (JSON, XML, CSV etc.) as a scheduled overnight service, between 1-5am AEST. This is commonly used in digital banking, fintech startups, and in retail analytics.

For more information on our Standard Service, please view the Products and API Endpoints sections of this documentation.


alt text


Integration Tips


Data Retrieval

Before sending transaction data via our Data Intelligence APIs, you should first establish a connection with your Data Provider and confirm they have successfully retrieved the transaction data from the bank or financial institutions.

Data Providers will typically provide a status endpoint to confirm this step e.g. Basiq GET /users/{user.id}/jobs, will generate a “retrieve-transactions” update as either “pending” “in-progress”, “success”, or “failed”.

  • Failure to do so may lead to incomplete data intelligence, sub-optimal accuracy and integration response errors

Data Formatting

For reliable and accurate Data Intelligence, please ensure all data fields are formatted and mapped to the FinchXP APIs as described in the API Endpoints section.

  • Failure to do so may lead to incomplete data intelligence, sub-optimal accuracy and integration response errors

If you are using a Data Provider (Data Aggregator or Open Banking API) to source your data, please contact us to receive our Data Mapping Guides.

  • For your convenience, we return the original transaction ID, account ID, and user ID (as provided by your Data Provider) in our API responses if you wish to continue using these fields

Rate Limits

To ensure service stability, the Finch XP API validates request rate limits on a per API Key basis. For optimal performance, please limit requests to 5 per second to avoid sending concurrent requests that may impact API performance.

If you make an excessive amount of requests in a short period of time, the Finch XP API will respond with a HTTP 429 Too Many Requests response code.

However, this is not expected during normal use of the Finch XP API. If you have received this error, please visit our Troubleshooting Guide or contact the Finch XP support team.


Usage Plan

Every Account on the FinchXP platform is assigned to a Usage Plan. The Usage Plan consists of the product type (Lending API, PFM API, Loyalty API) processing speed (Real-time or Standard Service) and account specific features (output parameters, volume of transactions, users, etc.)

To help you start testing quickly, we’ve created a free Test Plan that you can subscribe to via our console. For more information on Test Plan limits, please see Step 5 in Quickstart Guide.

To subscribe to a "Production" Usage Plan, please request access, here. A member of the Finch XP team will approve your application.

Usage Plan Limits

For optimal security and performance, platform wide limits apply to all usage plans. These limits include:

  • Access token limit: 5 per second
  • Rate Limit: 5 per second
  • Historical data: up to 90 days
  • Accounts: 25 per user

If you exceed these limits, you will receive a 402 - Request failed error. If you have any questions regarding these limits, please contact support@finchxp.com.


Caching

As our machine learning platform is continually learning and our accuracy increases from new data every day, we discourage customers from caching lists of resources. If caching is necessary, we recommend refreshing a cached list at least daily.


Authentication

To get Finch XP API access, we need to authenticate your account using your API credentials, which you can create, view and manage in your developer console.

All requests are authenticated with an API key and Access Token through the request headers such as X-API-KEY: <apiKey> and Authorization: bearer <accessToken>. All API requests must be made over HTTPS. Requests made over plain HTTP will fail. API requests without authentication will also fail.


API Key

API Key is used as a unique identifier to authenticate and authorise access to your account. Retrieve your API Key from the developer console and enter it into the request header as X-API-KEY: <apiKey>.


Client Keys

Your Client ID/Client Secret Key is the unique identifier to your back-end application: 32-character hexadecimal strings both generated by a cryptographically-secure library. API access to our platform and your account is restricted to your unique Client ID/Secret Keys.

It is highly recommended you keep your Client ID/Secret Keys secret and safe i.e. do not share them in public areas, use them in client-side code, or in any way that could compromise their security.

If at any time you feel their security could have been compromised, please contact Finch XP and generate a new Client ID/Secret Key in your developer console.


Access Tokens

Every request you send to our API from your account requires your API Key and a signed JSON Web Token (Access Token) to be granted access.

To create an Access Token, you need to send a request to the /auth/token endpoint with your X-API-Key, clientId, and clientSecret as your digital ‘signature’.

Finch XP Access Tokens can’t be intercepted (can only be sent on HTTPS TLS 1.2 or higher), are valid for a limited time (3600 seconds), and can only be created by your unique, cryptographically generated API credentials i.e. your API Key, Client ID, and Secret Key.

Once an Access Token has expired, the Finch XP API will respond with a HTTP 401 Unauthorised response code, and you will need to request a new one.

Note: AWS generates a maximum of 5 access tokens per second. We recommend that you reuse access tokens, to avoid exceeding this limit.


Multi-factor authentication

Once in production, access to your developer console will require multi-factor authentication. This will restrict access to the email address and Australian mobile number associated with your account.


IP Whitelisting

For all production and some development accounts, we require a list of all IP addresses to be assigned to your account. API access to our platform and your account will be restricted to these IP addresses only, preventing unauthorised access.

Note, as the API credentials grant full access to your account, make sure that you store it securely and that it is not shared publicly. If your credentials are compromised, please notify the Finch XP team as soon as possible and revoke your credentials in the developer console.


See our Quickstart Guide for instructions to authenticate requests with Finch XP.

HTTP Authentication and Authorization Status Codes
Code Description
401 Possible reasons include missing Authorization: Bearer {accessToken} HTTP header, missing X-API-KEY: {apiKey} HTTP header, and expired access token.

Quickstart Guide

To get started, simply follow the instructions below on how to:

  1. Create an Account
  2. Choose a Product Plan
  3. Get API Access
  4. Select an API Testing Environment
  5. Start Testing

For easy testing and integration, we support both Swagger UI and Postman.


Step 1: Create an Account

To create an account, simply sign up to our developer console and verify your email address.

Sign up is free and we’ll immediately send you an email with an account verification link. Once you've received this email, simply click on the link and sign-in.

Please note that once in Production, sign-in will require multi-factor authentication (MFA).


Step 2: Choose a Product Plan

To select one of our data intelligence APIs, simply visit the Product Pages within the developer console and look for the "Start testing" button to subscribe to our "Testing" plan.

“Testing” plans are free and are available for both Lending and Personal Finance productType. Test data and limits are provided in Step 5.

Note: if you want to subscribe to a "Production" plan, you will need to be approved by the Finch XP team, before it is enabled on your account. To request access, please fill out the form here.


Step 3: Get API Access

Simply follow the instructions below to get API access:

  1. Create an API client: in the API Credentials page within the developer console to generate a unique clientId and clientSecret
  2. Generate an Access Token: use your X-API-Key, clientId, and clientSecret to request an Access Token from the /auth/token endpoint. Retrieve the accessToken from the response body

See our Authentication section for more information on any of the above.


Step 4: Select an API Testing environment

For easy integration, we have published Swagger and Postman collections that provide examples for all the FinchXP API endpoints.


Test using Swagger UI

To get started in Swagger UI, simply go to the Swagger UI Page in the developer console.

What is Swagger?
Swagger is an API testing tool allowing developers to execute their functional, security, and performance testing right from the OpenAPI Specifications (OAS).


Test using Postman

To get started on Postman, simply import the FinchXP Postman collection by clicking on the button below:

Run in Postman


What is Postman?
Postman is a free, powerful tool for performing integration testing with your API. It allows for repeatable, reliable tests that can be automated and used in a variety of environments.

New to Postman? Get started by following the instructions below:

  1. Download Postman.
  2. Import the FinchXP Postman collection, by clicking on the orange button above.
  3. Add the following variables to the collection by selecting the collection on the left of the Postman app, opening the View more actions (...) menu, and clicking Edit.
Variable Initial Value Current Value
productType Your_productType
X-API-Key Your_API_Key
clientID Your_clientSecret
clientSecret Your_clientSecret
  1. Generate an Access Token by calling GET token endpoint. The accessToken will automatically be added to your global environment.

If successful, you are now able to begin testing in Postman using the Real-time Service endpoint.

For more infromation on how to start testing with Postman, please watch the video below:



Step 5: Start Testing

Testing the FinchXP APIs is simple and you can use either your own real data or our test data.


Test data and limits

The FinchXP Test data consists of 100 transactions from 4 fake users with accounts at 4 fake financial institutions/banks - the non-sensitive data is publicly available from our github repository.

You are welcome to test using your own real data although testing (both fake and real data) is limited to 1000 transactions, 100 users, or 90 days: whichever is first. For security and performance reasons, we have set limits of 100 transactions per request and 3 requests per user (per day).

If you would like to test with your own data, please contact us and we’ll provide you with a list of financial institutions/banks that we support for testing.

If you would like to test with test banks from your Data Provider, please contact the FinchXP team first.

To see a full list of all financial institutions/banks we support in production, check out /api/providers


Data intelligence and formats

Data intelligence is a process that keeps evolving over time. While we maintain the highest service level guarantees of data intelligence accuracy, note that we continually analyse both national and individual spending trends, along with your user preferences, to constantly improve and maintain our algorithms and machine learning intelligence.

Therefore, you may see data intelligence we send through change overnight as our platform becomes smarter around your user’s spending habits - improving in both categorisation and transaction insight as it gathers more information.

Our APIs support multiple data formats (JSON, CSV, XML etc.) and all data channels i.e. Bank-direct, Open Banking, or via data aggregators (Basiq, Moneytree, Proviso, and Yodlee).


Parameters

To start testing, use our Real Time Service /api/finchxp endpoint specifying the productType (LENDING or PERSONAL_FINANCE) and parameters (see below) in the request body.

ExternalUser
Name Type Description
externalUserId string The unique ID used to identify your customer and their data on FinchXP. This must be defined by you.
AccountEntity
Name Type Description
providerId string The bank or financial institution of the end-user. See GET /api/providers for a list of providers and their providerIDs
externalAccountId string The account number as provided by the bank or financial institution
accountType string The type of financial account as defined by the bank or financial institution, e.g. checking, savings, loan etc
ProcessTransactionEntity
Name Type Description
externalTransactionId string The unique transaction number as defined by you, the bank or financial institution. Each transaction belongs to only one account
type enum A transaction type represents a money movement in or out of an account. CREDIT is money in, income etc.; DEBIT is money out, expense
description string The original description of the transaction as provided by the institution i.e. as it appears in the original bank statement
postDate string The posted date of the transaction as provided by the institution. Dates and times are always given in ISO 8601 format
date string The original date of the transaction as provided by the institution. Dates and times are always given in ISO 8601 format
amount number The original amount of the transaction as provided by the institution
currency string (optional) The currency of the transaction as provided by the institution, default AUD
status string (optional) The status of the transaction can be POSTED or PENDING

Error Handling

FinchXP uses conventional HTTP response codes to indicate the success or failure of a request, with supplementary error messaging as needed within response bodies.

If you encounter an error, please refer to the Common Errors section in our Troubleshooting guide.

Code Status Description
200 OK Your request was successful.
400 Bad Request Body Request failed. Please check the request body for required parameters that need to be filled or changed.
401 Unauthorised Access unauthorised. Possible reasons include missing or expired Authorization: bearer {accessToken} HTTP header, and missing X-API-KEY: {apiKey} HTTP header.
402 Request Failed The parameters were valid but the request failed. Possible reasons include usage plan limits exceeded.
403 Forbidden Access forbidden. You do not have permission to perform this request. Please check that you are subscribed to the correct usage plan.
404 Resource Not Found The requested resource doesn't exist.
429 Too Many Requests You've exceeded your throttling limits. Please limit this to 5 requests per second to avoid errors.
500 502 503 504 Server Errors An error happened in one of Finch's servers. You can check the “GET/health” endpoint to see if the server is down.
HTTP Response Codes
Code Description
2xx Status codes indicating successful requests.
4xx The data sent from the client was not sent in a way the Finch servers expects.
5xx An error happened in one of Finch's servers.

Troubleshooting

Experiencing an issue or an error? Below you will find a troubleshooting guide that should help you identify and resolve the issue before requesting additional support from the FinchXP team.

The troubleshooting guide will include:

  • Most Common Errors
  • Integration
  • API Performance
  • How to report issues

Most Common Errors


400 - Bad Request Errors


1. Are any of the required parameters missing or in incorrect format (string/enum/number)?

To validate whether the variable is required or optional, please see schema definitions here. Common problems include unspecified or invalid product_type, incorrect header/parameter name and improper date formats (see International format here)


401 - Unauthorised


1. Are the client credentials and API key valid and in the required format?

Please check for formatting errors including extra spaces, typos and follow the below requirements for the HTTP headers:

  • X-API-KEY: <apiKey>
  • Authorization: bearer <accessToken>.
2. Is the access token missing or expired?

All access tokens are valid for 3600 seconds (1 hour). Please validate that the token hasn’t expired by requesting a new token.


403 - Forbidden


1. Are you subscribed to a Test Plan or a Usage Plan?

To access the platform, you have to be subscribed to a Usage Plan. To sign up to one of our Test Plans, please check a relevant product page in the console. For more information on Usage Plans, see our documentation.

2. Are you exceeding the throttling limit for access tokens?

For security and performance, AWS generates a maximum of 5 access tokens per second. We recommend that you reuse access tokens, to avoid exceeding this limit.

3. Are you attempting to perform a request outside of your permissions or usage plan limit?

If you require extended access or would like to increase your usage plan limits, please contact support@finchxp.com.

4. Are you attempting to perform requests or activities that are breaching our Firewall rules?

Please ensure that your requests do not breach our Firewall rules or perform any unsual activity. If you require extended access, please contact support@finchxp.com.


429 - Too Many Requests


1. Are you sending too many requests?

For optimal performance, please limit requests to 5 per second to avoid sending concurrent requests.

2. Are you generating access tokens too often?

For security and performance, AWS generates a maximum of 5 access tokens per second. We recommend that you reuse access tokens, to avoid exceeding this limit.

3. Are you sending historical data that is over 90 days old?

FinchXP does not process data beyond 90 days. If you’d like to enrich historical data, please contact sales@finchxp.com for more information.

4. Are you sending duplicate data?

For optimal performance, please do not send duplicate data for enrichment.


500 - Server Error


1. Is the FinchXP server down?

Please call “GET/health” endpoint to check whether our server is down.

2. Are you sending multiple bad requests?

For transactions with bad requests, you may experience a 500 timeout error.


API Integration


1. Are you using the correct product type or would you like to switch to a different product?

Please enter the product type that you’ve subscribed to. If you’d like to switch, please contact support@finchxp.com.

2. Are you sending data from unsupported providers (banks)?

If the provider is currently not supported on the FinchXP platform, please enter the original data aggregator providerID as a placeholder and notify the FinchXP support team via support@finchxp.com. Note: Transactions from unsupported banks will be included in the enrichment process, however, results may vary.

3. Are you using test banks / test accounts?

If you’d like to test with test banks from your Data Provider, please notify the FinchXP support team via support@finchxp.com.


API Performance:


1. Did the API call return data within the expected latency?

For optimal performance, please:

  • Do not send multiple requests at the same time to avoid concurrent API processing
  • Limit requests to 5 per second
  • Do not generate a new access token for each call to avoid AWS access token throttling limit
  • Make sure you have a strong internet connection
  • Check that the request body matches the requirements. Errors will affect latency.
2. Are you sending data from unsupported providers (banks)?

When an error occurs, FinchXP returns a JSON-formatted response that contains a human-readable error message and an error code. Ensure that your code can handle all the errors that may be returned, as well as unexpected items. See the full list of errors here.


How to Report Issues


1. Would you like to report an unidentified or misidentified transaction?

Please send the request to support@finchxp.com following the structure below:

  • Problem description: please provide as much information as you can to help us quickly identify the problem.
  • Transaction id
  • Transaction description
  • Current result: what do you currently see?
  • Desired result: what would you like to see?
2. Would you like to report a bug?

Please send the request to support@finchxp.com following the structure below:

  • Error code and message (if applicable)
  • Current result: what do you currently see?
  • Desired result: what would you like to see?
3. Would you like to request a new provider?

Please send the request to support@finchxp.com specifying the provider’s name, website, bank code from your Data Provider (if applicable) and 10 transaction examples.

4. Would you like to request a new category?

Please send the request to support@finchxp.com specifying the desired parentCategory name, Category name and 10 merchant examples.

Lending API

The Lending API lets you retrieve in real-time accurate categorisation, income, and expense details to reliably verify a customer’s financial situation and make lending decisions on-demand. Real-time Lending API is supported with all data channels i.e. Bank-direct, Open Banking, or via data aggregators (Basiq, Moneytree, Proviso, and Yodlee).

Due to our accuracy and reliability, a common use-case for the Lending API is to minimise the risk of non-compliance with the responsible lending guidelines provided in RG 209 by ASIC.

There are over 200 categories carefully selected to reflect the modern, digital economy. You can find a list of our Categories in the Resources section. You can also retrieve the list using the Categories endpoint.


Responsible Lending (beta)

To assist lenders and brokers in verifying information about the customer’s financial situation and in identifying areas for further enquiry, we also return the following:

Adjustability: flags spending behaviours and lifestyle activities that could help reduce their current expenditure to afford the repayments of a loan RF Activity: flags higher risk activities (as defined in RG 209 as ‘red flags’) which may require further enquiry e.g. credit-related debts, ‘buy now, pay later’, delinquencies etc.


Specifying your product type

Once enabled on your account, you will need to specify productType: LENDING in any request. Note: Our Lending API is currently only available in real-time. For larger institutions looking for a Standard Service and overnight processing, please contact us.

Response Content-Type: application/json
Response Example
{
    "externalUserId": "U001",
    "accounts": [
      {
        "externalAccountId": "A0001",
        "providerId": "CTBA",
        "accountType": "bank"
      }
    ],
    "transactions": [
      {
        "externalAccountId": "A0001",
        "externalTransactionId": "61123",
        "type": "DEBIT",
        "description": "COLES EXPRESS 6907       CLOVERDALE   AU",
        "postDate": "2020-11-22",
        "status": "POSTED",
        "date": "2020-11-21",
        "amount": 150,
        "currency": "AUD",
        "enrichedInfo": {
          "location": {},
          "category": {
            "parentCategory": "Car & Auto",
            "category": "Petrol Stations"
          },
          "type": {
            "isAtm": false,
            "isExpense": true,
            "isBillPayment": false,
            "isOnline": false,
            "isTransfer": false,
            "isInternalTransfer": false,
            "isInternational": false
          }
        }
      }
    ]
  }

Personal Finance API

The Personal Finance API lets you retrieve accurate information around a customer’s spending to enhance the customer experience based on your bank transaction data.

In addition to over 200 categories, carefully selected to reflect the modern economy and consumer spending behaviours, we provide insightful information around every transaction, such as the merchant name (Woolworths) and location (Surry Hills, NSW 2010).

COVID-19 Update: due to the deteriorating financial situation of millions of Australians, financial literacy is more important than ever. To help support your customers through this time, the Personal Finance API will be available free for a limited time.

A common use-case for the Personal Finance API is to provide customers with more information around their spending activity and behaviours, helping to promote financial literacy and well-being.


Specifying your product type

Once enabled on your account, you will need to specify productType: PERSONAL_FINANCE in any request. Note: Our Personal Finance API is currently only available as a standard-service. For banks or larger institutions looking for Personal Finance or Digital Banking in real-time, please contact us.

Response Content-Type: application/json
Response Example
{
    "externalUserId": "U001",
    "accounts": [
      {
        "externalAccountId": "A0001",
        "providerId": "CTBA",
        "accountType": "bank"
      }
    ],
    "transactions": [
      {
        "externalAccountId": "A0001",
        "externalTransactionId": "61123",
        "type": "DEBIT",
        "description": "COLES EXPRESS 6907       CLOVERDALE   AU",
        "postDate": "2020-11-22",
        "status": "POSTED",
        "date": "2020-11-21",
        "amount": 150,
        "currency": "AUD",
        "enrichedInfo": {
          "name": "Coles Express",
          "location": {
            "suburb": "Cloverdale",
            "state": "WA",
            "postcode": "6105"
          },
          "category": {
            "parentCategory": "Car & Auto",
            "category": "Petrol Stations"
          },
          "type": {
            "isAtm": false,
            "isExpense": true,
            "isBillPayment": false,
            "isOnline": false,
            "isTransfer": false,
            "isInternalTransfer": false,
            "isInternational": false
          }
        }
      }
    ]

Authentication

Generate access token

POST /auth/token

Every request you send to our API from your account requires your API Key and a signed JSON Web Token (Access Token) to be granted access. To create an Access Token, you need to send a request to the /auth/token endpoint with your API Credentials i.e. your X-API-Key in the HTTP header, with clientId and clientSecret as the parameters. If you provided the correct parameters, you should get a successful response with an accessToken that is valid for a limited time. The API credentials can be found in your developer console.

Enter your clientId and clientSecret into the request body.

Request Content-Types: application/json
Request Example
{
  "clientId": "string",
  "clientSecret": "string"
}
200 Success

Generate the Access token from the response and enter it into the HTTP Authorization header as a bearer <token>.

Response Content-Types: application/json
Response Example (200 Success )
{
  "accessToken": "string"
}

Standard Service

Create a job

POST /api/jobs

This endpoint is for customers in production requiring overnight data intelligence on up to 1 million end-users or 10 million transactions per job e.g. personal finance, retail analytics, and digital banking.

Please specify your productType.

Request Content-Types: application/json
Request Example
{
  "contentType": "string",
  "format": "string",
  "processingType": "string",
  "productType": "LENDING",
  "expiresIn": 86400,
  "notifiedWebhook": "https://yourapp.com/hooks/app/?",
  "notifiedEmail": "client@clientemail.com"
}
200 Success

You have now created pre-signed URLs to begin uploading your data.

Response Content-Types: application/json
Response Example (200 Success )
{
  "id": "000091cd-68ba-40fa-8594-6e1e04929375",
  "status": "successful",
  "signedPutUrl": "url",
  "signedGetUrl": "url",
  "processingType": "STANDARD",
  "productType": "LENDING",
  "signedPutUrlExpiresAt": "2020-11-21T00:00:00Z",
  "created": "2020-11-21T00:00:00Z",
  "modified": "2020-11-21T00:00:00Z",
  "noOfInputTransactions": 1000,
  "noOfProcessedTransactions": 1000,
  "noOfUniqueUsers": 100
}

Complete upload

POST /api/jobs/completeUpload

Use this endpoint to indicate you have finished uploading all data in your job in order for us to begin running data intelligence.

The unique Job ID returned in the response body when you created the job.

Request Content-Types: application/json
Request Example
{
  "id": "string"
}
200 OK

Receive your presigned output URL.

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "000091cd-68ba-40fa-8594-6e1e04929375",
  "status": "successful",
  "signedPutUrl": "url",
  "signedGetUrl": "url",
  "processingType": "STANDARD",
  "productType": "LENDING",
  "signedPutUrlExpiresAt": "2020-11-21T00:00:00Z",
  "created": "2020-11-21T00:00:00Z",
  "modified": "2020-11-21T00:00:00Z",
  "noOfInputTransactions": 1000,
  "noOfProcessedTransactions": 1000,
  "noOfUniqueUsers": 100
}

Job Status

POST /api/jobs/details/:id

This endpoint is for customers in production to track the status of their jobs. Once the job is complete, you will be able to download it using the presigned output URL. You will also receive the email/webhook notification. Standard jobs for data intelligence processing are completed between 1-5am AEST.

For faster processing services, please contact our sales team.

id: string
in path

The unique Job ID returned in the response body when you created the job.

withSignedUrl: boolean
in query

Whether a signed URL for upload/download the job should be included (depending on the job status)

signedUrlExpiry: number
in query

Expiry required for the signed URL in seconds

200 OK

Details of submitted job

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "000091cd-68ba-40fa-8594-6e1e04929375",
  "status": "successful",
  "signedPutUrl": "url",
  "signedGetUrl": "url",
  "processingType": "STANDARD",
  "productType": "LENDING",
  "signedPutUrlExpiresAt": "2020-11-21T00:00:00Z",
  "created": "2020-11-21T00:00:00Z",
  "modified": "2020-11-21T00:00:00Z",
  "noOfInputTransactions": 1000,
  "noOfProcessedTransactions": 1000,
  "noOfUniqueUsers": 100
}

Real Time Service

Process transactions by user

POST /api/finchxp/transactions/user/{externalUserId}

This endpoint is for testing and for customers in production requiring advanced data intelligence in real-time e.g. on-demand lending, personal finance alerts/notifications, and more.

externalUserId: string
in path

The unique ID used to identify your customer and their data on FinchXP. This must be defined by you.

Request Content-Types: application/json
Request Example
{
  "accounts": [
    {
      "externalAccountId": "123823834",
      "accountType": "Savings",
      "providerId": "CTBA"
    }
  ],
  "transactions": [
    {
      "externalAccountId": "123823834",
      "externalTransactionId": "82394238",
      "externalUserId": "U0001",
      "description": "FRESH AND FAIR PTY L NEWPORT NS AUS Tap and Pay xx1234 Value Date_ 01/05/2020",
      "postDate": "2020-06-01",
      "date": "2020-06-01",
      "amount": "150.00",
      "currency": "AUD",
      "status": "POSTED",
      "type": "DEBIT"
    }
  ],
  "productType": "LENDING"
}

Data Intelligence and information provided in your response will vary depending on your productType and specific plan.

Response Content-Types: application/json
Response Example (200 OK)
{
  "externalUserId": "U001",
  "accounts": [
    {
      "externalAccountId": "123823834",
      "accountType": "Savings",
      "providerId": "CTBA"
    }
  ],
  "transactions": [
    {
      "externalAccountId": "123823834",
      "externalTransactionId": "82394238",
      "description": "FRESH AND FAIR PTY L NEWPORT NS AUS Tap and Pay xx1234 Value Date_ 01/05/2020",
      "postDate": "2020-06-03",
      "date": "2020-06-01",
      "amount": "150.00",
      "currency": "AUD",
      "status": "POSTED",
      "type": "DEBIT",
      "enrichedInfo": {
        "name": "Charli's Cafe",
        "location": {
          "address": "19 Robertson Road",
          "suburb": "Newport",
          "state": "NSW",
          "postcode": "2106"
        },
        "category": {
          "parentCategory": "Food & Drink",
          "category": "Fast Food Restaurant"
        },
        "type": {
          "isAtm": false,
          "isExpense": true,
          "isBillPayment": true,
          "isOnline": false,
          "isTransfer": false,
          "isInternalTransfer": false,
          "isInternational": false
        }
      }
    }
  ]
}

Common

List Providers

GET /api/finchxp/providers
200 OK

Complete list of financial institutions and banks that you can upload your data from (either direct or via data aggregators) and we can support with data intelligence services. The providerId is a required paramater when sending an API request. If the provider is currently not on the list, please enter the original data aggregator providerID as a placeholder and notify us at support@finchxp.com

Response Content-Types: application/json
Response Example (200 OK)
{
  "providers": [
    {
      "providerId": "CTBA",
      "providerName": "Commonwealth Bank of Australia"
    }
  ]
}

List Categories

GET /api/finchxp/categories

Complete list of our parent categories and 200+ categories we support in production.

200 OK

Complete list of Finch XP categories.

Response Content-Types: application/json
Response Example (200 OK)
{
  "Categories": [
    {
      "parentCategory": "Food & Drink",
      "category": "Fast Food Restaurant"
    }
  ]
}

Get Service Health

GET /api/health

ServiceHealthModel

Response Content-Types: application/json
Response Example (200 OK)
{
  "services": {
    "database": "boolean"
  },
  "isOK": "boolean",
  "serverTimestamp": "number"
}

Schema Definitions

AuthTokenAuthRequest: object

clientId: string
clientSecret: string
Example
{
  "clientId": "string",
  "clientSecret": "string"
}

JwtTokenResponse: object

accessToken: string
Example
{
  "accessToken": "string"
}

AccountEntity: object

externalAccountId: string

The account number of your customer. This can be defined by you or you can pass through the account number provided by the bank or financial institution.

accountType: string

The type of financial account as defined by the bank or financial institution, e.g. checking, savings, loan etc.

providerId: string

The bank or financial institution where this data is from i.e. where your customer holds an account. See GET /api/providers for a list of providers and their providerIDs.

Example
{
  "externalAccountId": "123823834",
  "accountType": "Savings",
  "providerId": "CTBA"
}

ProcessTransactionEntity: object

externalAccountId: string

The account number of your customer. This can be defined by you or you can pass through the account number provided by the bank or financial institution.

externalTransactionId: string

The unique transaction number of your customer. This can be defined by you or you can pass through the transaction number provided by the bank or financial institution.

externalUserId: string

The unique ID used to identify your customer and their data on FinchXP. This must be defined by you.

description: string

The original description of the transaction as provided by the bank or financial institution i.e. as it appears in the original bank statement or raw transaction description.

postDate: string (date-time)

The posted date of the transaction as provided by the bank or financial institution. Dates and times must always be given in ISO 8601 format.

date: string (date-time)

The original date of the transaction as provided by the bank or financial institution. Dates and times must always be given in ISO 8601 format.

amount: number

The original amount of the transaction as provided by the bank or financial institution.

currency: string

The currency of the transaction as provided by the bank or financial institution, default AUD

status: string POSTED, PENDING

The status of the transaction can be POSTED or PENDING

type: string CREDIT, DEBIT

The type of transaction in or out of an account i.e. CREDIT is money in to an account (income) whereas DEBIT is money out of an account (expense).

Example
{
  "externalAccountId": "123823834",
  "externalTransactionId": "82394238",
  "externalUserId": "U0001",
  "description": "FRESH AND FAIR PTY L NEWPORT NS AUS Tap and Pay xx1234 Value Date_ 01/05/2020",
  "postDate": "2020-06-01",
  "date": "2020-06-01",
  "amount": "150.00",
  "currency": "AUD",
  "status": "POSTED",
  "type": "DEBIT"
}

ProcessTransactionsContainer: object

accounts: AccountEntity

List of accounts

AccountEntity
transactions: ProcessTransactionEntity

List of transactions to process

ProcessTransactionEntity
productType: string LENDING, PERSONAL_FINANCE, LOYALTY
Example
{
  "accounts": [
    {
      "externalAccountId": "123823834",
      "accountType": "Savings",
      "providerId": "CTBA"
    }
  ],
  "transactions": [
    {
      "externalAccountId": "123823834",
      "externalTransactionId": "82394238",
      "externalUserId": "U0001",
      "description": "FRESH AND FAIR PTY L NEWPORT NS AUS Tap and Pay xx1234 Value Date_ 01/05/2020",
      "postDate": "2020-06-01",
      "date": "2020-06-01",
      "amount": "150.00",
      "currency": "AUD",
      "status": "POSTED",
      "type": "DEBIT"
    }
  ],
  "productType": "LENDING"
}

MerchantLocation: object

address: string
suburb: string
state: string
postcode: string
Example
{
  "address": "19 Robertson Road",
  "suburb": "Newport",
  "state": "NSW",
  "postcode": "2106"
}

EnrichedInfo: object

name: string
location: MerchantLocation
category: Category
type: ParsedTransactionType
Example
{
  "name": "Charli's Cafe",
  "location": {
    "address": "19 Robertson Road",
    "suburb": "Newport",
    "state": "NSW",
    "postcode": "2106"
  },
  "category": {
    "parentCategory": "Food & Drink",
    "category": "Fast Food Restaurant"
  },
  "type": {
    "isAtm": false,
    "isExpense": true,
    "isBillPayment": true,
    "isOnline": false,
    "isTransfer": false,
    "isInternalTransfer": false,
    "isInternational": false
  }
}

ProcessedUserTransactionsEntity: object

externalAccountId: string
externalTransactionId: string
description: string
postDate: date
date: date
amount: number
currency: string
status: string
type: string
enrichedInfo: EnrichedInfo
Example
{
  "externalAccountId": "123823834",
  "externalTransactionId": "82394238",
  "description": "FRESH AND FAIR PTY L NEWPORT NS AUS Tap and Pay xx1234 Value Date_ 01/05/2020",
  "postDate": "2020-06-03",
  "date": "2020-06-01",
  "amount": "150.00",
  "currency": "AUD",
  "status": "POSTED",
  "type": "DEBIT",
  "enrichedInfo": {
    "name": "Charli's Cafe",
    "location": {
      "address": "19 Robertson Road",
      "suburb": "Newport",
      "state": "NSW",
      "postcode": "2106"
    },
    "category": {
      "parentCategory": "Food & Drink",
      "category": "Fast Food Restaurant"
    },
    "type": {
      "isAtm": false,
      "isExpense": true,
      "isBillPayment": true,
      "isOnline": false,
      "isTransfer": false,
      "isInternalTransfer": false,
      "isInternational": false
    }
  }
}

ProcessedTransactionsResponse: object

externalUserId: string
accounts: AccountEntity
AccountEntity
transactions: ProcessedUserTransactionsEntity

List of processed transactions

ProcessedUserTransactionsEntity
Example
{
  "externalUserId": "U001",
  "accounts": [
    {
      "externalAccountId": "123823834",
      "accountType": "Savings",
      "providerId": "CTBA"
    }
  ],
  "transactions": [
    {
      "externalAccountId": "123823834",
      "externalTransactionId": "82394238",
      "description": "FRESH AND FAIR PTY L NEWPORT NS AUS Tap and Pay xx1234 Value Date_ 01/05/2020",
      "postDate": "2020-06-03",
      "date": "2020-06-01",
      "amount": "150.00",
      "currency": "AUD",
      "status": "POSTED",
      "type": "DEBIT",
      "enrichedInfo": {
        "name": "Charli's Cafe",
        "location": {
          "address": "19 Robertson Road",
          "suburb": "Newport",
          "state": "NSW",
          "postcode": "2106"
        },
        "category": {
          "parentCategory": "Food & Drink",
          "category": "Fast Food Restaurant"
        },
        "type": {
          "isAtm": false,
          "isExpense": true,
          "isBillPayment": true,
          "isOnline": false,
          "isTransfer": false,
          "isInternalTransfer": false,
          "isInternational": false
        }
      }
    }
  ]
}

MerchantDetails: object

name: string
location: MerchantLocation
Example
{
  "name": "Charli's Cafe",
  "location": {
    "address": "19 Robertson Road",
    "suburb": "Newport",
    "state": "NSW",
    "postcode": "2106"
  }
}

ParsedTransactionType: object

isAtm: boolean
isExpense: boolean
isBillPayment: boolean
isOnline: boolean
isTransfer: boolean
isInternalTransfer: boolean
isInternational: boolean
Example
{
  "isAtm": false,
  "isExpense": true,
  "isBillPayment": true,
  "isOnline": false,
  "isTransfer": false,
  "isInternalTransfer": false,
  "isInternational": false
}

ParsedTransaction: object

id: string
userId: string
transactionDescription: string
transactionType: string
amount: number
currency: string
merchant: MerchantDetails
category: string
parentCategory: string
types: ParsedTransactionType
valueDate: string (date-time)
Example
{
  "id": "82394238",
  "userId": "U0001",
  "transactionDescription": "FRESH AND FAIR PTY L NEWPORT NS AUS Tap and Pay xx1234 Value Date_ 01/05/2020",
  "transactionType": "DEBIT",
  "amount": "150.00",
  "currency": "AUD",
  "merchant": {
    "name": "Charli's Cafe",
    "location": {
      "address": "19 Robertson Road",
      "suburb": "Newport",
      "state": "NSW",
      "postcode": "2106"
    }
  },
  "category": "Cafe & Coffee Shops",
  "parentCategory": "Food & Drink",
  "types": {
    "isAtm": false,
    "isExpense": true,
    "isBillPayment": true,
    "isOnline": false,
    "isTransfer": false,
    "isInternalTransfer": false,
    "isInternational": false
  },
  "valueDate": "2020-05-01"
}

MultipleTransactionParseResponse: object

Example
{
  "transactions": [
    {
      "id": "82394238",
      "userId": "U0001",
      "transactionDescription": "FRESH AND FAIR PTY L NEWPORT NS AUS Tap and Pay xx1234 Value Date_ 01/05/2020",
      "transactionType": "DEBIT",
      "amount": "150.00",
      "currency": "AUD",
      "merchant": {
        "name": "Charli's Cafe",
        "location": {
          "address": "19 Robertson Road",
          "suburb": "Newport",
          "state": "NSW",
          "postcode": "2106"
        }
      },
      "category": "Cafe & Coffee Shops",
      "parentCategory": "Food & Drink",
      "types": {
        "isAtm": false,
        "isExpense": true,
        "isBillPayment": true,
        "isOnline": false,
        "isTransfer": false,
        "isInternalTransfer": false,
        "isInternational": false
      },
      "valueDate": "2020-05-01"
    }
  ]
}

JobCreateRequestModel: object

contentType: string text/csv, text/tab-separated-values, application/x-lzop, application/json, application/gzip, application/x-snappy-framed
format: string CSV, TSV, JSON, ORC, PARQUET
processingType: string standard, expedited
productType: string LENDING, PERSONAL_FINANCE, LOYALTY
expiresIn: number
notifiedWebhook: string
notifiedEmail: string
Example
{
  "contentType": "string",
  "format": "string",
  "processingType": "string",
  "productType": "LENDING",
  "expiresIn": 86400,
  "notifiedWebhook": "https://yourapp.com/hooks/app/?",
  "notifiedEmail": "client@clientemail.com"
}

JobModel: object

id: string
status: string
signedPutUrl: string
signedGetUrl: string
processingType: string STANDARD, EXPEDITED
productType: string LENDING, PERSONAL_FINANCE, LOYALTY
signedPutUrlExpiresAt: string (date-time)
created: string (date-time)
modified: string (date-time)
noOfInputTransactions: number
noOfProcessedTransactions: number
noOfUniqueUsers: number
Example
{
  "id": "000091cd-68ba-40fa-8594-6e1e04929375",
  "status": "successful",
  "signedPutUrl": "url",
  "signedGetUrl": "url",
  "processingType": "STANDARD",
  "productType": "LENDING",
  "signedPutUrlExpiresAt": "2020-11-21T00:00:00Z",
  "created": "2020-11-21T00:00:00Z",
  "modified": "2020-11-21T00:00:00Z",
  "noOfInputTransactions": 1000,
  "noOfProcessedTransactions": 1000,
  "noOfUniqueUsers": 100
}

JobCompleteUploadModel: object

id: string
Example
{
  "id": "string"
}

ServicesStatus: object

database: boolean
Example
{
  "database": "boolean"
}

Category: object

parentCategory: string
category: string
Example
{
  "parentCategory": "Food & Drink",
  "category": "Fast Food Restaurant"
}

Provider: object

providerId: string
providerName: string
Example
{
  "providerId": "CTBA",
  "providerName": "Commonwealth Bank of Australia"
}

Providers: object

providers: Provider
Provider
Example
{
  "providers": [
    {
      "providerId": "CTBA",
      "providerName": "Commonwealth Bank of Australia"
    }
  ]
}

Categories: object

Categories: Category
Category
Example
{
  "Categories": [
    {
      "parentCategory": "Food & Drink",
      "category": "Fast Food Restaurant"
    }
  ]
}

ServiceHealthModel: object

services: ServicesStatus
isOK: boolean
serverTimestamp: number
Example
{
  "services": {
    "database": "boolean"
  },
  "isOK": "boolean",
  "serverTimestamp": "number"
}