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.

Partner Authentication


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

Headers

Accept	application/json
Content-Type	application/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"

}'

See Partner Authentication API

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

Accept	application/json
Content-Type	application/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"

}'

See Add Testing Customer API

Add customer

Add Customer


POST
https://api.finicity.com/aggregation/v2/customers/active

Headers

Accept	application/json
Content-Type	application/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"

}'

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.

Create Consumer


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

"birthday": {

"year": 1989,

"month": 8,

"dayOfMonth": 13

},

"suffix": "Mr"

}

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"

}'

See Create Consumer API

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

Headers

Accept	application/json
Content-Type	application/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"

}'

See Generate V2 Connect URL (Connect Full) API

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/generate/lite

Headers

Accept	application/json
Content-Type	application/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"

}'

See Generate V2 Lite Connect URL API

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

Accept	application/json
Content-Type	application/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

    }

  ]

}'

See Send V2 Connect Email API

See also: