Customer Accounts

A customer account represents an account in a supported institution. Finicity's Customer Account resource includes services for maintaining customer account records and for modifying the credentials stored to access those customer 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:

Customer Account Record

The following fields are available in an account record:

(Fields marked with an asterisk * are included in a partial account record for pending accounts.)

Field Name Description
*id The ID of the account
*number The account number from the institution (all digits except the last four are obfuscated)
*name The account name from the institution
*type One of the values from Account Types (cannot be unknown for calls to Activate Customer Accounts)
*status pending during account discovery, always active following successful account activation
*balance The cleared balance of the account as-of balanceDate
aggregationStatusCode The status of the most recent aggregation attempt (see Handling Aggregation Status Codes)
customerId The Finicity ID of the customer associated with this account 
institutionId The Finicity ID of the institution for this account
balanceDate A timestamp showing when the balance was captured (see Handling Dates and Times)
aggregationSuccessDate A timestamp showing the last successful aggregation of the account (see Handling Dates and Times)
aggregationAttemptDate A timestamp showing the last aggregation attempt, whether successful or not (see Handling Dates and Times)
createdDate A timestamp showing when the account was added to the Finicity system(see Handling Dates and Times)
lastUpdatedDate A timestamp showing when the account was last modified (see Handling Dates and Times)
institutionLoginId The institution login ID (see Institution Logins)
detail Optional XML element with other details, dependent on the institution and the account type (see Account Details, below)

Account Details: Checking / Savings / CD / Money Market

Accounts with type checking, savings, cd, or moneyMarket may include an optional detail element with one or more of these fields:

Field Name Description
availableBalanceAmount The available balance (typically the current balance minus any pending transactions)
interestYtdAmount Interest accrued year-to-date
periodInterestRate The interest rate for the current period
periodInterestAmount Interest accrued during the current period

Account Details: Credit Card / Line of Credit

Accounts with type creditCard or lineOfCredit may include an optional detail element with one or more of these fields:

Field Name Description
creditMaxAmount The account's credit limit
creditAvailableAmount The available credit (typically the credit limit minus the current balance)
paymentMinAmount Minimum payment due
paymentDueDate Due date for the next payment
lastPaymentAmount The amount received in the last payment
lastPaymentDate The date of the last payment
interestRate The account's current interest rate
cashAdvanceInterestRate Interest rate for cash advances

Account Details: Mortgage / Loan

Accounts with type mortgage or loan may include an optional detail element with one or more of these fields:

Field Name Description
interestRate The interest rate
nextPaymentDate Due date for the next payment
nextPayment Minimum payment due
escrowBalance The escrow balance
payoffAmount The amount required to payoff the loan
principalBalance The principal balance
ytdInterestPaid Interest paid year-to-date
ytdPrincipalPaid Principal paid year-to-date
lastPaymentAmount The amount of the last payment
lastPaymentReceiveDate The date of the last payment

Account Details: Investment

Accounts with type investment may include an optional detail element with one or more of these fields:

Field Name Description
availableCashBalance Amount available for cash withdrawal

Get Customer Accounts

GET /v1/customers/{customerId}/accounts

Get details for all accounts owned by the specified customer.

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

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/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/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

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/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/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>
    <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>
    <createdDate>1420653087</createdDate>
  </account>
</accounts>

Get Customer Accounts by Institution
GET /v1/customers/{customerId}/institutions/{institutionId}/accounts

Get details for all active accounts owned by the specified customer at 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

customerId path

The ID of the customer who owns the accounts

institutionId path

The ID of the institution

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/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/institutions/101732/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 who owns the accounts

institutionId path

The ID of the institution

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/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/institutions/101732/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>
    <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>
    <createdDate>1420653087</createdDate>
  </account>
</accounts>

Get Customer Account

GET /v1/customers/{customerId}/accounts/{accountId}

Get details for the specified account.

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 who owns the account

accountId path

The Finicity ID of the account to be retrieved

Success: HTTP 200 (OK)

Example Request:

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

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/accounts/2055"

Response Details:

A single account record.

Example Response:

{
"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
}

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 who owns the account

accountId path

The Finicity ID of the account to be retrieved

Success: HTTP 200 (OK)

Example Request:

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

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/accounts/2055"

Response Details:

An XML document containing one account record.

Example Response:

<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>
  <lastUpdatedDate>1422421087</lastUpdatedDate>
</account>

Modify Customer Account

PUT /v1/customers/{customerId}/accounts/{accountId}

Modify some details for the specified account. It may be necessary to call this service if the account details have changed at the institution itself.

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

accountId path

The Finicity ID of the account to be modified

number JSON field

New value for the account's <number> field (optional)

name JSON field

New value for the account's <name> field (optional)

Success: HTTP 204 (No Content)

Example Request:

PUT https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055
{
"number": "ACCT_NUMBER",
"name": "ACCT_NAME"
}

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/accounts/2055" -d '{ "number": "ACCT_NUMBER", "name": "ACCT_NAME" }'

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

accountId path

The Finicity ID of the account to be modified

account XML element

Root element

number XML element

New value for the account's <number> field (optional)

name XML element

New value for the account's <name> field (optional)

Success: HTTP 204 (No Content)

Example Request:

PUT https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055
<account>
<number>ACCT_NUMBER</number>
<name>ACCT_NAME</name>
</account>

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/accounts/2055" -d '<account> <number>ACCT_NUMBER</number> <name>ACCT_NAME</name> </account>'

Delete Customer Account

DELETE /v1/customers/{customerId}/accounts/{accountId}

Remove the specified account from the Finicity system.

(Note that the request and response are the same for JSON and XML clients.)

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
customerId path

The ID of the customer whose account are to be deleted

accountId path

The Finicity ID of the account to be deleted

Success: HTTP 204 (No Content)

Example Request:

DELETE https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -X DELETE "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055" -d ''

Get Customer Account Login Form

GET /v1/customers/{customerId}/accounts/{accountId}/loginForm

Get the login fields for the specified account.

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 who owns the account

accountId path

The Finicity ID of the account to be retrieved

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/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/customers/41442/accounts/2055/loginForm"

Response Details:

Field Name Description
loginForm A list of loginField records

Example Response:

{
"loginForm": [
{
"id": 101732001,
"name": "Banking Userid",
"value": "USERNAME",
"description": "Banking Userid",
"mask": "false",
"displayOrder": 1
},
{
"id": 101732002,
"name": "Banking Password",
"value": "",
"description": "Banking Password",
"mask": "true",
"displayOrder": 2
}
]
}

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 who owns the account

accountId path

The Finicity ID of the account to be retrieved

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/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/customers/41442/accounts/2055/loginForm"

Response Details:

XML Name Description
loginForm Root element
loginField A loginField record

Example Response:

<loginForm>
  <loginField>
    <id>101732001</id>
    <name>Banking Userid</name>
    <value>USERNAME</value>
    <mask>false</mask>
    <displayOrder>1</displayOrder>
  </loginField>
  <loginField>
    <id>101732002</id>
    <name>Banking Password</name>
    <value></value>
    <mask>true</mask>
    <displayOrder>2</displayOrder>
  </loginField>
</loginForm>

 

Have more questions? Submit a request

Comments

Powered by Zendesk