Set Up Environment

Prerequisite

To customize your web or mobile application using Finicity’s APIs, complete the following steps.

Step 1 - Partner authentication

To access Finicity’s APIs, authenticate your partner ID and partner secret values to confirm they are valid and receive a secure access token, allowing you access to all Finicity’s API endpoints.

If you fail to authenticate after five attempts, your account locks. To get help resetting your account, contact support@finicity.com.

 

Note: 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.

Partner Authentication

POST
https://api.finicity.com/aggregation/v2/partners/authentication
Headers
Acceptapplication/json
Content-Typeapplication/json
Finicity-App-Key{{APP_KEY}}
Finicity-App-Token{{TOKEN}}
Request Body
 {

"partnerId": "PARTNER_ID",

"partnerSecret": "PARTNER_SECRET"

}
Sample Request
 curl -X POST \

--url

'https://api.finicity.com/aggregation/v2/partners/authentication' \

-H 'Finicity-App-Key: Finicity-App-Key'\

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

-H 'Accept: application/json' \

--data-raw '{

"partnerId": "PARTNER_ID",

"partnerSecret": "PARTNER_SECRET"

}'

Step 2 - Add customer

The customer record allows customers using the Connect application to log into their financial institutions. After customers add their accounts, the financial data is associated with their customer id. If you delete the customer id field, the link to their accounts gets deleted as well.

There are two APIs to add a customer.

  • If you want to test your credentials using our testing financial institutions (FI), FinBank, then use Add Test Customer.

  • If you want to add real customers to a live FI, then use Add Customer.

Add test customer

Add Test Customer

POST
https://api.finicity.com/aggregation/v2/customers/testing
Headers
Acceptapplication/json
Content-Typeapplication/json
Finicity-App-Key{{APP_KEY}}
Finicity-App-Token{{TOKEN}}
Request Body
 {

    "username": "customerusername1"

}
Sample Request
 curl -X POST \

--url

'https://api.finicity.com/aggregation/v1/customers/testing' \

-H 'Finicity-App-Token: Finicity-App-Token'\

-H 'Finicity-App-Key: Finicity-App-Key'\

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

-H 'Accept: application/json' \

--data-raw '{

"username": "customerusername1"

}'

Add customer

Add Customer

POST
https://api.finicity.com/aggregation/v2/customers/active
Headers
Acceptapplication/json
Content-Typeapplication/json
Finicity-App-Key{{APP_KEY}}
Finicity-App-Token{{TOKEN}}
Request Body
 {

"username": "USERNAME",

"applicationId": "12345"

}
Sample Request
 curl -X POST \

--url 'https://api.finicity.com/aggregation/v2/customers/active'

\

-H 'Finicity-App-Token: Finicity-App-Token'\

-H 'Finicity-App-Key: Finicity-App-Key'\

-H 'Accept: application/json'\

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

--data-raw '{

"username": "USERNAME",

"applicationId": "12345"

}'

Step 3 - Create consumer

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

Create Consumer

POST
https://api.finicity.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": "111222333",

"birthday": {

"year": 1989,

"month": 8,

"dayOfMonth": 13

},

"email": "finicity@test.com",

"suffix": "Mr",

"emailAddress": "finicity@test.com"

}
Sample Request
 curl -X POST \

--url

'https://api.finicity.com/decisioning/v1/customers/1000278253/consume

r' \

-H 'Finicity-App-Token: Finicity-App-Token'\

-H 'Finicity-App-Key: Finicity-App-Key'\

-H 'Accept: application/json'\

-H '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

},

"email": "finicity@test.com",

"suffix": "Mr",

"emailAddress": "finicity@test.com"

}'

Step 4 - Generate V2 Connect URL

The URL results of this API call to implement Connect into your web or mobile applications.There are two APIs that generate a Connect URL link, depending on which Connect features you want to use.

  • Generate V2 Connect URL (Connect Full)

    • Sign in, the user’s credentials and Multi-Factor Authentication (MFA)
    • Search for the user’s financial institutions
    • Manage the user’s accounts

  • Generate V2 Lite URL (Connect Lite)

    • Sign in, user’s credentials and Multi-Factor Authentication (MFA)
    • No user account management
    • Search for the user’s financial institutions
    • Manage the user’s accounts

Generate V2 Connect URL

Generate V2 Connect URL

POST
https://api.finicity.com/connect/v2/generate
Headers
Acceptapplication/json
Content-Typeapplication/json
Finicity-App-Key{{APP_KEY}}
Finicity-App-Token{{TOKEN}}
Request Body
 {

"partnerId": "1445585709680",

"customerId": "1005061234",

"webhook": "https://webhook.site/8d4421a7-d1d1-4f01-bb08-

5370aff0321b",

"webhookContentType": "application/json",

"experience": "default"

}
Sample Request
 curl -X POST \

--url 'https://api.finicity.com/connect/v2/generate' \

-H 'Finicity-App-Token: Finicity-App-Token'\

-H 'Finicity-App-Key: Finicity-App-Key'\

-H 'Accept: application/json' \

-H 'Content-type: application/json' \

--data-raw '{

"partnerId": "1445585709680",

"customerId": "1005061234",

"webhook": "https://webhook.site/8d4421a7-d1d1-4f01-bb08-

5370aff0321b",

"webhookContentType": "application/json",

"experience": "default"

}'

Generate V2 Lite URL (Connect Lite)

This API generates a URL for Connect Lite, which includes:

  • Sign in, user’s credentials and Multi-Factor Authentication (MFA)

  • No user account management

Generate V2 Lite URL (Connect Lite)

POST
https://api.finicity.com/connect/v2/lite
Headers
Acceptapplication/json
Content-Typeapplication/json
Finicity-App-Key{{APP_KEY}}
Finicity-App-Token{{TOKEN}}
Request Body
 {

"partnerId": "1445585709680",

"customerId": "1005061234",

"institutionId": 101723,

"webhook": "https://webhook.site/8d4421a7-d1d1-4f01-bb08-

5370aff0321b",

"webhookContentType": "application/json",

"experience": "default"

}
Sample Request
 curl -X POST \

--url 'https://api.finicity.com/connect/v2/generate/lite' \

-H 'Finicity-App-Token: Finicity-App-Token'\

-H 'Finicity-App-Key: Finicity-App-Key'\

-H 'Accept: application/json' \

-H 'Content-type: application/json' \

--data-raw '{

"partnerId": "1445585709680",

"customerId": "1005061234",

"institutionId": 101723,

"webhook": "https://webhook.site/8d4421a7-d1d1-4f01-bb08-5370aff0321b",

"webhookContentType": "application/json",

"experience": "default"

}'