Get Started

Learn about Finicity Connect and set up your environment to access the Finicity APIs.

Overview

The Finicity Connect application is the foundation that allows your customers to grant Finicity authorization and use of their account credentials to access their financial data. Using our network of financial institutions, covering 95% of the market, Connect downloads all relevant data from the customer’s accounts to build your data and analytics. The customer can also log in and view their account information, send electronic payments, apply for loans, request financial reports, and more.

Finicity provides you with the following Connect development tools and technical capabilities:

Free access to our API endpoints.
Connect supports the TSP protocol or the OAuth service to secure user credentials when accessing information from your financial institution.
Integrate Connect anywhere within your web or mobile applications using an iFrame or new window.
Connect SDK resources for both web and mobile applications.
Connect can send webhook events to indicate the customer’s progress as they navigate through the Connect application.
Webhook events can feed into Google Analytics and Adobe Analytics.

Finicity’s Partner API Keys

The Finicity’s Connect APIs are free and available to any partner who signs up for an account on the Finicity Developer Portal. The keys you receive are unique to your partner account.

Partner ID and Partner Secret: Sent to the Partner Authentication service to obtain a token for accessing the APIs.
- The token is valid for two hours and is required on all calls to the Finicity APIs.
- As a best practice, use a single token for all calls. Assign a timestamp for each token, and then check the current timestamp before making any calls. If the token is greater than 90 minutes, generate a new one.
Finicity-App-Key: Required on all calls to the Finicity APIs to identify your application.

Get Partner API Keys

The Test Drive account only allows you to add test customer data until you upgrade to a paid plan, then you can add your real customer’s data to your financial institution.

1
Go to the Finicity Developer Portal and sign up for a free Test Drive account.
2
Go to the Developer Portal Login page, log in with your test drive credentials and get your partner API keys.

Set Up Environment

To start customizing your web or mobile application using Finicity’s APIs, do the following:

Complete Steps 1-4

Step 1—Authenticate Partner API Keys

To access Finicity’s APIs, authenticate your partner API keys to confirm they are valid, and to receive a secure access token giving you access to Finicity’s API endpoints.

The token is required for all API calls.
The token is valid for a two-hour time period.
As a best practice, use a single token for all calls. Assign a timestamp for each token, and then check the current timestamp before making any calls. If the token is greater than 90 minutes, generate a new one.
After five failed attempts to authenticate, your account is locked. Contact support@finicity.com to get help resetting your account.

Computers accessing Finicity’s APIs must use Transport Layer Security (TLS) protocol 1.2 or later and must reside within the United States or Canada.

Authenticate


POST
https://api.finicity.com/aggregation/v2/partners/authentication

Headers
Accept	application/json
Content-Type	application/json
Finicity-App-Key	{{APP_KEY}}

Request Body (application/json)

 {

  "partnerId": "PARTNER_ID",

  "partnerSecret": "PARTNER_SECRET"

}

Example Request

 curl -X POST '{{API_BASE_URL}}/aggregation/v2/partners/authentication' \ 

--header 'Accept: application/json' \ 

--header 'Content-Type: application/json' \ 

--header 'Finicity-App-Key: {{APP_KEY}}' \ 

--data-raw '{"partnerId": "{{PARTNER_ID}}", "partnerSecret": "{{PARTNER_SECRET}}"}'

Step 2—Create a Customer

The customer record allows the customer to use Connect to log in to their financial institutions. After the customer links to their financial accounts, the financial data is associated with the customer id. If you delete the customer id field, the link to their accounts is deleted as well.

Create Customer


POST
https://api.finicity.com/aggregation/v1/customers/testing

Headers
Accept	application/json
Content-Type	application/json
Finicity-App-Key	{{APP_KEY}}
Finicity-App-Token	{{TOKEN}}

Request Body

 {

   "username": "customerusername1",

   "firstName: "FIRST_NAME",

   "lastName: "LAST_NAME"

}

Example Request

 curl -X POST '{{API_BASE_URL}}/aggregation/v1/customers/testing' \

--header 'Finicity-App-Key: Finicity-App-Key' \

--header 'Finicity-App-Token: Finicity-App-Token' \

--header 'Content-Type: application/json' \

--header 'Accept: application/json' \

--data-raw '{

"username": "customerusername1",

"firstName": "FIRST_NAME",

"lastName": "LAST_NAME"

}'

Step 3—Create a Consumer

The consumer record is only required if the customer or lender is using Finicity’s Credit Decisioning products.

Create Consumer


POST
https://api.finicty.com/decisioning/v1/customers/{{CUSTOMER_ID}}/consumer

Headers
Accept	application/json
Content-Type	application/json
Finicity-App-Key	{{APP_KEY}}
Finicity-App-Token	{{TOKEN}}

Request Body

 {

  "firstName": "John",

  "lastName": "Smith",

  "address": "434 W Ascension Way",

  "city": "Murray",

  "state": "UT",

  "zip": "84123",

  "phone": "6786786786",

  "ssn": "*****2222",

  "birthday": {

    "year": 1989,

    "month": 8,

    "dayOfMonth": 13

}

Example Request

 curl -X POST '{{API_BASE_URL}}/decisioning/v1/customers/1000278253/consumer' \

--header 'Finicity-App-Token: {{TOKEN}}'\

--header 'Finicity-App-Key: {{APP_KEY}}'\

--header 'Accept: application/json'\

--header 'Content-Type: application/json' \

  --data-raw '{

  "firstName": "John",

  "lastName": "Smith",

  "address": "434 W Ascension Way",

  "city": "Murray",

  "state": "UT",

  "zip": "84123",

  "phone": "6786786786",

  "ssn": "111222333",

  "birthday": {

    "year": 1989,

    "month": 8,

    "dayOfMonth": 13

  }

}'

Step 4—Generate a Connect URL

The Connect URL lets you integrate Connect anywhere you want within your web or mobile application.

Generate Connect URL


POST
https://api.finicity.com/connect/v1/generate

Headers
Accept	application/json
Content-Type	application/json
Finicity-App-Key	{{APP_KEY}}
Finicity-App-Token	{{TOKEN}}

Request Body (application/json)

 {

    "partnerId": "{{PARTNER_ID}}",

    "customerId": "{{CUSTOMER_ID}}",

    "consumerId": "{{CONSUMER_ID}}",

    "type": "voa"

}

Example Request

 curl -X POST '{{CONNECT_BASE_URL}}/connect/v1/generate' \ 

--header 'Accept: application/json' \ 

--header 'Finicity-App-Key: {{APP_KEY}}' \ 

--header 'Finicity-App-Token: {{TOKEN}}' \ 

--header 'Content-Type: application/json' \ 

--data-raw '{ 

     "partnerId": "{{PARTNER_ID}}", 

     "customerId": "{{CUSTOMER_ID}}", 

     "consumerId": "{{CONSUMER_ID}}", "type": "voa"

 }'