Set Up Environment
Prerequisite
- Get Started – Get Free API Keys
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.
POST
https://api.finicity.com/aggregation/v2/partners/authentication
Accept | application/json |
Content-Type | application/json |
Finicity-App-Key | {{APP_KEY}} |
{
"partnerId": "PARTNER_ID",
"partnerSecret": "PARTNER_SECRET"
}
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
POST
https://api.finicity.com/aggregation/v2/customers/testing
Accept | application/json |
Content-Type | application/json |
Finicity-App-Key | {{APP_KEY}} |
Finicity-App-Token | {{TOKEN}} |
{
"username": "customerusername1"
}
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
POST
https://api.finicity.com/aggregation/v2/customers/active
Accept | application/json |
Content-Type | application/json |
Finicity-App-Key | {{APP_KEY}} |
Finicity-App-Token | {{TOKEN}} |
{
"username": "USERNAME",
"applicationId": "12345"
}
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"
}'
See Add Customer API
Step 3 - Create consumer
The consumer record is only required if the customer or lender is using Finicity’s Credit Decisioning products.
POST
https://api.finicity.com/decisioning/v1/customers/{CUSTOMER ID}/consumer
Accept | application/json |
Content-Type | application/json |
Finicity-App-Key | {{APP_KEY}} |
Finicity-App-Token | {{TOKEN}} |
{
"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
},
"suffix": "Mr"
}
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
When you call one of the Generate 2.0 Connect URL APIs, the response returns a URL link that you use to implement Connect in your own web or mobile applications. Depending on which Connect features you want, choose one of the following APIs to generate a URL link.
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
Send V2 Connect Email
- Send an email to the consumer that includes a Connect URL link. The email includes a button that opens the Connect application.
Generate V2 Connect URL
POST
https://api.finicity.com/connect/v2/generate
Accept | application/json |
Content-Type | application/json |
Finicity-App-Key | {{APP_KEY}} |
Finicity-App-Token | {{TOKEN}} |
{
"partnerId": "1445585709680",
"customerId": "1005061234",
"webhook": "https://webhook.site/8d4421a7-d1d1-4f01-bb08-
5370aff0321b",
"webhookContentType": "application/json",
"experience": "default"
}
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
POST
https://api.finicity.com/connect/v2/generate/lite
Accept | application/json |
Content-Type | application/json |
Finicity-App-Key | {{APP_KEY}} |
Finicity-App-Token | {{TOKEN}} |
{
"partnerId": "1445585709680",
"customerId": "1005061234",
"institutionId": 101723,
"webhook": "https://webhook.site/8d4421a7-d1d1-4f01-bb08-
5370aff0321b",
"webhookContentType": "application/json",
"experience": "default"
}
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"
}'
Send V2 Connect Email
This API is used to send an email to the consumer that includes a Connect link. The email includes a button that opens the Connect application.
POST
https://api.finicity.com/connect/v2/send/email
Accept | application/json |
Content-Type | application/json |
Finicity-App-Key | {{APP_KEY}} |
Finicity-App-Token | {{TOKEN}} |
{
"partnerId": "1445585709680",
"customerId": "1005061234",
"consumerId": "86238nvnw7269e224a4e3de12352d87d",
"type": "voa",
"webhook": "https://webhook.site/8d4421a7-d1d1-4f01-bb08-5370aff0321b",
"webhookContentType": "application/json",
"email": {
"to": "fin.user@finicity.com",
"supportPhone": "800-555-5555",
"subject": "Verify your income",
"firstName": "Bob",
"brandColor": "#4287f5",
"brandLogo": "https://acme-lending.com/logo.png",
"institutionName": "Acme Lending",
"institutionAddress": "222 Winipeg Drive SLC UT, 84109",
"signature": [
"Cindy Mayfield",
"Senior Loan Officer",
"Direct 123-456-7890"
]
},
"experience": "default",
"fromDate": 12345678,
"reportCustomFields": [
{
"label": "loanID",
"value": "12345",
"shown": true
},
{
"label": "branchID",
"value": "55555",
"shown": false
}
]
}
curl -X POST \
--url 'https://api.finicity.com/connect/v2/send/email' \
-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",
"consumerId": "86238nvnw7269e224a4e3de12352d87d",
"webhook": "https://webhook.site/8d4421a7-d1d1-4f01-bb08-5370aff0321b",
"webhookContentType": "application/json",
"email": {
"to": "fin.user@finicity.com",
"supportPhone": "800-555-5555",
"subject": "Verify your income",
"firstName": "Bob",
"institutionName": "Acme Lending",
"institutionAddress": "222 Winipeg Drive SLC UT, 84109",
"signature": [
"Cindy Mayfield",
"Senior Loan Officer",
"Direct 123-456-7890"
]
},
"experience": "default",
"fromDate": 12345678,
"reportCustomFields": [
{
"label": "loanID",
"value": "12345",
"shown": true
},
{
"label": "branchID",
"value": "55555",
"shown": false
}
]
}'
See also: