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

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

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 Curl 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"

}'

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.

Send Connect Email

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

  "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

    }

  ]

}
Sample Curl Request
 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

    }

  ]

}'