Account Ownership Verification (PDF Statements)

Account Ownership Verification provides the ability to download, directly from the institution, an account's most recent statement as a PDF document. Finicity's Account Ownership Verification Service includes services for downloading PDF statements for customer accounts, including support for responding to MFA challenges.

(MFA means Multi-Factor Authentication, describing various styles of authentication challenges such as text questions, image matching, “captcha” images, etc.)

See Active Docs to experiment directly with the API.

Available services:

Get Customer Account Statement

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

Connect to the account's financial institution and download the most recent monthly statement for the account, in PDF format. This is an interactive refresh, so MFA challenges may be required.

This is a premium service. The billing rate is the variable rate for Account Ownership Verification under the current subscription plan. The billable event is a successful call to this service.

HTTP status of 200 means the statement was retrieved successfully, and the body of the response contains the bytes of the PDF document.

HTTP status of 203 means the response contains an MFA challenge in XML or JSON format. Go to Get Customer Account Statement (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.

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
Accept HTTP header application/pdf,application/json (the document will be in PDF format, but errors or MFA will be JSON)
customerId path The ID of the customer who owns the account
accountId path The Finicity ID of the account

Example Request

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

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/pdf,application/json" -X GET "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083/statement"

Response Details - HTTP 200 (OK)

Parameter Type Description
Content-Type HTTP header application/pdf

The contents of the response are the bytes of the requested PDF document.

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the subsequent request for Get Customer Account Statement (with MFA Answers).
Content-Type HTTP header application/json
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
Accept HTTP header

application/pdf,application/xml (the document will be in PDF format, but errors or MFA will be XML)

customerId path

The ID of the customer who owns the account

accountId path

The Finicity ID of the account

Example Request

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

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/pdf,application/xml" -X GET "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083/statement"

Response Details - HTTP 200 (OK)

Parameter Type Description
Content-Type HTTP header application/pdf

The contents of the response are the bytes of the requested PDF document.

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the subsequent request for Get Customer Account Statement (with MFA Answers).
Content-Type HTTP header application/xml
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> 

Get Customer Account Statement (with MFA Answers)

POST /v1/customers/{customerId}/accounts/{accountId}/statement/mfa

Send MFA answers for an earlier challenge while getting an account statement.

HTTP status of 200 means the statement was retrieved successfully, and the body of the response contains the bytes of the PDF document.

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

This service is invoked only if a previous call to Get Customer Account Statement or Get Customer Account Statement (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:

  • Change the request method from GET to POST.
  • Append /mfa to the path.
  • Add a Content-Type header with the value application/json or application/xml
  • 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. 

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

application/pdf,application/json

Content-Type 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

questions JSON parent

MFA Challenge Segment

Example Request

POST https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083/statement/mfa
{
"questions": [
{
"text": "What was the last name of your favorite teacher?",
"answer": "Green"
}
]
}

Using curl:

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

Response Details - HTTP 200 (OK)

Parameter Type Description
Content-Type HTTP header application/pdf

The contents of the response are the bytes of the requested PDF document.

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the subsequent request for Get Customer Account Statement (with MFA Answers).
Content-Type HTTP header application/xml
questions JSON parent 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
Accept HTTP header

application/pdf,application/xml

Content-Type 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

mfaChallenges XML element

MFA Challenge Segment

Example Request

POST https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083/statement/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 "Content-Type:application/xml" -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/pdf,application/xml" -H "Content-Type:application/xml" -H "MFA-Session:MFA_SESSION" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2083/statement/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 200 (OK)

Parameter Type Description
Content-Type HTTP header application/pdf

The contents of the response are the bytes of the requested PDF document.

Response Details - HTTP 203 (MFA Challenge)

Parameter Type Description
MFA-Session HTTP header Session identifier. Must be copied directly to the subsequent request for Get Customer Account Statement (with MFA Answers).
Content-Type HTTP header application/xml
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