Institutions

An institution is a financial institution (FI) such as a bank, investment firm, or other organization, which provides financial accounts for their customers. Finicity's Institution resource includes services for looking up supported financial institutions and for obtaining the login form of a specific institution, in order to discover and activate customer accounts.

See Active Docs to experiment directly with the API.

Available services:

Institution Record

The following fields are available in an institution record:

Field Name Description
id The institution ID
name The name of the institution
accountTypeDescription One of the values Banking, Investments, Credit Cards/Accounts, Workplace Retirement, Mortgages and Loans, Insurance
urlHomeApp The URL of the institution's primary home page
urlLogonApp The URL of the institution's login page
phone The institution's primary phone number
currency The institution's primary currency
email The institution's primary contact email
specialText Any special text found on the institution's website
address Parent element for the address of the institution's headquarters
- addressLine1, 2 Address information for the institution's headquarters
- city The city of the institution's headquarters
- state Two-letter code for the state of the institution's headquarters
- postalCode The postal code of the institution's headquarters
- country The country of the institution's headquarters

LoginField Record

The following fields are available in a loginField record:

(Fields marked with an asterisk * are included in a partial loginField record submitted for calls that require account credentials, such as Add All Accounts and Modify Customer Account Credentials.)

Field Name Description
*id The ID of this field
*name The system name for this field
*value A default value for this field, if found (always blank for masked fields)
displayOrder An ordinal number to facilitate sorting fields for display
mask true if the contents of this field should NOT be displayed on the screen (for password-style fields) 
description The displayable name for this field
instructions Additional instructions from the institution (should be displayed if present)
valueLengthMin The minimum length for this field's value, or "0" if not known 
valueLengthMax The maximum length for this field's value, or "0" if not known 

Get Institutions

GET /v1/institutions?search=[text]&start=[index]&limit=[count]

Return all financial institutions that contain the search text in the institution’s name, urlHomeApp, or urlLogonApp fields.

Return all institutions if no query parameters are provided or if the search string is a single asterisk *.

If the value of moreAvailable in the response is true, you can retrieve the next page of results by increasing the value of the start parameter in your next request:

  ...&start=6&limit=5

JSON Implementation

Request Details:

Parameter Type Default Description
Finicity-App-Key HTTP header   Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header   Token returned from Partner Authentication
Accept HTTP header  

application/json

search query *

Text to match, or * to return all supported institutions.

Must be URL-encoded (see Handling Spaces in Queries)

start query 1 Starting index for this page of results (ignored if returning all institutions)
limit query 25 Maximum number of entries for this page of results (ignored if returning all institutions)

Success: HTTP 200 (OK)

Example Requests:

GET https://api.finicity.com/aggregation/v1/institutions
GET https://api.finicity.com/aggregation/v1/institutions?search=new+york&start=1&limit=3

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -X GET "https://api.finicity.com/aggregation/v1/institutions?search=new+york&start=1&limit=3"

Response Details:

Field Name Description
found Total number of records matching search criteria
displaying Number of records in this response
moreAvailable true if this response does not contain the last record in the result set
createdDate Date this list was generated
institutions List of institution records

Example Response:

{
"found": 28,
"displaying": 3,
"moreAvailable": true,
"createdDate": 1470966593,
"institutions": [
{
"id": 101065,
"name": "New York College Savings Program 529",
"accountTypeDescription": "Banking",
"urlHomeApp": "http://www.ny529advisor.com/",
"urlLogonApp": "https://ny529advisor.org/nyatpl/auth/loginFormAction.do",
"urlProductApp": "",
"specialText": "Please enter your New York College Savings Program User name and Password.",
"address": {
"addressLine1": "P.O. Box 55498",
"addressLine2": "Boston, MA 02205",
"city": "Boston",
"state": "MA",
"postalCode": "02205",
"country": "USA"
},
"phone": "1-800-774-2108",
"email": "ny.529advisor@jpmorgan.com",
"currency": "USD"
},
{
"id": 8584,
"name": "New York Community Bank Credit Card",
"accountTypeDescription": "Credit Cards/Accounts",
"urlHomeApp": "http://www.qcsb.com/index.asp?divID=1",
"urlLogonApp": "https://global1.onlinebank.com/cgi-forte/forteisapi.dll?BankTag=1382nycb&ServiceName=WebTeller&TemplateName=Login.htm",
"urlProductApp": "",
"specialText": "Please enter your New York Community Bank Credit Card User ID and Password required for login",
"address": {
"addressLine1": "1125 Atlantic Avenue",
"addressLine2": "",
"city": "Atlantic City",
"state": "NJ",
"postalCode": "08401",
"country": "USA"
},
"phone": "1-609-348-1183",
"email": "http://www.qcsb.com/southjersey/welcome.shtml",
"currency": "USD"
},
{
"id": 1668,
"name": "New York Giants MBNA CC",
"accountTypeDescription": "Credit Cards/Accounts",
"urlHomeApp": "https://www.bankofamerica.com/",
"urlLogonApp": "https://secure.bankofamerica.com/login/sign-in/signOnV2Screen.go",
"urlProductApp": "",
"specialText": "Please enter your MBNA Credit Card Online ID and Online Passcode required for login. ",
"address": {
"addressLine1": "",
"addressLine2": "",
"city": "Wilmington",
"state": "DE",
"postalCode": "19884",
"country": "USA"
},
"phone": "1-800-653-2465",
"email": "",
"currency": "USD"
}
]
}

XML Implementation

Request Details:

Parameter Type Default Description
Finicity-App-Key HTTP header   Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header   Token returned from Partner Authentication
Accept HTTP header   application/xml
search query *

Text to match, or * to return all supported institutions.

Must be URL-encoded (see Handling Spaces in Queries)

start query 1 Starting index for this page of results (ignored if returning all institutions)
limit query 25 Maximum number of entries for this page of results (ignored if returning all institutions)

Success: HTTP 200 (OK)

Example Requests:

GET https://api.finicity.com/aggregation/v1/institutions
GET https://api.finicity.com/aggregation/v1/institutions?search=new+york&start=1&limit=3

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/xml" -X GET "https://api.finicity.com/aggregation/v1/institutions?search=new+york&start=1&limit=3"

Response Details:

XML Name Description
institutions Root element
found Attribute giving the total number of records matching search criteria
displaying Attribute giving the number of records in this response
moreAvailable Attribute giving true if this response does not contain the last record in the result set
createdDate Date this list was generated
institution An institution record

Example Response:

<institutions found="28" displaying="3" moreAvailable="true" createdDate="1470966889">
<institution>
<id>101065</id>
<name>New York College Savings Program 529</name>
<accountTypeDescription>Banking</accountTypeDescription>
<phone>1-800-774-2108</phone>
<currency>USD</currency>
<email>ny.529advisor@jpmorgan.com</email>
<urlHomeApp>http://www.ny529advisor.com/</urlHomeApp>
<urlLogonApp>https://ny529advisor.org/nyatpl/auth/loginFormAction.do</urlLogonApp>
<urlProductApp></urlProductApp>
<specialText>Please enter your New York College Savings Program User name and Password.</specialText>
<address>
<addressLine1>P.O. Box 55498</addressLine1>
<addressLine2>Boston, MA 02205</addressLine2>
<city>Boston</city>
<state>MA</state>
<postalCode>02205</postalCode>
<country>USA</country>
</address>
</institution>
<institution>
<id>8584</id>
<name>New York Community Bank Credit Card</name>
<accountTypeDescription>Credit Cards/Accounts</accountTypeDescription>
<phone>1-609-348-1183</phone>
<currency>USD</currency>
<email>http://www.qcsb.com/southjersey/welcome.shtml</email>
<urlHomeApp>http://www.qcsb.com/index.asp?divID=1</urlHomeApp>
<urlLogonApp>https://global1.onlinebank.com/cgi-forte/forteisapi.dll?BankTag=1382nycb&amp;ServiceName=WebTeller&amp;TemplateName=Login.htm</urlLogonApp>
<urlProductApp></urlProductApp>
<specialText>Please enter your New York Community Bank Credit Card User ID and Password required for login</specialText>
<address>
<addressLine1>1125 Atlantic Avenue</addressLine1>
<addressLine2></addressLine2>
<city>Atlantic City</city>
<state>NJ</state>
<postalCode>08401</postalCode>
<country>USA</country>
</address>
</institution>
<institution>
<id>1668</id>
<name>New York Giants MBNA CC</name>
<accountTypeDescription>Credit Cards/Accounts</accountTypeDescription>
<phone>1-800-653-2465</phone>
<currency>USD</currency>
<email></email>
<urlHomeApp>https://www.bankofamerica.com/</urlHomeApp>
<urlLogonApp>https://secure.bankofamerica.com/login/sign-in/signOnV2Screen.go</urlLogonApp>
<urlProductApp></urlProductApp>
<specialText>Please enter your MBNA Credit Card Online ID and Online Passcode required for login. </specialText>
<address>
<addressLine1></addressLine1>
<addressLine2></addressLine2>
<city>Wilmington</city>
<state>DE</state>
<postalCode>19884</postalCode>
<country>USA</country>
</address>
</institution>
</institutions>

Get Institution
GET /v1/institutions/{institutionId}

Get details for the specified institution.

JSON Implementation

Request Details:

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header application/json
institutionId path ID of the institution to retrieve

Success: HTTP 200 (OK)

Example Request:

https://api.finicity.com/aggregation/v1/institutions/11863

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -X GET "https://api.finicity.com/aggregation/v1/institutions/11863"

Response Details:

A single institution record.

Example Response:

{
"id": 11863,
"name": "Clearfield Bank & Trust Co",
"accountTypeDescription": "Banking",
"urlHomeApp": "https://www.clearfieldbankandtrust.com/",
"urlLogonApp": "https://www.netteller.com/clearfieldbankandtrust/login.cfm",
"urlProductApp": "",
"specialText": "Please enter your Clearfield Bank & Trust Co ONLINE24 Internet Banking ID and ONLINE24 Internet Banking Password required for login.",
"address": {
"addressLine1": "11 N. Second Street",
"addressLine2": "PO Box 171",
"city": "Clearfield",
"state": "PA",
"postalCode": "16830",
"country": "USA"
},
"email": "support@cbtfinancial.com",
"phone": "814-765-7551",
"currency": "USD"

XML Implementation

Request Details:

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header application/xml
institutionId path ID of the institution to retrieve

Success: HTTP 200 (OK)

Example Request:

https://api.finicity.com/aggregation/v1/institutions/11863

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/xml" -X GET "https://api.finicity.com/aggregation/v1/institutions/11863"

Response Details:

A single institution record.

Example Response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<institution>
<id>11863</id>
<name>Clearfield Bank &amp; Trust Co</name>
<accountTypeDescription>Banking</accountTypeDescription>
<phone>814-765-7551</phone>
<currency>USD</currency>
<email>support@cbtfinancial.com</email>
<urlHomeApp>https://www.clearfieldbankandtrust.com/</urlHomeApp>
<urlLogonApp>https://www.netteller.com/clearfieldbankandtrust/login.cfm</urlLogonApp>
<urlProductApp></urlProductApp>
<specialText>Please enter your Clearfield Bank &amp; Trust Co ONLINE24 Internet Banking ID and ONLINE24 Internet Banking Password required for login.</specialText>
<address>
<addressLine1>11 N. Second Street</addressLine1>
<addressLine2>PO Box 171</addressLine2>
<city>Clearfield</city>
<state>PA</state>
<postalCode>16830</postalCode>
<country>USA</country>
</address>
</institution> 

Get Institution Details
GET /v1/institutions/{institutionId}/details

Get details for the specified institution.

JSON Implementation

Request Details:

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header application/json
institutionId path ID of the institution to retrieve

Success: HTTP 200 (OK)

Example Request:

https://api.finicity.com/aggregation/v1/institutions/11863/details

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -X GET "https://api.finicity.com/aggregation/v1/institutions/11863/details"

Response Details:

One institution record and one loginForm list of loginField records.

Example Response:

{
"institution": {
"id": 11863,
"name": "Clearfield Bank & Trust Co",
"accountTypeDescription": "Banking",
"urlHomeApp": "https://www.clearfieldbankandtrust.com/",
"urlLogonApp": "https://www.netteller.com/clearfieldbankandtrust/login.cfm",
"urlProductApp": "",
"specialText": "Please enter your Clearfield Bank & Trust Co ONLINE24 Internet Banking ID and ONLINE24 Internet Banking Password required for login.",
"address": {
"addressLine1": "11 N. Second Street",
"addressLine2": "PO Box 171",
"city": "Clearfield",
"state": "PA",
"postalCode": "16830",
"country": "USA"
},
"email": "support@cbtfinancial.com",
"phone": "814-765-7551",
"currency": "USD"
},
"loginForm": [
{
"id": "11863001",
"name": "ID",
"value": "",
"description": "ONLINE24 Internet Banking ID",
"displayOrder": 1,
"mask": "false",
"instructions": ""
},
{
"id": "11863002",
"name": "PIN",
"value": "",
"description": "ONLINE24 Internet Banking Password",
"displayOrder": 2,
"mask": "true",
"instructions": ""
}
]

XML Implementation

Request Details:

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header application/xml
institutionId path ID of the institution to retrieve

Success: HTTP 200 (OK)

Example Request:

https://api.finicity.com/aggregation/v1/institutions/11863/details

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/xml" -X GET "https://api.finicity.com/aggregation/v1/institutions/11863/details"

Response Details:

An XML document containing an institution record and a loginForm element with one or more loginField records.

Example Response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<institutionDetail>
<institution>
<id>11863</id>
<name>Clearfield Bank &amp; Trust Co</name>
<accountTypeDescription>Banking</accountTypeDescription>
<phone>814-765-7551</phone>
<currency>USD</currency>
<email>support@cbtfinancial.com</email>
<urlHomeApp>https://www.clearfieldbankandtrust.com/</urlHomeApp>
<urlLogonApp>https://www.netteller.com/clearfieldbankandtrust/login.cfm</urlLogonApp>
<urlProductApp></urlProductApp>
<specialText>Please enter your Clearfield Bank &amp; Trust Co ONLINE24 Internet Banking ID and ONLINE24 Internet Banking Password required for login.</specialText>
<address>
<addressLine1>11 N. Second Street</addressLine1>
<addressLine2>PO Box 171</addressLine2>
<city>Clearfield</city>
<state>PA</state>
<postalCode>16830</postalCode>
<country>USA</country>
</address>
</institution>
<loginForm>
<loginField>
<id>11863001</id>
<name>ID</name>
<value></value>
<description>ONLINE24 Internet Banking ID</description>
<displayOrder>1</displayOrder>
<mask>false</mask>
<instructions></instructions>
</loginField>
<loginField>
<id>11863002</id>
<name>PIN</name>
<value></value>
<description>ONLINE24 Internet Banking Password</description>
<displayOrder>2</displayOrder>
<mask>true</mask>
<instructions></instructions>
</loginField>
</loginForm>
</institutionDetail> 

Get Institution Login Form

GET /v1/institutions/{institutionId}/loginForm

Get the login form fields required for Discover Customer Accounts. The form is typically displayed to a customer to obtain credentials to access the customer's accounts at this institution.

JSON Implementation

Request Details:

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header application/json
institutionId path ID of the institution to retrieve

Success: HTTP 200 (OK)

Example Request:

https://api.finicity.com/aggregation/v1/institutions/11863/loginForm

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -X GET "https://api.finicity.com/aggregation/v1/institutions/11863/loginForm"

Response Details:

Field Name Description
loginForm A list of loginField records

Example Response:

{
"loginForm": [
{
"id": "11863001",
"name": "ID",
"value": "",
"description": "ONLINE24 Internet Banking ID",
"displayOrder": 1,
"mask": "false",
"instructions": ""
},
{
"id": "11863002",
"name": "PIN",
"value": "",
"description": "ONLINE24 Internet Banking Password",
"displayOrder": 2,
"mask": "true",
"instructions": ""
}
]
}

XML Implementation

Request Details:

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header application/xml
institutionId path ID of the institution to retrieve

Success: HTTP 200 (OK)

Example Request:

https://api.finicity.com/aggregation/v1/institutions/11863/loginForm

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/xml" -X GET "https://api.finicity.com/aggregation/v1/institutions/11863/loginForm"

Response Details:

XML Name Description
loginForm Root element
loginField A loginField record

Example Response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<loginForm>
<loginField>
<id>11863001</id>
<name>ID</name>
<value></value>
<description>ONLINE24 Internet Banking ID</description>
<displayOrder>1</displayOrder>
<mask>false</mask>
<instructions></instructions>
</loginField>
<loginField>
<id>11863002</id>
<name>PIN</name>
<value></value>
<description>ONLINE24 Internet Banking Password</description>
<displayOrder>2</displayOrder>
<mask>true</mask>
<instructions></instructions>
</loginField>
</loginForm>

 

Have more questions? Submit a request

Comments

  • Avatar
    Raman Huziy

    Hello,

    question about Get Institution Login Form API:

    GET /v1/institutions/{institutionId}/loginForm


    are there cases when returned login form contain more than two login fields? Should we support such case in our application? There are UI considerations. This article does not seem to mention if there is such case. Given example has two fields only.

    If there are cases when login form contains more than two login fields, it would be nice to have testing account for such a case. 


    Thanks.

    Edited by Raman Huziy
  • Avatar
    Raman Huziy

    I found answer myself during development. Answer is 'yes it can'. Example of such case is: USAA Bank (id:2875)

Powered by Zendesk