Customer Account Discovery, Activation, and Refresh

Services for discovering, activating, and refreshing customer accounts, including support for responding to MFA challenges. Up to six months of transactions are available.

See Multi-Factor Authentication (MFA) to understand MFA challenges.

See Customer Accounts for a detailed description of a customer account record.

See Active Docs to experiment directly with the API.

See Testing Accounts to understand how to validate your integration with these services.

Available services:

General Process to Add an Account

Use Process A if your app intends to activate all accounts that are available using the given credentials at the given institution. Use Process B if your app needs to select specific accounts for activation.

Process A: Add All Accounts

- POST Add All Accounts.

    - MFA response (HTTP 203) ?
        - YES: POST Add All Accounts (with MFA Answers).
        - Repeat MFA response check
    - Parse accounts from response.

Each step in this sequence builds on the request and/or the response from the previous step. To restate the process showing this progression from one step to another:

1) Call Add All Accounts with the login form returned from Get Institution Login Form.

2) When the call to Add All Accounts returns HTTP 203, replay the previous request, with these changes:

  • Copy the MFA-Session header from the previous response into the request.
  • Remove the <credentials> element from the request body. 
  • Append the <mfaChallenges> element from the previous response to the request body. 
  • Add the appropriate MFA answer inside each <question> element in the MFA challenge. 
  • Append /mfa to the path.

3) When Add All Accounts (with or without MFA) returns HTTP 200, the response contains the complete <account> records for the activated accounts.

4) If any account has type "unknown", the account number and name should be displayed to the customer, who must specify the correct account type by selecting a valid account type (see Account Types). Then call Activate Customer Accounts v2 (without Aggregation) to activate this account. This should be a rare occurrence.

Process B: Discover and Activate Individual Accounts

- POST Discover Customer Accounts.
    - MFA response (HTTP 203) ?
        - YES: POST Discover Customer Accounts (with MFA Answers).
        - Repeat MFA response check
    - Parse partial accounts from response.

    - Allow the customer to choose the accounts to be activated and to specify the correct account type for accounts with type unknown. (Partners may choose to always activate all accounts, but the customer must still be given the opportunity to specify an account type for accounts with type unknown.)

- PUT Activate Customer Accounts v2 (without Aggregation).
- POST Refresh Institution Login Accounts 

    - MFA response (HTTP 203) ?
        - YES: POST Refresh Institution Login Accounts (with MFA Answers).
        - Repeat MFA response check.
    - Special handling for timeout errors (see Handling Timeouts)
    - Parse complete accounts from response.

Each step in this sequence builds on the request and/or the response from the previous step. To restate the process showing this progression from one step to another:

1) Call Discover Customer Accounts with the login form returned from Get Institution Login Form.

2) When the call to Discover returns HTTP 203, replay the previous Discover request, with these changes:

  • Copy the MFA-Session header from the previous response into the request.
  • Remove the <credentials> element from the request body. 
  • Append the <mfaChallenges> element from the previous response to the request body. 
  • Add the appropriate MFA answer inside each <question> element in the MFA challenge.
  • Append /mfa to the path.

3) When Discover (with or without MFA) returns HTTP 200, allow the customer to choose the accounts to be activated and to specify the correct account type for accounts with type unknown. (Partners may choose to always activate all accounts, but the customer must still be given the opportunity to specify an account type for accounts with type unknown.)

4) Build the request for Activate Customer Accounts by copying the desired account records from the previous response into the new request, changing accounts with type unknown to give the type designated by the customer.

5) Build the request for Refresh Institution Login Accounts by copying the institutionLoginId from any records in the previous response into the URL.

6) When Refresh returns HTTP 203, replay the previous Activate request, making the same kinds of changes made in step #2 above.

7) Add handling for "timeout" conditions.

8) When Refresh (with or without MFA) returns HTTP 200, the response contains the complete account records for the activated accounts.

Credentials Record

Field Name Description
loginField A partial loginField record returned from Get Institution Login Form or Get Customer Account Login Form

Account Activation Errors

When a failure occurs during a call to Add All Accounts or Discover Customer Accounts, the system will automatically escalate the error for quick resolution by Finicity. This escalation has the same effect as if the client app made a call to Escalate Aggregation Error.

As an additional enhancement, customer credentials and MFA answers are now stored by Finicity during the activation process. This reduces the need for Finicity to request AAI (Additional Authentication Information) while troubleshooting and fixing the problem.

A description of the newly-created ticket is included in the error response. This information can be used in subsequent calls to the various Aggregation Support services.

<error>
<code>104</code>
<message>Parsing error.</message>
<ticket>
<accountIds>
<accountId>12345</accountId>
<accountId>67890</accountId>
</accountIds>
<createdDate>1450249200</createdDate>
<id>2519</id>
<institutionId>100002</institutionId>
<resolutionDate>1450335600</resolutionDate>
<status>new</status>
</ticket>
</error>
(No ticket is created when the code requires action by the client app or the customer, as outlined in the Error Codes document.)

Add All Accounts

POST /v1/customers/{customerId}/institutions/{institutionId}/accounts/addall

Discover and activate all accounts available using the specified credentials at the given institution, without performing aggregation.

HTTP status 200 means all accounts have been added.

HTTP status 203 means the response contains an MFA challenge. Go to Add All Accounts (with MFA Answers).

This service combines functionality from Discover Customer Accounts and Activate Customer Accounts v2 (without Aggregation) to simplify and accelerate the process of adding accounts to the Finicity system.

A client app should use this service if the app intends to activate all accounts that are available using the given credentials at the given institution. A client app that needs to select specific accounts for activation should continue using the detailed activation sequence (Discover Customer Accounts followed by Activate Customer Accounts v1 or v2).

Upon return all accounts available using the given credentials at the given institution are active for daily aggregation, but no transactions have been retrieved from the institution for these accounts. To see transactions, clients must call Refresh Institution Login Accounts or Load Historic Transactions for Account sometime after calling this service. The app can decide whether to refresh the account immediately, or execute the refresh service in the background, or even skip refresh completely if the app is only interested in account-level details. (Note that the added accounts will still participate in regular daily aggregation on the standard Finicity schedule.)

Finicity can usually determine the correct type for each account, but in some rare cases the account type will be unknown and the status will be pending. In these cases, the account number and name should be displayed to the customer, who must specify the correct account type by selecting a value from the Account Types table. To activate the pending account, call Activate Customer Accounts v2 (without Aggregation) with the correct account type.

See Account Activation Errors for information about automatic tickets that can be generated by this call.

The recommended timeout setting for this request is 180 seconds.

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

The ID of the customer who owns the account

institutionId path

The Finicity ID of the account's institution

credentials JSON field

A list of credentials records

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/addall
{
"credentials": [
{
"id": "11863001",
"name": "id",
"value": "USER_ID"
},
{
"id": "11863002",
"name": "pin",
"value": "PASSWORD"
} ]
}

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/json" -H "Content-Type:application/json" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/addall" -d '{ "credentials": [ { "id": "11863001", "name": "id", "value": "USER_ID" }, { "id": "11863002", "name": "pin", "value": "PASSWORD" } ] }'

Response Details - HTTP 200 (OK)

A list of customer account records. (Can be partial account records if the type is unknown.)

Example Response - HTTP 200 (OK)

{
"accounts": [ { "id": "2083", "number": "8000008888", "name": "Auto Loan", "type": "loan", "status": "active", "balance": "-1234.56",
"customerId": "41442",
"institutionId": "101732",
"balanceDate": "1421996400",
"createdDate": "1415255907",
"lastUpdatedDate": "1421996400",
"detail": {
}
  },
{
"id": "3203", "number": "4100007777", "name": "Generic Account", "type": "unknown", "status": "pending" } ] }

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header MFA session identifier. Must be copied directly to the subsequent request for Add All Accounts (with MFA Answers).
mfaChallenges JSON field MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

{
"questions": [ { "text": "What color was your childhood home?" }, {
"text": "What was the last name of your favorite teacher?"
} ]
}

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

The ID of the customer who owns the account

institutionId path

The Finicity ID of the account's institution

accounts XML element

Root element

credentials XML element

A credentials record

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/addall
<accounts>
<credentials>
<loginField>
<id>11863001</id>
<name>id</name>
<value>USER_ID</value>
</loginField>
<loginField>
<id>11863002</id>
<name>pin</name>
<value>PASSWORD</value>
</loginField>
</credentials>
</accounts>

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -H "Accept:application/xml" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/addall" -d '<accounts> <credentials> <loginField> <id>11863001</id> <name>id</name> <value>USER_ID</value> </loginField> <loginField> <id>11863002</id> <name>pin</name> <value>PASSWORD</value> </loginField> </credentials> </accounts>'

Response Details - HTTP 200 (OK)

XML Name Description
accounts Root element
account A customer account record. (Can be a partial account record if the type is unknown.)

Example Response - HTTP 200 (OK)

<accounts>
  <account>
    <id>2083</id>
    <number>8000008888</number>
    <name>Auto Loan</name>
    <type>loan</type>
    <status>active</status>
    <balance>-1234.56</balance>
<customerId>41442</customerId>
<institutionId>101732</institutionId>
<balanceDate>1421996400</balanceDate>
<createdDate>1415255907</createdDate>
<lastUpdatedDate>1421996400</lastUpdatedDate>
<detail/>
  </account>
<account>
<id>3203</id> <number>4100007777</number> <name>Generic Account</name> <type>unknown</type> <status>pending</status> </account> </accounts>

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header MFA session identifier. Must be copied directly to the subsequent request for Add All Accounts (with MFA Answers).
mfaChallenges XML element MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

<mfaChallenges>
  <questions>
    <question>
      <text>What color was your childhood home?</text>
    </question>
    <question>
<text>What was the last name of your favorite teacher?</text>
</question>
</questions> </mfaChallenges>

Add All Accounts (with MFA Answers)
POST /v1/customers/{customerId}/institutions/{institutionId}/accounts/addall/mfa

Send MFA answers for an earlier challenge during Add All Accounts.

HTTP status of 200 means all accounts have been added.

HTTP status of 203 means the response contains another MFA challenge. Call Add All Accounts (with MFA Answers) again to answer the new challenge.

This service is invoked only if a previous call to Add All Accounts or Add All Accounts (with MFA Answers) has returned HTTP 203. The response from that previous call is referred to as "the previous response" below.

The call itself is a replay of the previous call, with several changes:

  • Copy the MFA-Session header from the previous response onto this request. 
  • Remove the <credentials> element from the request.
  • Append the <mfaChallenges> element from the previous response to the request body.
  • Add the appropriate MFA answer inside each <question> element in the MFA challenge.  
  • Append /mfa to the path.

The recommended timeout setting for this request is 180 seconds.

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
Accept HTTP header application/json
MFA-Session HTTP header

MFA session identifier. Copied directly from the previous response (the value will be different for each HTTP 203 response received)

customerId path

The ID of the customer who owns the account

institutionId path

The Finicity ID of the account's institution

credentials JSON field

A credentials record

mfaChallenges JSON field

MFA Challenge Segment

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/addall/mfa
{
"mfaChallenges": { "questions": [ {
"text": "What color was your childhood home?",
"answer": "Brown"
},
{ "text": "What was the last name of your favorite teacher?", "answer": "Green" } ] } }

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/json" -H "Accept:application/json" -H "MFA-Session:MFA_SESSION" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/addall/mfa" -d '{ "mfaChallenges": { "questions": [ { "text": "What color was your childhood home?", "answer": "Brown" }, { "text": "What was the last name of your favorite teacher?", "answer": "Green" } ] } }'

Response Details - HTTP 200 (OK)

A list of customer account records. (Can be partial account records if the type is unknown.)

Example Response - HTTP 200 (OK)

{
"accounts": [
{
"id": "2083",
"number": "8000008888",
"name": "Auto Loan",
"type": "loan",
"status": "active",
"balance": "-1234.56",
"aggregationStatusCode": "125",
"customerId": "41442",
"institutionId": "101732",
"balanceDate": "1421996400",
"aggregationSuccessDate": "1421996400",
"aggregationAttemptDate": "1423239602",
"createdDate": "1415255907",
"lastUpdatedDate": "1422467353",
"detail": {
}
},
{
"id": "3203",
"number": "4100007777",
"name": "Generic Account",
"type": "unknown",
"status": "pending"
} ]
}

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header MFA session identifier. Must be copied directly to the subsequent request for Add All Accounts (with MFA Answers).
mfaChallenges XML element MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

{
"questions": [
{
"text": "What color was your childhood home?"
},
{
"text": "What was the last name of your favorite teacher?"
} ]
}

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
Accept HTTP header application/xml
MFA-Session HTTP header

MFA session identifier. Copied directly from the previous response (the value will be different for each HTTP 203 response received)

customerId path

The ID of the customer who owns the account

institutionId path

The Finicity ID of the account's institution

accounts XML element

Root element

credentials XML element

A credentials record

mfaChallenges XML element

MFA Challenge Segment

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/addall/mfa
<accounts>
<mfaChallenges> <questions>
<question>
<text>What color was your childhood home?</text>
<answer>Brown</answer>
</question>
<question> <text>What was the last name of your favorite teacher?</text> <answer>Green</answer> </question> </questions> </mfaChallenges> </accounts>

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -H "Accept:application/xml"  -H "MFA-Session:MFA_SESSION" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/addall/mfa" -d '<accounts> <mfaChallenges> <questions> <question> <text>What color was your childhood home?</text> <answer>Brown</answer> </question> <question> <text>What was the last name of your favorite teacher?</text> <answer>Green</answer> </question> </questions> </mfaChallenges> </accounts>'

Response Details - HTTP 200 (OK)

XML Name Description
accounts Root element
account A customer account record. (Can be a partial account record if the type is unknown.)

Example Response - HTTP 200 (OK)

<accounts>
  <account>
    <id>2083</id>
    <number>8000008888</number>
    <name>Auto Loan</name>
    <type>loan</type>
    <status>active</status>
    <balance>-1234.56</balance>
<aggregationStatusCode>125</aggregationStatusCode>
<customerId>41442</customerId>
<institutionId>101732</institutionId>
<balanceDate>1421996400</balanceDate>
<aggregationSuccessDate>1421996400</aggregationSuccessDate>
<aggregationAttemptDate>1423239602</aggregationAttemptDate>
<createdDate>1415255907</createdDate>
<lastUpdatedDate>1422467353</lastUpdatedDate>
<detail/>
  </account>
<account>
<id>3203</id> <number>4100007777</number> <name>Generic Account</name> <type>unknown</type> <status>pending</status> </account> </accounts>

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header MFA session identifier. Must be copied directly to the subsequent request for Add All Accounts (with MFA Answers).
mfaChallenges XML element MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

<mfaChallenges>
<questions>
<question>
<text>Which high school did you attend?</text>
<choice value="Washington">Washington</choice>
<choice value="Jefferson">Jefferson</choice>
<choice value="Wilson">Wilson</choice>
</question>
</questions>
</mfaChallenges>

Discover Customer Accounts

POST /v1/customers/{customerId}/institutions/{institutionId}/accounts

Discover all accounts owned by the specified customer at the given institution. Use Discover Customer Accounts and Activate Customer Accounts if you need to select specific accounts for activation. Otherwise, use Add All Acounts instead.

HTTP status 200 means discovery was successful. Go to Activate Customer Accounts.

HTTP status 203 means the response contains an MFA challenge. Go to Discover Customer Accounts (with MFA Answers).

See Account Activation Errors for information about automatic tickets that can be generated by this call.

The recommended timeout setting for this request is 180 seconds.

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

The ID of the customer who owns the account

institutionId path

The Finicity ID of the account's institution

credentials JSON field

A list of credentials records

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts
{
"credentials": [
{
"id": "11863001",
"name": "id",
"value": "USER_ID"
},
{
"id": "11863002",
"name": "pin",
"value": "PASSWORD"
} ]
}

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/json" -H "Accept:application/json"  -X POST "https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts" -d '{ "credentials": [ { "id": "11863001", "name": "id", "value": "USER_ID" }, { "id": "11863002", "name": "pin", "value": "PASSWORD" } ] }'

Response Details - HTTP 200 (OK)

A list of partial account records (desired accounts must be copied into the subsequent request for Activate Customer Accounts).

Example Response - HTTP 200 (OK)

{ 
"accounts": [
{
"id": "2055",
"number": "XXXX-XXXXXX-32765",
"name": "Checking",
"balance": 1266.49,
"type": "checking",
"status": "pending"
},
{
"id": "5027",
"number": "XXXX-XXXXXX-36174",
"name": "Credit Card",
"balance": -1547.62,
"type": "creditCard",
"status": "pending"
} ]
}

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header MFA session identifier. Must be copied directly to the subsequent request for Discover Customer Accounts (with MFA Answers).
mfaChallenges JSON field MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

{
"questions": [
{
"text": "What color was your childhood home?"
},
{
"text": "What was the last name of your favorite teacher?"
} ]
}

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

The ID of the customer who owns the account

institutionId path

The Finicity ID of the account's institution

accounts XML element

Root element

credentials XML element

A credentials record

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts
<accounts>
<credentials>
<loginField>
<id>11863001</id>
<name>id</name>
<value>USER_ID</value>
</loginField>
<loginField>
<id>11863002</id>
<name>pin</name>
<value>PASSWORD</value>
</loginField>
</credentials>
</accounts>

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -H "Accept:application/xml"  -X POST "https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts" -d '<accounts> <credentials> <loginField> <id>11863001</id> <name>id</name> <value>USER_ID</value> </loginField> <loginField> <id>11863002</id> <name>pin</name> <value>PASSWORD</value> </loginField> </credentials> </accounts>'

Response Details - HTTP 200 (OK)

XML Name Description
accounts Root element
account A partial account record (desired accounts must be copied into the subsequent request for Activate Customer Accounts)

Example Response - HTTP 200 (OK)

<accounts>
  <account>
    <id>2055</id>
    <number>XXXX-XXXXXX-32765</number>
    <name>Checking</name>
<balance>1266.49</balance> <type>checking</type> <status>pending</status> </account> <account> <id>5027</id> <number>XXXX-XXXXXX-36174</number> <name>Credit Card</name>
<balance>-1547.62</balance> <type>creditCard</type> <status>pending</status> </account> </accounts>

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header MFA session identifier. Must be copied directly to the subsequent request for Discover Customer Accounts (with MFA Answers).
mfaChallenges XML element MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

<mfaChallenges>
  <questions>
    <question>
<text>What color was your childhood home?</text>
</question>
<question> <text>What was the last name of your favorite teacher?</text> </question> </questions> </mfaChallenges>

Discover Customer Accounts (with MFA Answers)

POST /v1/customers/{customerId}/institutions/{institutionId}/accounts/mfa

Send MFA answers for an earlier challenge during account discovery.

HTTP status of 200 means discovery was successful. Go to Activate Customer Accounts.

HTTP status of 203 means the response contains another MFA challenge. Call Discover Customer Accounts (with MFA Answers) again to answer the new challenge.

This service is invoked only if a previous call to Discover Customer Accounts or Discover Customer Accounts (with MFA Answers) has returned HTTP 203. The response from that previous call is referred to as "the previous response" below.

The call itself is a replay of the previous call, with four changes:

  • Copy the MFA-Session header from the previous response onto this request.
  • Remove the <credentials> element from the request body. 
  • Append the <mfaChallenges> element from the previous response to the request body.
  • Add the appropriate MFA answer inside each <question> element in the MFA challenge.
  • Append /mfa to the path.

The recommended timeout setting for this request is 180 seconds.

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 Must be application/xml
MFA-Session HTTP header

MFA session identifier. Copied directly from the previous response (the value will be different for each HTTP 203 response received)

customerId path

The ID of the customer who owns the account

institutionId path

The Finicity ID of the account's institution

mfaChallenges JSON field

MFA Challenge Segment

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/mfa
{
"mfaChallenges": {
"questions": [
{
"text": "What color was your childhood home?",
"answer": "Brown"
},
{
"text": "What was the last name of your favorite teacher?",
"answer": "Green"
} ]
}
}

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/json"-H "Accept:application/json" -H "MFA-Session:MFA_SESSION" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/mfa" -d '{ "mfaChallenges": { "questions": [ { "text": "What color was your childhood home?", "answer": "Brown" }, { "text": "What was the last name of your favorite teacher?", "answer": "Green" } ] } }'

Response Details - HTTP 200 (OK)

A list of partial account records (desired accounts must be copied into the subsequent request for Activate Customer Accounts).

Example Response - HTTP 200 (OK)

{ 
"accounts": [
{
"id": "2055",
"number": "XXXX-XXXXXX-32765",
"name": "Checking",
"balance": 1266.49,
"type": "checking",
"status": "pending"
},
{
"id": "5027",
"number": "XXXX-XXXXXX-36174",
"name": "Credit Card",
"balance": -1547.62,
"type": "creditCard",
"status": "pending"
} ]
}

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header MFA session identifier. Must be copied directly to the subsequent request for Discover Customer Accounts (with MFA Answers).
mfaChallenges JSON field MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

{
"questions": [
{
"text": "What color was your childhood home?"
},
{
"text": "What was the last name of your favorite teacher?"
} ]
}

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
Accept HTTP header application/xml
MFA-Session HTTP header

MFA session identifier. Copied directly from the previous response (the value will be different for each HTTP 203 response received)

customerId path

The ID of the customer who owns the account

institutionId path

The Finicity ID of the account's institution

accounts XML element

Root element

mfaChallenges XML element

MFA Challenge Segment

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/mfa
<accounts>
<mfaChallenges> <questions> <question>
<text>What color was your childhood home?</text>
  <answer>Brown</answer>
</question>
<question> <text>What was the last name of your favorite teacher?</text> <answer>Green</answer> </question> </questions> </mfaChallenges> </accounts>

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -H "Accept:application/xml" -H "MFA-Session:MFA_SESSION" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/mfa" -d '<accounts> <mfaChallenges> <questions> <question> <text>What color was your childhood home?</text> <answer>Brown</answer> </question> <question> <text>What was the last name of your favorite teacher?</text> <answer>Green</answer> </question> </questions> </mfaChallenges> </accounts>'

Response Details - HTTP 200 (OK)

XML Name Description
accounts Root element
account A partial account record (desired accounts must be copied into the subsequent request for Activate Customer Accounts)

Example Response - HTTP 200 (OK)

<accounts>
  <account>
    <id>2083</id>
    <number>8000008888</number>
    <name>Auto Loan</name>
<balance>1266.49</balance> <type>loan</type> <status>pending</status> </account> <account> <id>3203</id> <number>4100007777</number> <name>Visa</name>
<balance>-1547.62</balance> <type>creditCard</type> <status>pending</status> </account> </accounts>

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header MFA session identifier. Must be copied directly to the subsequent request for Discover Customer Accounts (with MFA Answers).
mfaChallenges XML element MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

<mfaChallenges>
  <questions>
    <question>
      <text>Which high school did you attend?</text>
      <choice value="Washington">Washington</choice>
      <choice value="Jefferson">Jefferson</choice>
      <choice value="Wilson">Wilson</choice>
    </question>
  </questions>
</mfaChallenges>

Activate Customer Accounts v2 (without Aggregation)
PUT /v2/customers/{customerId}/institutions/{institutionId}/accounts

Enable Finicity aggregation for the specified accounts, but do not actually perform aggregation.

This service returns quickly, does not invoke aggregation, and will never return an MFA challenge (HTTP 203).

After activation is complete, the app can decide whether to call Refresh Institution Login Accounts immediately, or execute Refresh Institution Login Accounts in the background, or even skip aggregation completely if the app is only interested in account-level details. (Note that the activated account will still participate in regular daily aggregation on the standard Finicity schedule.)

Upon successful return the specified accounts are active for daily aggregation, but no transactions have been retrieved from the institution for these accounts. To see transactions, clients must call Refresh Institution Login Accounts or Load Historic Transactions for Account sometime after calling this service. The app can decide whether to refresh the account immediately, or execute the refresh service in the background, or even skip refresh completely if the app is only interested in account-level details. (Note that the activated accounts will still participate in regular daily aggregation on the standard Finicity schedule.)

HTTP status of 200 means the activation operation is complete, and the full account records are in the body of the response.

This service will never return an MFA challenge (HTTP 203).

The recommended timeout setting for this request is 20 seconds.

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

The ID of the customer who owns the account

institutionId path

The Finicity ID of the account's institution

account XML element

A list of partial account records, copied from the response from Discover Customer Accounts. The <type> field cannot be unknown (see Account Types).

Example Request:

PUT https://api.finicity.com/aggregation/v2/customers/41442/institutions/101732/accounts
{ 
"accounts": [
{
"id": "2055",
"number": "XXXX-XXXXXX-32765",
"name": "Checking",
"balance": 1266.49,
"type": "checking",
"status": "pending"
},
{
"id": "5027",
"number": "XXXX-XXXXXX-36174",
"name": "Credit Card",
"balance": -1547.62,
"type": "creditCard",
"status": "pending"
} ]
}

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/json" -H "Accept:application/json"  -X PUT "https://api.finicity.com/aggregation/v2/customers/41442/institutions/101732/accounts" -d '{ "accounts": [ { "id": "2055", "number": "XXXX-XXXXXX-32765", "name": "Checking", "balance": 1266.49, "type": "checking", "status": "pending" }, { "id": "5027", "number": "XXXX-XXXXXX-36174", "name": "Credit Card", "balance": -1547.62, "type": "creditCard", "status": "pending" } ] }'

Response Details - HTTP 200 (OK)

A list of customer account records.

Example Response - HTTP 200 (OK)

{
"accounts": [
{
"id": "2083",
"number": "8000008888",
"name": "Auto Loan",
"type": "loan",
"status": "active",
"balance": "-1234.56",
"customerId": "41442",
"institutionId": "101732",
"balanceDate": "1421996400",
"createdDate": "1415255907",
"lastUpdatedDate": "1422467353",
"detail": {
}
},
 {
"id": "3203",
"number": "4100007777",
"name": "Visa",
"type": "creditCard",
"status": "active",
"balance": "-1208.25",
"customerId": "41442",
"institutionId": "101732",
"balanceDate": "1418022000",
"createdDate": "1418080904",
"lastUpdatedDate": "1422467353",
"detail": {
}
} ]
}

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

The ID of the customer who owns the account

institutionId path

The Finicity ID of the account's institution

accounts XML element

Root element

account XML element

A partial account record, copied from the response from Discover Customer Accounts. The <type> field cannot be unknown (see Account Types).

Example Request:

PUT https://api.finicity.com/aggregation/v2/customers/41442/institutions/101732/accounts
<accounts>
  <account>
    <id>2083</id>
    <number>8000008888</number>
    <name>Auto Loan</name>
    <type>loan</type>
    <status>pending</status>
  </account>
  <account>
    <id>3203</id>
    <number>4100007777</number>
    <name>Visa</name>
    <type>creditCard</type>
    <status>pending</status>
  </account>
</accounts>

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -H "Accept:application/xml" -X PUT "https://api.finicity.com/aggregation/v2/customers/41442/institutions/101732/accounts" -d '<accounts> <account> <id>2083</id> <number>8000008888</number> <name>Auto Loan</name> <type>loan</type> <status>pending</status> </account> <account> <id>3203</id> <number>4100007777</number> <name>Visa</name> <type>creditCard</type> <status>pending</status> </account> </accounts>'

Response Details - HTTP 200 (OK)

XML Name Description
accounts Root element
account A customer account record

Example Response - HTTP 200 (OK)

<accounts>
  <account>
    <id>2083</id>
    <number>8000008888</number>
    <name>Auto Loan</name>
    <type>loan</type>
    <status>active</status>
    <balance>-1234.56</balance>
<customerId>41442</customerId>
<institutionId>101732</institutionId>
<balanceDate>1421996400</balanceDate>
<createdDate>1415255907</createdDate>
<lastUpdatedDate>1422467353</lastUpdatedDate>
<detail/>
  </account>
<account>
<id>3203</id> <number>4100007777</number> <name>Visa</name> <type>creditCard</type> <status>active</status> <balance>-1208.25</balance>
<customerId>41442</customerId>
<institutionId>101732</institutionId>
<balanceDate>1418022000</balanceDate>
<createdDate>1418080904</createdDate>
  <lastUpdatedDate>1422467353</lastUpdatedDate>
</account> </accounts>

Refresh Institution Login Accounts

POST /v1/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts

Connect to the financial institution and refresh transaction data for all accounts associated with the given institutionLoginId. This is an interactive refresh, so MFA challenges may be required.

An Institution Login represents one set of credentials at a particular institution, together with all accounts accessible using those credentials at that institution.

Client apps are not permitted to automate calls to the Refresh services. Active accounts are automatically refreshed by Finicity once per day. Apps may call Refresh services for a specific customer when the customer opens the app, or when the customer directly invokes a Refresh action from the app.

Because many financial institutions only post transactions once per day, calling Refresh repeatedly is usually a waste of resources and is not recommended.

HTTP status of 200 means the refresh operation is complete, and the full account records are in the body of the response.

HTTP status of 203 means the response contains an MFA challenge. Go to Refresh Institution Login Accounts (with MFA Answers).

This service retrieves account data from the institution. This usually returns quickly, but in some scenarios may take a few minutes to complete, which can result in a timeout condition (usually HTTP 202, 408, or 504, but may show some other codes also). See Handling Timeouts for guidelines on handling this kind of error.

This service requires the HTTP header Content-Length: 0 because it is a POST request with no request body.

The recommended timeout setting for this request is 120 seconds.

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-Length HTTP header Must be 0 (this request has no body)
Accept 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)

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutionLogins/16537/accounts

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN"-H "Content-Length:0" -H "Accept:application/json" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/institutionLogins/16537/accounts" -d ''

Response Details - HTTP 200 (OK)

A list of customer account records.

Example Response - HTTP 200 (OK)

{
"accounts": [
{
"id": "2083",
"number": "8000008888",
"name": "Auto Loan",
"type": "loan",
"status": "active",
"balance": "-1234.56",
"customerId": "41442",
"institutionId": "101732",
"balanceDate": "1421996400",
"createdDate": "1415255907",
"lastUpdatedDate": "1422467353",
"detail": {
}
},
{
"id": "3203",
"number": "4100007777",
"name": "Visa",
"type": "creditCard",
"status": "active",
"balance": "-1208.25",
"customerId": "41442",
"institutionId": "101732",
"balanceDate": "1418022000",
"createdDate": "1418080904",
"lastUpdatedDate": "1422467353",
"detail": {
}
} ]
}

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header MFA session identifier. Must be copied directly to the following request for Refresh Institution Login Accounts (with MFA Answers).
mfaChallenges JSON field MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

{
"questions": [
{
"text": "What color was your childhood home?"
},
{
"text": "What was the last name of your favorite teacher?"
} ]
}

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-Length HTTP header Must be 0 (this request has no body)
Accept 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)

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutionLogins/16537/accounts

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Length:0" -H "Accept:application/xml" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/institutionLogins/16537/accounts" -d ''

Response Details - HTTP 200 (OK)

XML Name Description
accounts Root element
account A customer account record

Example Response - HTTP 200 (OK)

<accounts>
<account>
<id>2083</id>
<number>8000008888</number>
<name>Auto Loan</name>
<type>loan</type>
<status>active</status>
<balance>-1234.56</balance>
<customerId>41442</customerId>
<institutionId>101732</institutionId>
<balanceDate>1421996400</balanceDate>
<createdDate>1415255907</createdDate>
<lastUpdatedDate>1422467353</lastUpdatedDate>
<detail/>
</account>
<account>
<id>3203</id>
<number>4100007777</number>
<name>Visa</name>
<type>creditCard</type>
<status>active</status>
<balance>-1208.25</balance>
<customerId>41442</customerId>
<institutionId>101732</institutionId>
<balanceDate>1418022000</balanceDate>
<createdDate>1418080904</createdDate>
</account>
</accounts>

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header MFA session identifier. Must be copied directly to the following request for Refresh Institution Login Accounts (with MFA Answers).
mfaChallenges XML element MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

<mfaChallenges>
  <questions>
    <question>
<text>What color was your childhood home?</text>
</question>
<question> <text>What was the last name of your favorite teacher?</text> </question> </questions> </mfaChallenges>

Refresh Institution Login Accounts (with MFA Answers)

POST /v1/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts/mfa

Send MFA answers for an earlier challenge during institution login account refresh.

An Institution Login represents one set of credentials at a particular institution, together with all accounts accessible using those credentials at that institution.

Client apps are not permitted to automate calls to the Refresh services. Active accounts are automatically refreshed by Finicity once per day. Apps may call Refresh services for a specific customer when the customer opens the app, or when the customer directly invokes a Refresh action from the app.

Because many financial institutions only post transactions once per day, calling Refresh repeatedly is usually a waste of resources and is not recommended.

HTTP status of 200 means the refresh operation is complete, and the full account records are in the body of the response.

HTTP status of 203 means the response contains another MFA challenge. Repeat Refresh Institution Login Accounts (with MFA Answers).

This service retrieves account data from the institution. This usually returns quickly, but in some scenarios may take a few minutes to complete, which can result in a timeout condition (usually HTTP 202, 408, or 504, but may show some other codes also). See Handling Timeouts for guidelines on handling this kind of error.

This service is invoked only if a previous call to Refresh Institution Login Accounts or Refresh Institution Login Accounts (with MFA Answers) has returned HTTP 203. The response from that previous call is referred to as "the previous response" below. Note that this service requires a request body (the MFA challenge with answer), where the previous call had no body.

The call itself is a replay of the previous call, with four changes:

  • Copy the MFA-Session header from the previous response onto this request.
  • Append the <mfaChallenges> element from the previous response to the request body.
  • Add the appropriate MFA answer inside each <question> element in the MFA challenge.
  • Append /mfa to the path.

The recommended timeout setting for this request is 120 seconds.

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
Accept HTTP header application/json
MFA-Session HTTP header

Copied directly from the previous response (the value will be different for each HTTP 203 response received)

customerId path

The ID of the customer who owns the account

institutionLoginId path

The institution login ID (from the account record)

mfaChallenges XML element

MFA Challenge Segment

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutionLogins/16537/accounts/mfa
{
"mfaChallenges": {
"questions": [
{
"text": "What color was your childhood home?",
"answer": "Brown"
},
{
"text": "What was the last name of your favorite teacher?",
"answer": "Green"
} ]
}
}

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/json" -H "Accept:application/json" -H "MFA-Session:MFA_SESSION" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/institutionLogins/16537/accounts/mfa" -d '{ "mfaChallenges": { "questions": [ { "text": "What color was your childhood home?", "answer": "Brown" }, { "text": "What was the last name of your favorite teacher?", "answer": "Green" } ] } }'

Response Details - HTTP 200 (OK)

A list of customer account records.

Example Response - HTTP 200 (OK)

{
"accounts": [
{
"id": "2083",
"number": "8000008888",
"name": "Auto Loan",
"type": "loan",
"status": "active",
"balance": "-1234.56",
"aggregationStatusCode": "0",
"customerId": "41442",
"institutionId": "101732",
"balanceDate": "1421996400",
"aggregationSuccessDate": "1421996400",
"aggregationAttemptDate": "1423239602",
"createdDate": "1415255907",
"lastUpdatedDate": "1422467353",
"detail": {
}
},
{
"id": "3203",
"number": "4100007777",
"name": "Visa",
"type": "creditCard",
"status": "active",
"balance": "-1208.25",
"aggregationStatusCode": "0",
"customerId": "41442",
"institutionId": "101732",
"balanceDate": "1421996400",
"aggregationSuccessDate": "1421996400",
"aggregationAttemptDate": "1423239602",
"createdDate": "1415255907",
"lastUpdatedDate": "1422467353",
"detail": {
}
}
}
Response Details - HTTP 203 (MFA Challenge)
Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the subsequent request for Refresh Institution Login Accounts (with MFA Answers).
mfaChallenges JSON field MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

{
"questions": [
{
"text": "What color was your childhood home?"
},
{
"text": "What was the last name of your favorite teacher?"
} ]
}

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
Accept HTTP header application/xml
MFA-Session HTTP header

Copied directly from the previous response (the value will be different for each HTTP 203 response received)

customerId path

The ID of the customer who owns the account

institutionLoginId path

The institution login ID (from the account record)

mfaChallenges XML element

MFA Challenge Segment

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutionLogins/16537/accounts/mfa
<mfaChallenges> <questions> <question>
<text>What color was your childhood home?</text>
<answer>Brown</answer>
</question>
<question> <text>What was the last name of your favorite teacher?</text> <answer>Green</answer> </question> </questions> </mfaChallenges>

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -H "Accept:application/xml" -H "MFA-Session:MFA_SESSION" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/institutionLogins/16537/accounts/mfa" -d '<mfaChallenges> <questions> <question> <text>What color was your childhood home?</text> <answer>Brown</answer> </question> <question> <text>What was the last name of your favorite teacher?</text> <answer>Green</answer> </question> </questions> </mfaChallenges>'

Response Details - HTTP 200 (OK)

XML Name Description
accounts Root element
account A customer account record

Example Response - HTTP 200 (OK)

<accounts>
<account>
<id>2083</id>
<number>8000008888</number>
<name>Auto Loan</name>
<type>loan</type>
<status>active</status>
<balance>-1234.56</balance>
<customerId>41442</customerId>
<institutionId>101732</institutionId>
<balanceDate>1421996400</balanceDate>
<createdDate>1415255907</createdDate>
<lastUpdatedDate>1422467353</lastUpdatedDate>
<detail/>
</account>
<account>
<id>3203</id>
<number>4100007777</number>
<name>Visa</name>
<type>creditCard</type>
<status>active</status>
<balance>-1208.25</balance>
<customerId>41442</customerId>
<institutionId>101732</institutionId>
<balanceDate>1418022000</balanceDate>
<createdDate>1418080904</createdDate>
</account>
</accounts>
Response Details - HTTP 203 (MFA Challenge)
Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the subsequent request for Refresh Institution Login Accounts (with MFA Answers).
mfaChallenges XML element MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

<mfaChallenges>
  <questions>
    <question>
      <text>Which high school did you attend?</text>
      <choice value="Washington">Washington</choice>
      <choice value="Jefferson">Jefferson</choice>
      <choice value="Wilson">Wilson</choice>
    </question>
  </questions>
</mfaChallenges>

Refresh Customer Accounts (non-interactive)

POST /v1/customers/{customerId}/accounts

Connect to all of the customer's financial institutions and refresh the transaction data for all of the customer's accounts. This is a non-interactive refresh, so any MFA challenge will cause the account to fail with an aggregationStatusCode value of 185 or 187.

To recover an account that has state 185 or 187, call Refresh Institution Login Accounts during an interactive session with the customer, prompt the customer with the MFA challenge that is returned from that call, and then send that response to Refresh Institution Login Accounts (with MFA Answers).

This service retrieves account data from the institution. This usually returns quickly, but in some scenarios may take a few minutes to complete, which can result in a timeout condition (usually HTTP 202, 408, or 504, but may show some other codes also). See Handling Timeouts for guidelines on handling this kind of error.

Client apps are not permitted to automate calls to the Refresh services. Active accounts are automatically refreshed by Finicity once per day. Apps may call Refresh services for a specific customer when the customer opens the app, or when the customer directly invokes a Refresh action from the app.

Because many financial institutions only post transactions once per day, calling Refresh repeatedly is usually a waste of resources and is not recommended.

This service requires the HTTP header Content-Length: 0 because it is a POST request with no request body.

The recommended timeout setting for this request is 120 seconds.

  • JSON Implementation
  • XML Implementation

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-Length HTTP header

Must be 0 (this request has no body)

Accept HTTP header

application/json

customerId path

The ID of the customer who owns the accounts

Success: HTTP 200 (OK)

Example Request:

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

Using curl:

curl -v -H "Content-Type:application/xml" -H "Finicity-App-Key:APP_KEY" -H "Content-Length:0" -H "Accept:application/json" -H "Finicity-App-Token:ACCESS_TOKEN" -X PUT "https://api.finicity.com/aggregation/v1/customers/41442/accounts" -d ''

Response Details

A list of customer account records.

Example Response

{
"accounts": [
{
"id": "2083",
"number": "8000008888",
"name": "Auto Loan",
"type": "loan",
"status": "active",
"balance": "-1234.56",
"aggregationStatusCode": "0"
"customerId": "41442",
"institutionId": "101732",
"balanceDate": "1421996400",
"aggregationSuccessDate": "1421996400",
"aggregationAttemptDate": "1421996400",
"createdDate": "1415255907",
"lastUpdatedDate": "1421996400",
"detail": {
}
},
{
"id": "3203",
"number": "4100007777",
"name": "Visa",
"type": "creditCard",
"status": "active",
"balance": "-1208.25",
  "aggregationStatusCode": "185"
"customerId": "41442",
"institutionId": "101732",
"balanceDate": "1418022000",
  "aggregationSuccessDate": "1421996400",
"aggregationAttemptDate": "1421996400",
"createdDate": "1418080904",
"lastUpdatedDate": "1422467353",
"detail": {
}
} ]
}

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-Length HTTP header

Must be 0 (this request has no body)

Accept HTTP header

application/xml

customerId path

The ID of the customer who owns the accounts

Success: HTTP 200 (OK)

Example Request:

POST 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 "Content-Length:0" -H "Accept:application/xml" -X PUT "https://api.finicity.com/aggregation/v1/customers/41442/accounts" -d ''

Response Details

XML Name Description
accounts Root element
account A customer account record

Example Response

<accounts>
  <account>
    <id>2083</id>
    <number>8000008888</number>
    <name>Auto Loan</name>
    <type>loan</type>
    <status>active</status>
    <balance>-1234.56</balance>
<aggregationStatusCode>0</aggregationStatusCode>
<customerId>41442</customerId>
<institutionId>101732</institutionId>
<balanceDate>1421996400</balanceDate>
<aggregationSuccessDate>1421996400</aggregationSuccessDate>
<aggregationAttemptDate>1421996400</aggregationAttemptDate>
<createdDate>1415255907</createdDate>
<lastUpdatedDate>1421996400</lastUpdatedDate>
<detail/>
  </account>
<account>
<id>3203</id> <number>4100007777</number> <name>Visa</name> <type>creditCard</type> <status>active</status> <balance>-1208.25</balance>
<aggregationStatusCode>185</aggregationStatusCode>
<customerId>41442</customerId>
<institutionId>101732</institutionId>
<balanceDate>1418022000</balanceDate>
<aggregationSuccessDate>1418081117</aggregationSuccessDate>
<aggregationAttemptDate>1421996400</aggregationAttemptDate>
<createdDate>1418080904</createdDate>
</account> </accounts>
Have more questions? Submit a request

Comments

Powered by Zendesk