Institution Logins

An Institution Login represents one set of customer credentials at a particular institution, together with all accounts accessible using those credentials at that institution. Finicity's Institution Login resource includes services for viewing all customer accounts associated with an institution login, and for modifying the credentials stored to access those accounts.

See Customer Account Discovery, Activation, and Refresh for adding and refreshing customer accounts.

See Account Types for an explanation of supported account types.

See Active Docs to experiment directly with the API.

Available services:

Get Institution Login Accounts

GET /aggregation/v1/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts

Get details for all accounts associated with the given institution login. All accounts returned are accessible by a single set of credentials on a single 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

customerId path

The ID of the customer whose accounts are to be retrieved

institutionLoginId path

The institution login ID (from the account record)

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/institutionLogins/9764/accounts

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/customers/41442/institutionLogins/9764/accounts"

Response Details:

Field Name Description
accounts A list of account records

Example Response:

{ 
"accounts": [
{
"id": "2055",
"number": "XXXX-XXXXXX-32765",
"name": "Checking",
"balance": 1266.49,
"type": "checking",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "41442",
"institutionId": "101732",
"balanceDate": 1422421087,
"aggregationSuccessDate": 1422399293,
"aggregationAttemptDate": 1422395888,
"createdDate": 1422395818,
"currency": "USD",
"lastTransactionDate": 1422421087,
"institutionLoginId": 9764,
"displayPosition": 1
},
{
"id": "5027",
"number": "XXXX-XXXXXX-36174",
"name": "Credit Card",
"balance": -1547.62,
"type": "creditCard",
"aggregationStatusCode": 0,
"status": "active",
"customerId": "41442",
"institutionId": "101732",
"balanceDate": 1422342000,
"aggregationSuccessDate": 1422358530,
"aggregationAttemptDate": 1422358530,
"createdDate": 1420653087,
"currency": "USD",
"lastTransactionDate": 1422342000,
"institutionLoginId": 9764,
"displayPosition": 2
}
]
}

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

customerId path

The ID of the customer whose accounts are to be retrieved

institutionLoginId path

The institution login ID (from the account record)

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/institutionLogins/9764/accounts

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/customers/41442/institutionLogins/9764/accounts"

Response Details:

XML Name Description
accounts Root element
account An account record

Example Response:

<accounts>
  <account>
    <id>2055</id>
    <number>XXXX-XXXXXX-32765</number>
    <name>Checking</name>
    <balance>1266.49</balance>
    <type>checking</type>
    <aggregationStatusCode>0</aggregationStatusCode>
    <status>active</status>
    <customerId>41442</customerId>
    <institutionId>101732</institutionId>
    <balanceDate>1422421087</balanceDate>
    <aggregationSuccessDate>1422399293</aggregationSuccessDate>
    <aggregationAttemptDate>1422395888</aggregationAttemptDate>
    <createdDate>1422395818</createdDate>
<institutionLoginId>9764</institutionLoginId> <lastUpdatedDate>1422421087</lastUpdatedDate> </account> <account> <id>5027</id> <number>XXXX-XXXXXX-36174</number> <name>Credit Card</name> <balance>-1547.62</balance> <type>creditCard</type> <aggregationStatusCode>0</aggregationStatusCode> <status>active</status> <customerId>41442</customerId> <institutionId>101732</institutionId> <balanceDate>1422342000</balanceDate> <aggregationSuccessDate>1422358530</aggregationSuccessDate> <aggregationAttemptDate>1422358530</aggregationAttemptDate> <institutionLoginId>9764</institutionLoginId>
<createdDate>1420653087</createdDate> </account> </accounts>

Modify Institution Login Credentials

PUT /aggregation/v1/customers/{customerId}/institutionLogins/{institutionLoginId}

Change the values stored for the login fields of all accounts associated with the given institution login ID.

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
Content-Type HTTP header application/json
customerId path

The ID of the customer who owns the account

institutionLoginId path

The institution login ID (from the account record)

loginForm JSON field

A list of partial loginField records

id JSON field

The ID of the loginField to be changed (from Get Customer Account Login Form)

value JSON field

The new value for the loginField

Success: HTTP 204 (No Content)

Example Request:

PUT https://api.finicity.com/aggregation/v1/customers/41442/institutionLoginId/9764
{
"loginForm": [
{
"id": FIELD_ID_1,
"value": "VALUE_1",
},
{
"id": FIELD_ID_2,
"value": "VALUE_2",
}
]
}

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/json" -X PUT "https://api.finicity.com/aggregation/v1/customers/41442/institutionLogins/9764" -d '{ "loginForm": [ { "id": FIELD_ID_1, "value": "VALUE_1" }, { "id": FIELD_ID_2, "value": "VALUE_2" } ] }'

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
Content-Type HTTP header application/xml
customerId path

The ID of the customer who owns the account

institutionLoginId path

The institution login ID (from the account record)

loginForm XML element

Root element

loginField XML element

A partial loginField record

id XML element

The ID of the loginField to be changed (from Get Customer Account Login Form)

value XML element

The new value for the loginField

Success: HTTP 204 (No Content)

Example Request:

PUT https://api.finicity.com/aggregation/v1/customers/41442/institutionLogins/9764
<loginForm>
<loginField>
<id>FIELD_ID_1</id>
<value>VALUE_1</value>
</loginField>
<loginField>
<id>FIELD_ID_2</id>
<value>VALUE_2</value>
</loginField>
</loginForm>'

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -X PUT "https://api.finicity.com/aggregation/v1/customers/41442/institutionLogins/9764" -d '<loginForm> <loginField> <id>FIELD_ID_1</id> <value>VALUE_1</value> </loginField> <loginField> <id>FIELD_ID_2</id> <value>VALUE_2</value> </loginField> </loginForm>'

 

Have more questions? Submit a request

Comments

  • Avatar
    Uy Pham

    i would like to ask about "Modify Institution Login Credentials", I inputed full fields, but when i send request it showed : "

    10005
    Missing parameter (id)
    "

    - This is my body field
    "<loginForm> <loginField> <id> Banking  Userid</id> <value>demo</value> </loginField> <loginField> <id> Banking  Password</id> <value>gogo</value> </loginField> </loginForm>"

    - Where am i wrong ?

    Edited by Uy Pham
  • Avatar
    Chip Whitmer

    You used the values from the name fields instead of the id fields. The id values in your loginForm should be numbers: 101732001 and 101732002.

    Edited by Chip Whitmer
  • Avatar
    Uy Pham

    - Thank you, It worked. I would like to ask, After i changed password. How many time the new password will be effect ?

  • Avatar
    Chip Whitmer

    Please send questions like this in an email to support@finicity.com

    Edited by Chip Whitmer
Powered by Zendesk