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.

System flow diagram

Finicity provides 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: Sends 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.

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.

  • 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
Acceptapplication/json
Content-Typeapplication/json
Finicity-App-Key{{APP_KEY}}
Request Body (application/json)
 {
"partnerId": "PARTNER_ID",
"partnerSecret": "PARTNER_SECRET"
}

Example Request

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
Acceptapplication/json
Content-Typeapplication/json
Finicity-App-Key{{APP_KEY}}
Finicity-App-Token{{TOKEN}}
Request Body
 {
"username": "customerusername1",
"firstName: "FIRST_NAME",
"lastName: "LAST_NAME"
}

Example Request

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
Acceptapplication/json
Content-Typeapplication/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

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
Acceptapplication/json
Content-Typeapplication/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

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"
}'