Finicity

Finicity provides access to borrower bank account and transaction data in JSON format. Depending on your integration, Finicity JSON data may be obtained through borrower-initiated flows, backend processes, or batch data retrieval.

Ocrolus does not require a specific Finicity integration pattern. As long as the Finicity JSON files are generated by Finicity and belong to the same data pull, they can be ingested into Ocrolus for processing.

📘

Note

• Finicity uploads must include all required JSON files from the same Finicity data pull. Partial uploads are not supported.
• Finicity JSON ingestion is used for analytics enrichment and does not perform reconciliation against PDF bank statements.
• Ensure that all cross-file identifiers (such as account IDs, customer IDs, and institution IDs) resolve correctly across the uploaded files.
• Subscribe to the document.verification_failed webhook event to receive notifications if JSON reconciliation fails. To learn more, see the Webhook page.

Uploading Finicity JSON to Ocrolus

Finicity provides bank data across multiple JSON files that together represent a complete data bundle. To ingest Finicity data into Ocrolus, perform the following steps:

1. Create a new Book to house the Finicity data.
2. Upload the required Finicity JSON files to the Book using the Upload Aggregator JSON endpoint. For each Use the JSON obtained from the corresponding Mastercard endpoints:
   • Accounts: This JSON file contains Finicity account data. It is used to create bank account information associated with the Book. Use the JSON returned from the Get Customer Accounts by Institution ID (Simple) endpoint to upload accounts details.
   • Transactions: This JSON file contains Finicity transaction data. This file is used to create period and transaction data for the associated bank accounts identified in the accounts JSON. Use the JSON returned from the Get All Customer Transaction endpoint to upload transactions details.

     📘

     Note

     When submitting the Transactions JSON, set showDailyBalance to true to ensure successful submission of the output JSON.

   • Customers: This JSON file contains Finicity customer data. It is used to associate customer information with the uploaded bank accounts and transactions. Use the JSON returned from the Get Customer by ID endpoint to upload accounts details
   • Institutions: This JSON file contains Finicity institution data. It is used to map accounts to their respective financial institutions (banks). Use the JSON returned from the Get Institution by ID endpoint to upload transactions details.
3. Once the Finicity JSON data is successfully ingested, you can access borrower bank data using Ocrolus’s Transactions and SMB analytics endpoints.

Rejection reasons

While parsing the document, a document may be successfully uploaded but later rejected during processing. Common rejection reasons include:

• Finicity JSON Parse Error: The uploaded Finicity JSON file could not be parsed due to invalid or malformed data.
• Finicity Customer Not Found: The accounts.customerId does not match any customer.id in the customers JSON.
• Finicity Institution Not Found: The accounts.institutionId does not match any institution.id in the institutions JSON.
• Finicity Account Not Found: The transactions.accountId does not exist in the accounts JSON.
• Finicity Insufficient Transaction Data: The uploaded Finicity transactions JSON does not contain sufficient data to generate periods for the account.