Cash Flow Verification (Historic Transactions)

Services to retrieve up to twelve months or more of historic transactions for an account.

The availability of historic transactions depends on the institution itself. Some institutions provide only three or four months of transactions; others provide twelve, eighteen, or twenty-four months.

See Active Docs to experiment directly with the API.

Available services:

Load Historic Transactions for Account

POST /v1/customers/{customerId}/accounts/{accountId}/transactions/historic

Connect to the account's financial institution and load up to twelve months of historic transactions for the account. For some institutions, up to two years of history may be available.

This is a premium service. The billing rate is the variable rate for Cash Flow Verification under the current subscription plan. The billable event is a call to this service specifying a customerId that has not been seen before by this service. (If this service is called multiple times with the same customerId, to load transactions from multiple accounts, only one billable event has occurred.)

HTTP status of 204 means historic transactions have been loaded successfully. The transactions are now available by calling Get Customer Account Transactions.

HTTP status of 203 means the response contains an MFA challenge. Go to Load Historic Transactions for Account (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 usually requires the HTTP header Content-Length: 0 because it is a POST request with no request body.

The date range sent to the institution is calculated from the account's createdDate. This means that calling this service a second time for the same account normally will not add any new transactions for the account. For this reason, a second call to this service for a known accountId will usually return immediately with HTTP 204.

In a few specific scenarios, it may be desirable to force a second connection to the institution for a known accountId. Some examples are:

  • The institution's policy has changed, making more transactions available.
  • Finicity has now added Cash Flow Verification support for the institution.
  • The first call encountered an error, and the resulting Aggregation Ticket has now been fixed by the Finicity Support Team.

In these cases, the POST request can contain the parameter force=true in the request body to force the second connection.

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 Usually application/json
    To force execution: application/x-www-form-urlencoded
Content-Length HTTP header Usually 0 (this request has no body)
    To force execution: 10, and add the body: force=true
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 refreshed

Example Request:

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

Using curl:

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

Response Details - HTTP 204 (No Content)

No content in the response body.

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the following request for Load Historic Transactions for Account (with MFA Answers).
questions JSON field MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

{
"questions": [
{
"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 Usually application/xml
    To force execution: application/x-www-form-urlencoded
Content-Length HTTP header Usually 0 (this request has no body)
    To force execution: 10, and add the body: force=true
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 refreshed

Example Request:

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

Using curl:

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

Response Details - HTTP 204 (No Content)

No content in the response body.

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the following request for Load Historic Transactions for Account (with MFA Answers).
mfaChallenges XML element MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

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

Load Historic Transactions for Account (with MFA Answers)

POST /v1/customers/{customerId}/accounts/{accountId}/transactions/historic/mfa

Send MFA answers for an earlier challenge during loading of historic transactions.

HTTP status of 204 means historic transactions have been loaded successfully. The transactions are now available by calling Get Customer Account Transactions.

HTTP status of 203 means the response contains another MFA challenge. Go to Load Historic Transactions for Account (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 Load Historic Transactions for Account or Load Historic Transactions for Account (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.
  • Copy the MFA challenge from the previous response into the request body. 
  • Add the MFA answer inside the 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

accountId path

The Finicity ID of the account to be refreshed

mfaChallenges XML element

MFA Challenge Segment

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083/transactions/historic/mfa
{
"questions": [
{
"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/accounts/2083/transactions/historic/mfa" -d '{ "questions": [ { "text": "What was the last name of your favorite teacher?", "answer": "Green" } ] }'

Response Details - HTTP 204 (No Content)

No content in the response body.

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the subsequent request for Load Historic Transactions for Account (with MFA Answers).
mfaChallenges JSON field MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

{
"questions": [
{
"text": "Enter your first pet's 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
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

accountId path

The Finicity ID of the account to be refreshed

mfaChallenges XML element

MFA Challenge Segment

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083/transactions/historic/mfa
<mfaChallenges> <questions> <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/accounts/2083/transactions/historic/mfa" -d '<mfaChallenges> <questions> <question> <text>What was the last name of your favorite teacher?</text> <answer>Green</answer> </question> </questions> </mfaChallenges>'

Response Details - HTTP 204 (No Content)

No content in the response body.

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the subsequent request for Load Historic Transactions for Account (with MFA Answers).
mfaChallenges XML element MFA Challenge Segment

Example Response - HTTP 203 (MFA Challenge)

<mfaChallenges>
<questions>
<question>
<text>Enter your first pet's name:</text>
</question>
</questions>
</mfaChallenges>
Have more questions? Submit a request

Comments

Powered by Zendesk