Quick Start Guide

TIME TO COMPLETE: 30 MINUTES


Overview

Follow this guide to:

  • Introduce yourself to Connect and the foundational Finicity APIs

  • Get access to series of high-quality data from our Test Drive

  • Explore and test all APIs using our Postman collection

  • Generate API client libraries from our API specification

Applications accessing the Finicity APIs must be hosted within the United States or Canada.

1. Generate Your Credentials

As a first step, sign up for a developer account on the Finicity Developer Portal and create your API credentials. These will give you access to our Test Drive and test banks (FinBanks) until you are ready to upgrade to a paid plan with live financial institutions and real customers.

For that:

  • 1

    Navigate to the Sign Up page

  • 2

    Click Test Drive and follow the step-by-step instructions

  • 3

    Note your Partner ID, Partner Secret and Finicity App Key

Finicity credentials

2. Create an Access Token

All requests sent to Finicity must include a Finicity-App-Token HTTP header. Use the following endpoint whenever you need to generate a new access token:

cURL command
 curl --location --request POST 'https://api.finicity.com/aggregation/v2/partners/authentication' \
--header 'Content-Type: application/json' \
--header 'Finicity-App-Key: {{appKey}}' \
--header 'Accept: application/json' \
--data-raw '{
    "partnerId": "{{partnerId}}",
    "partnerSecret": "{{partnerSecret}}"
}' 
Expected response
 {
"token": "YBh22Sb9Es6e66Q7lWdt"
}

3. Welcome Your First Customer

Most of Finicity APIs require a Customer ID. To create a test customer and share some test accounts with Finicity, follow the 4 steps below.

You can go a little bit faster by downloading and running the following script: setup.sh.

Usage: ./setup.sh {partnerId} {partnerSecret} {appKey}

Step 1 - Call addTestingCustomer

Here, we start with creating a “testing” customer record we will then use with FinBank test profiles:

cURL command
 curl --location --request POST 'https://api.finicity.com/aggregation/v2/customers/testing' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Finicity-App-Key: {{appKey}}' \
--header 'Finicity-App-Token: {{appToken}}' \
--data-raw '{
    "username": "{{username}}"
}' 
Expected response
 {
"id": "1005061234",
"username": "{{username}}",
"createdDate": 1607450357
}

Step 2 - Call generateConnectUrl

Now that you have a Customer ID, the next step is to generate a Connect URL you would typically share with your end users. From that, they can start a Connect session and grant Finicity access to their accounts and financial data.

cURL command
 curl --location --request POST 'https://api.finicity.com/connect/v2/generate' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Finicity-App-Token: {{appToken}}' \
--header 'Finicity-App-Key: {{appKey}}' \
--data-raw '{
    "partnerId": "{{partnerId}}",
    "customerId": "{{customerId}}"
}' 
Expected response
 {
"link": "https://connect2.finicity.com?customerId=1005061234&origin=url&partnerId=2423653942467&signature=91f44ab969a9c7bb2568910d92501eb13aa0b7fd4fd56314ab8ebb4f1880fa83×tamp=1651326873996&ttl=1651334073996"
}

Step 3 - Sign-in to FinBank and submit accounts

As an end user would do,

  • 1

    Open the URL generated at the previous step

  • 2

    Search for FinBank

  • 3

    When asked for a username and password, type profile_09 for both

  • 4

    Select all accounts, and then click Submit

Expected flow:

Connect screens

Step 4 - Call refreshCustomerAccounts

As a last step, an initial aggregation must be made in order to retrieve account transactions. For that, call the following endpoint:

cURL command
 curl --location -g --request POST 'https://api.finicity.com/aggregation/v1/customers/{{customerId}}/accounts' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Finicity-App-Token: {{appToken}}' \
--header 'Finicity-App-Key: {{appKey}}' \
--data-raw '{}' 
Expected response
 {
"accounts": [
{
"id": "5053611184",
"number": "8000008888",
"accountNumberDisplay": "8888",
"name": "Auto Loan",
"balance": -429.29,
"type": "loan",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231824,
"aggregationAttemptDate": 1651231824,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"payoffAmount": 101.11,
"principalBalance": 1021.21,
"escrowBalance": 71.45,
"interestRate": "1.65",
"autoPayEnrolled": "Y",
"collateral": "test collateral",
"currentSchool": "current school",
"firstMortgage": "N",
"originalSchool": "original school",
"recurringPaymentAmount": 232.0,
"lender": "lender",
"availableBalanceAmount": 78.11,
"endingBalanceAmount": 66.33,
"loanTermType": "loan term type",
"paymentsMade": 4,
"balloonAmount": 88.11,
"projectedInterest": 54.22,
"interestPaidLtd": 12.22,
"interestRateType": "interest rate type",
"loanPaymentType": "loan payment type",
"paymentsRemaining": 88,
"loanMinAmtDue": 250.0,
"loanPaymentFreq": "loan pay freq",
"paymentMinAmount": 232.0,
"loanMinAmtDueDate": 1650888000,
"firstPaymentDate": 1650369600
},
"displayPosition": 1,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Auto Loan",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
},
{
"id": "5053611185",
"number": "2000005555",
"accountNumberDisplay": "5555",
"name": "Home Mortgage",
"balance": -429.29,
"type": "mortgage",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231824,
"aggregationAttemptDate": 1651231824,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"payoffAmount": 101.11,
"principalBalance": 1021.21,
"escrowBalance": 71.45,
"interestRate": "1.65",
"autoPayEnrolled": "Y",
"collateral": "test collateral",
"currentSchool": "current school",
"firstMortgage": "N",
"originalSchool": "original school",
"recurringPaymentAmount": 232.0,
"lender": "lender",
"availableBalanceAmount": 78.11,
"endingBalanceAmount": 66.33,
"loanTermType": "loan term type",
"paymentsMade": 4,
"balloonAmount": 88.11,
"projectedInterest": 54.22,
"interestPaidLtd": 12.22,
"interestRateType": "interest rate type",
"loanPaymentType": "loan payment type",
"paymentsRemaining": 88,
"loanMinAmtDue": 250.0,
"loanPaymentFreq": "loan pay freq",
"paymentMinAmount": 232.0,
"loanMinAmtDueDate": 1650888000,
"firstPaymentDate": 1650369600
},
"displayPosition": 7,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Home Mortgage",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
},
{
"id": "5053611187",
"number": "2000004444",
"accountNumberDisplay": "4444",
"name": "Roth IRA",
"balance": 429.29,
"type": "investment",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231825,
"aggregationAttemptDate": 1651231825,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"vestedBalance": 1250.0,
"currentLoanBalance": 4500.0,
"loanRate": 3.0,
"marginAllowed": true,
"cashAccountAllowed": true
},
"displayPosition": 3,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Roth IRA",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
},
{
"id": "5053611189",
"number": "0000000000",
"accountNumberDisplay": "0000",
"name": "Brokerage",
"balance": 429.29,
"type": "investment",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231825,
"aggregationAttemptDate": 1651231825,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"vestedBalance": 1250.0,
"currentLoanBalance": 4500.0,
"loanRate": 3.0,
"employeeDeferPreTaxAmount": 45.25,
"employeePreTaxAmount": 1250.0,
"employeePreTaxPercentage": 4500.0,
"employerYearToDate": 25.1,
"rolloverContributionAmount": 45.25,
"allowedCheckWriting": "ALLOW",
"allowedOptionTrade": "ALLOW",
"dailyChange": 3.0,
"margin": 45.25,
"percentageChange": 1250.0,
"loanPaymentAmount": 3.0,
"loanNextPaymentDate": 1550041200
},
"position": [
{
"id": 21697396,
"symbol": "JPM",
"fundName": "JPMORGAN CHASE & CO",
"quantity": 10.0,
"marketValue": "914.20000000",
"changePercent": 5.0,
"costBasis": 925.5,
"dailyChange": 3.0,
"memo": "I am tp_account_inves_position memo",
"empPretaxContribAmount": 156.0,
"heldInAccount": "127786786.00000000",
"holdType": "INVESTMENT",
"maturityValue": 5466.0,
"units": 99.0,
"unitPrice": 786.0,
"type": "Margin",
"status": "A",
"invSecurityType": "OTHERINFO",
"securityCurrencyRate": "3.21000000",
"averageCost": 10.0,
"cashAccount": 22.22,
"faceValue": 10.0,
"holdingId": "H213223",
"securitySubType": "S112233",
"rate": 11.1,
"unitType": "U5522",
"todayGLDollar": 13.1,
"todayGLPercent": 11.1,
"totalGLDollar": 12.1,
"totalGLPercent": 14.1,
"costBasisPerShare": 15.0,
"enterpriseSymbol": "E52122",
"localMarketValue": 16.0,
"localPrice": 17.1,
"securityId": "1234",
"reinvestmentCapGains": "101.00000000",
"reinvestmentDividend": "20.00000000",
"expirationDate": 1550041200,
"originalPurchaseDate": 1550041200
},
{
"id": 21697397,
"symbol": "ABC",
"fundName": "American Broadcasting Company",
"quantity": 100.0,
"marketValue": "429.00000000",
"changePercent": 5.0,
"costBasis": 925.5,
"dailyChange": 3.0,
"memo": "I am tp_account_inves_position memo",
"empPretaxContribAmount": 156.0,
"heldInAccount": "127786786.00000000",
"holdType": "INVESTMENT",
"maturityValue": 5466.0,
"units": 99.0,
"unitPrice": 786.0,
"type": "Margin",
"status": "A",
"invSecurityType": "OTHERINFO",
"securityCurrencyRate": "3.21000000",
"averageCost": 10.0,
"cashAccount": 22.22,
"faceValue": 10.0,
"holdingId": "H213223",
"securitySubType": "S112233",
"rate": 11.1,
"unitType": "U5522",
"todayGLDollar": 13.1,
"todayGLPercent": 11.1,
"totalGLDollar": 12.1,
"totalGLPercent": 14.1,
"costBasisPerShare": 15.0,
"enterpriseSymbol": "E52122",
"localMarketValue": 16.0,
"localPrice": 17.1,
"securityId": "1234",
"reinvestmentCapGains": "101.00000000",
"reinvestmentDividend": "20.00000000",
"expirationDate": 1550041200,
"originalPurchaseDate": 1550041200
},
{
"id": 21697398,
"symbol": "KO",
"fundName": "COCA COLA CO",
"quantity": 22.0,
"marketValue": "1002.98000000",
"changePercent": 5.0,
"costBasis": 981.88,
"dailyChange": 3.0,
"memo": "I am tp_account_inves_position memo",
"empPretaxContribAmount": 156.0,
"heldInAccount": "127786786.00000000",
"holdType": "INVESTMENT",
"maturityValue": 5466.0,
"units": 99.0,
"unitPrice": 786.0,
"type": "Margin",
"status": "A",
"invSecurityType": "OTHERINFO",
"securityCurrencyRate": "3.21000000",
"averageCost": 10.0,
"cashAccount": 22.22,
"faceValue": 10.0,
"holdingId": "H213223",
"securitySubType": "S112233",
"rate": 11.1,
"unitType": "U5522",
"todayGLDollar": 13.1,
"todayGLPercent": 11.1,
"totalGLDollar": 12.1,
"totalGLPercent": 14.1,
"costBasisPerShare": 15.0,
"enterpriseSymbol": "E52122",
"localMarketValue": 16.0,
"localPrice": 17.1,
"securityId": "1234",
"reinvestmentCapGains": "101.00000000",
"reinvestmentDividend": "20.00000000",
"expirationDate": 1550041200,
"originalPurchaseDate": 1550041200
}
],
"displayPosition": 8,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Brokerage",
"marketSegment": "personal"
},
{
"id": "5053611190",
"number": "8000006666",
"accountNumberDisplay": "6666",
"name": "Line of Credit",
"balance": -429.29,
"type": "lineOfCredit",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231825,
"aggregationAttemptDate": 1651231825,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"interestRate": "4.5",
"creditAvailableAmount": 799.99,
"paymentMinAmount": 1.0,
"statementCloseBalance": -429.29,
"locPrincipalBalance": 20010.0,
"paymentDueDate": 1651730400,
"statementEndDate": 1648792800
},
"displayPosition": 4,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Line of Credit",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
},
{
"id": "5053611191",
"number": "4100007777",
"accountNumberDisplay": "7777",
"name": "Credit Card",
"balance": 429.29,
"type": "creditCard",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231826,
"aggregationAttemptDate": 1651231826,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"displayPosition": 2,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Credit Card",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
},
{
"id": "5053611192",
"number": "1000002222",
"realAccountNumberLast4": "2222",
"accountNumberDisplay": "2222",
"name": "Savings",
"balance": 429.29,
"type": "savings",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231826,
"aggregationAttemptDate": 1651231826,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"availableBalanceAmount": 429.29,
"periodInterestRate": "4.5"
},
"displayPosition": 6,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Savings",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
},
{
"id": "5053611193",
"number": "1000001111",
"realAccountNumberLast4": "1111",
"accountNumberDisplay": "1111",
"name": "Checking",
"balance": 429.29,
"type": "checking",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231826,
"aggregationAttemptDate": 1651231826,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"availableBalanceAmount": 429.29,
"periodInterestRate": "4.5"
},
"displayPosition": 5,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Checking",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
}
]
}

4. Fetch Some Data

Example 1 - Fetch institutions

In this first example, we retrieve the list of supported financial institutions by calling getInstitutions:

cURL command
 curl --location --request GET 'https://api.finicity.com/institution/v2/institutions' \
--header 'Finicity-App-Key: {{appKey}}' \
--header 'Accept: application/json' \
--header 'Finicity-App-Token: {{appToken}}' 
Expected response
 {
"found": 6850,
"displaying": 25,
"moreAvailable": true,
"createdDate": 1651231882,
"institutions": [
{
"id": 4222,
"name": "Principal Financial - Retirement (Personal)",
"voa": false,
"voi": false,
"stateAgg": false,
"ach": false,
"transAgg": true,
"aha": false,
"availBalance": false,
"accountOwner": false,
"accountTypeDescription": "Workplace Retirement",
"phone": "1-800-986-3343",
"urlHomeApp": "https://www.principal.com",
"urlLogonApp": "https://login.principal.com/login",
"oauthEnabled": false,
"urlForgotPassword": "https://auth.principal.com/oaam_server/forgotPassword.do",
"urlOnlineRegistration": "",
"class": "retirement",
"specialText": "Please enter your Principal Financial - Retirement (Personal) Username and Password.",
"timeZone": null,
"specialInstructions": null,
"specialInstructionsTitle": null,
"address": {
"city": "Des Moines",
"state": "IA",
"country": "USA",
"postalCode": "50392",
"addressLine1": "711 High Street",
"addressLine2": ""
},
"currency": "USD",
"email": "https://secure01.principal.com/common/webreply/reply.htm",
"status": "online",
"newInstitutionId": null,
"requiresFinicityCallout": false,
"accuityData": null,
"branding": {
"logo": "https://prod-carpintero-branding.s3.us-west-2.amazonaws.com/4222/logo.svg",
"alternateLogo": "https://prod-carpintero-branding.s3.us-west-2.amazonaws.com/4222/alternateLogo.svg",
"icon": "https://prod-carpintero-branding.s3.us-west-2.amazonaws.com/4222/icon.svg",
"primaryColor": "#58595B",
"tile": "https://prod-carpintero-branding.s3.us-west-2.amazonaws.com/4222/tile.svg"
},
"oauthInstitutionId": null,
"productionStatus": {
"overallStatus": "investigating",
"transAgg": "investigating",
"voa": "investigating",
"voi": "investigating",
"stateAgg": "investigating",
"ach": "investigating",
"aha": "investigating"
}
}
]
}

Example 2 - Fetch customer accounts

We are now interested in retrieving the list of accounts owned by our customer. For that, we call the getCustomerAccounts endpoint:

cURL command
 curl --location -g --request GET 'https://api.finicity.com/aggregation/v1/customers/{{customerId}}/accounts' \
--header 'Finicity-App-Key: {{appKey}}' \
--header 'Accept: application/json' \
--header 'Finicity-App-Token: {{appToken}}' 
Expected response
 {
"accounts": [
{
"id": "5053611184",
"number": "8000008888",
"accountNumberDisplay": "8888",
"name": "Auto Loan",
"balance": -429.29,
"type": "loan",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231824,
"aggregationAttemptDate": 1651231824,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"payoffAmount": 101.11,
"principalBalance": 1021.21,
"escrowBalance": 71.45,
"interestRate": "1.65",
"autoPayEnrolled": "Y",
"collateral": "test collateral",
"currentSchool": "current school",
"firstMortgage": "N",
"originalSchool": "original school",
"recurringPaymentAmount": 232.0,
"lender": "lender",
"availableBalanceAmount": 78.11,
"endingBalanceAmount": 66.33,
"loanTermType": "loan term type",
"paymentsMade": 4,
"balloonAmount": 88.11,
"projectedInterest": 54.22,
"interestPaidLtd": 12.22,
"interestRateType": "interest rate type",
"loanPaymentType": "loan payment type",
"paymentsRemaining": 88,
"loanMinAmtDue": 250.0,
"loanPaymentFreq": "loan pay freq",
"paymentMinAmount": 232.0,
"loanMinAmtDueDate": 1650888000,
"firstPaymentDate": 1650369600
},
"displayPosition": 1,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Auto Loan",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
},
{
"id": "5053611185",
"number": "2000005555",
"accountNumberDisplay": "5555",
"name": "Home Mortgage",
"balance": -429.29,
"type": "mortgage",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231824,
"aggregationAttemptDate": 1651231824,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"payoffAmount": 101.11,
"principalBalance": 1021.21,
"escrowBalance": 71.45,
"interestRate": "1.65",
"autoPayEnrolled": "Y",
"collateral": "test collateral",
"currentSchool": "current school",
"firstMortgage": "N",
"originalSchool": "original school",
"recurringPaymentAmount": 232.0,
"lender": "lender",
"availableBalanceAmount": 78.11,
"endingBalanceAmount": 66.33,
"loanTermType": "loan term type",
"paymentsMade": 4,
"balloonAmount": 88.11,
"projectedInterest": 54.22,
"interestPaidLtd": 12.22,
"interestRateType": "interest rate type",
"loanPaymentType": "loan payment type",
"paymentsRemaining": 88,
"loanMinAmtDue": 250.0,
"loanPaymentFreq": "loan pay freq",
"paymentMinAmount": 232.0,
"loanMinAmtDueDate": 1650888000,
"firstPaymentDate": 1650369600
},
"displayPosition": 7,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Home Mortgage",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
},
{
"id": "5053611187",
"number": "2000004444",
"accountNumberDisplay": "4444",
"name": "Roth IRA",
"balance": 429.29,
"type": "investment",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231825,
"aggregationAttemptDate": 1651231825,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"vestedBalance": 1250.0,
"currentLoanBalance": 4500.0,
"loanRate": 3.0,
"marginAllowed": true,
"cashAccountAllowed": true
},
"displayPosition": 3,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Roth IRA",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
},
{
"id": "5053611189",
"number": "0000000000",
"accountNumberDisplay": "0000",
"name": "Brokerage",
"balance": 429.29,
"type": "investment",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231825,
"aggregationAttemptDate": 1651231825,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"vestedBalance": 1250.0,
"currentLoanBalance": 4500.0,
"loanRate": 3.0,
"employeeDeferPreTaxAmount": 45.25,
"employeePreTaxAmount": 1250.0,
"employeePreTaxPercentage": 4500.0,
"employerYearToDate": 25.1,
"rolloverContributionAmount": 45.25,
"allowedCheckWriting": "ALLOW",
"allowedOptionTrade": "ALLOW",
"dailyChange": 3.0,
"margin": 45.25,
"percentageChange": 1250.0,
"loanPaymentAmount": 3.0,
"loanNextPaymentDate": 1550041200
},
"position": [
{
"id": 21697396,
"symbol": "JPM",
"fundName": "JPMORGAN CHASE & CO",
"quantity": 10.0,
"marketValue": "914.20000000",
"changePercent": 5.0,
"costBasis": 925.5,
"dailyChange": 3.0,
"memo": "I am tp_account_inves_position memo",
"empPretaxContribAmount": 156.0,
"heldInAccount": "127786786.00000000",
"holdType": "INVESTMENT",
"maturityValue": 5466.0,
"units": 99.0,
"unitPrice": 786.0,
"type": "Margin",
"status": "A",
"invSecurityType": "OTHERINFO",
"securityCurrencyRate": "3.21000000",
"averageCost": 10.0,
"cashAccount": 22.22,
"faceValue": 10.0,
"holdingId": "H213223",
"securitySubType": "S112233",
"rate": 11.1,
"unitType": "U5522",
"todayGLDollar": 13.1,
"todayGLPercent": 11.1,
"totalGLDollar": 12.1,
"totalGLPercent": 14.1,
"costBasisPerShare": 15.0,
"enterpriseSymbol": "E52122",
"localMarketValue": 16.0,
"localPrice": 17.1,
"securityId": "1234",
"reinvestmentCapGains": "101.00000000",
"reinvestmentDividend": "20.00000000",
"expirationDate": 1550041200,
"originalPurchaseDate": 1550041200
},
{
"id": 21697397,
"symbol": "ABC",
"fundName": "American Broadcasting Company",
"quantity": 100.0,
"marketValue": "429.00000000",
"changePercent": 5.0,
"costBasis": 925.5,
"dailyChange": 3.0,
"memo": "I am tp_account_inves_position memo",
"empPretaxContribAmount": 156.0,
"heldInAccount": "127786786.00000000",
"holdType": "INVESTMENT",
"maturityValue": 5466.0,
"units": 99.0,
"unitPrice": 786.0,
"type": "Margin",
"status": "A",
"invSecurityType": "OTHERINFO",
"securityCurrencyRate": "3.21000000",
"averageCost": 10.0,
"cashAccount": 22.22,
"faceValue": 10.0,
"holdingId": "H213223",
"securitySubType": "S112233",
"rate": 11.1,
"unitType": "U5522",
"todayGLDollar": 13.1,
"todayGLPercent": 11.1,
"totalGLDollar": 12.1,
"totalGLPercent": 14.1,
"costBasisPerShare": 15.0,
"enterpriseSymbol": "E52122",
"localMarketValue": 16.0,
"localPrice": 17.1,
"securityId": "1234",
"reinvestmentCapGains": "101.00000000",
"reinvestmentDividend": "20.00000000",
"expirationDate": 1550041200,
"originalPurchaseDate": 1550041200
},
{
"id": 21697398,
"symbol": "KO",
"fundName": "COCA COLA CO",
"quantity": 22.0,
"marketValue": "1002.98000000",
"changePercent": 5.0,
"costBasis": 981.88,
"dailyChange": 3.0,
"memo": "I am tp_account_inves_position memo",
"empPretaxContribAmount": 156.0,
"heldInAccount": "127786786.00000000",
"holdType": "INVESTMENT",
"maturityValue": 5466.0,
"units": 99.0,
"unitPrice": 786.0,
"type": "Margin",
"status": "A",
"invSecurityType": "OTHERINFO",
"securityCurrencyRate": "3.21000000",
"averageCost": 10.0,
"cashAccount": 22.22,
"faceValue": 10.0,
"holdingId": "H213223",
"securitySubType": "S112233",
"rate": 11.1,
"unitType": "U5522",
"todayGLDollar": 13.1,
"todayGLPercent": 11.1,
"totalGLDollar": 12.1,
"totalGLPercent": 14.1,
"costBasisPerShare": 15.0,
"enterpriseSymbol": "E52122",
"localMarketValue": 16.0,
"localPrice": 17.1,
"securityId": "1234",
"reinvestmentCapGains": "101.00000000",
"reinvestmentDividend": "20.00000000",
"expirationDate": 1550041200,
"originalPurchaseDate": 1550041200
}
],
"displayPosition": 8,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Brokerage",
"marketSegment": "personal"
},
{
"id": "5053611190",
"number": "8000006666",
"accountNumberDisplay": "6666",
"name": "Line of Credit",
"balance": -429.29,
"type": "lineOfCredit",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231825,
"aggregationAttemptDate": 1651231825,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"interestRate": "4.5",
"creditAvailableAmount": 799.99,
"paymentMinAmount": 1.0,
"statementCloseBalance": -429.29,
"locPrincipalBalance": 20010.0,
"paymentDueDate": 1651730400,
"statementEndDate": 1648792800
},
"displayPosition": 4,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Line of Credit",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
},
{
"id": "5053611191",
"number": "4100007777",
"accountNumberDisplay": "7777",
"name": "Credit Card",
"balance": 429.29,
"type": "creditCard",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231826,
"aggregationAttemptDate": 1651231826,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"displayPosition": 2,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Credit Card",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
},
{
"id": "5053611192",
"number": "1000002222",
"realAccountNumberLast4": "2222",
"accountNumberDisplay": "2222",
"name": "Savings",
"balance": 429.29,
"type": "savings",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231826,
"aggregationAttemptDate": 1651231826,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"availableBalanceAmount": 429.29,
"periodInterestRate": "4.5"
},
"displayPosition": 6,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Savings",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
},
{
"id": "5053611193",
"number": "1000001111",
"realAccountNumberLast4": "1111",
"accountNumberDisplay": "1111",
"name": "Checking",
"balance": 429.29,
"type": "checking",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "5027308115",
"institutionId": "101732",
"balanceDate": 1651231801,
"aggregationSuccessDate": 1651231826,
"aggregationAttemptDate": 1651231826,
"createdDate": 1649693826,
"lastUpdatedDate": 1649693833,
"currency": "USD",
"lastTransactionDate": 1651231801,
"institutionLoginId": 5028130870,
"detail": {
"availableBalanceAmount": 429.29,
"periodInterestRate": "4.5"
},
"displayPosition": 5,
"financialinstitutionAccountStatus": "OPEN",
"accountNickname": "Checking",
"oldestTransactionDate": 1586606400,
"marketSegment": "personal"
}
]
}

5. Run the Postman Collection

You now have everything you need to explore the Finicity APIs further. For that, we recommend using the Finicity Postman collection.

  • 1
     Click: 
    Run in Postman
  • 2

    Select the Test Drive environment (top right) and update partnerId, partnerSecret, appKey and customerId variables

  • 3

    Click Send on individual requests, or Run collection

  • 4

    Explore the Pre-request Script and Tests tabs, and update the collection as you wish

Postman workspace

6. Generate an API Client Library

The final step we propose for this guide is to leverage the API specification and consume the Finicity APIs directly from your application.


Here is how to proceed:

  • 3 Add some code to automatically attach the Finicity-App-Token and Finicity-App-Key HTTP headers to requests:
  • 4 Configure your ApiClient instance and use one of the *Api classes:


Well done, you’re now ready to use Finicity in your application 

Connect URL from IntelliJ

Next Steps

  • For the full list of testing profiles available, refer to Test the APIs

  • To learn more about Finicity Connect, configure Connect for your application and receive Connect session events, read Connect

If you have any questions or need assistance, please contact us.