API
Start free trialRaise a request

Upload aggregator JSON to Book

post
https://api.ocrolus.com/v1/book/upload/json

This API uploads aggregator-provided JSON data (Plaid or Finicity) to an Ocrolus Book. This endpoint supports uploading:

  • Plaid Asset Report JSON
  • Plaid Transactions JSON
  • Finicity JSON bundles, including accounts, transactions, customers, and institutions

For Plaid, this endpoint takes the JSON output from Plaid's /transactions/get or /asset_report/get endpoints. To learn more, see the Plaid integration guide.

For Finicity, this endpoint requires a complete and internally consistent JSON bundle. Ocrolus validates references across files (accounts, customers, institutions, transactions) before generating accounts and periods. Partial Finicity uploads are not supported. To learn more, see the Account aggregator guide.

👍

Tips

  • You can upload multiple JSON files at a time using this endpoint.
  • For best results, create a separate Book for each Plaid Asset Report. Do not upload JSON files alongside PDF statements, as the data may not reconcile.
  • When multiple Finicity JSON files are uploaded, they are combined into a single document within the Book.
  • This is a shared endpoint for all both Plaid and Finicity JSON uploads. Aggregator-specific behavior is controlled using the aggregate_source parameter.
  • Ensure that all the Finicity JSON files originate from the same Finicity data pull and belong to the same account set.
  • Verify that all cross-file identifiers of Finicity (accountId, customerId, institutionId) resolve correctly.

Plaid and Finicity statement period construction

Plaid Asset Reports do not provide explicit statement periods. Ocrolus constructs periods based on transaction dates. For example, if transactions span Jan 15 to Apr 4, statement periods are created as:

  • Jan 15 - Jan 31
  • Feb 1 - Feb 28
  • Mar 1 - Mar 31
  • Apr 1 - Apr 4

❗️

Having unusual problems?

Do not use older versions of Plaid’s Python or Ruby client libraries to access these endpoints. Users have reported access issues with outdated versions. Upgrade to the latest available client libraries before proceeding. If you believe this behavior is a bug, open a support ticket with Plaid. As a temporary workaround, use a general-purpose HTTP request library.

Query Params
string
enum

Specifies the intent to process the Plaid JSON files uploaded to a Book. This parameter determines whether the uploaded transactions are simply added to the Book for analytics or actively compared against existing bank statement data to detect mismatches.

The available options to set intent are:

  • add_analytics: Adds transactions from the Plaid JSON to the Book without performing mismatch detection. Use this option for ongoing monitoring or when you only need to enrich the dataset with additional Plaid transactions. (Default if no value is specified.)
  • docs_to_digital: Runs the Docs-to-Digital algorithm. If used, the Plaid transactions are matched against bank statement data available in the Book, and any mismatches are flagged for review. Use this option when you want to perform reconciliation between digital (Plaid) and analog (PDF) sources.
Allowed:
string
enum
Defaults to PLAID

Specifies the data aggregator source used to generate the uploaded JSON. This field is case-sensitive. If no value is provided, the system defaults to PLAID.

Allowed:
Body Params
string
required

A unique primary key of the Book to which the uploaded JSON files will be added. This value is used interchangeably with a uuid. You must provide either pk or uuid.

string
required

A universally unique identifier of the Book to which the uploaded JSON files will be added. This value is used interchangeably with a pk. You must provide either uuid or pk.

file
required

The JSON file containing Plaid Asset Report or Transaction data. This should be the direct output from Plaid's API.

file

JSON files containing Finicity account data. This file is used to create bank account information associated with the Book. Must be valid JSON.

To learn more about uploading Finicity JSON file containing account details, see the Uploading Finicity JSON to Ocrolus guide.

file

JSON file containing Finicity transaction data. This file is used to create period and transaction data for the associated bank accounts identified in the accounts JSON. Must be valid JSON.

To learn more about uploading Finicity JSON file containing transaction details, see the Uploading Finicity JSON to Ocrolus guide.

file

JSON file containing Finicity customer data. It is used to associate customer information with the uploaded bank accounts and transactions. The account holder name is extracted from this JSON. Must be valid JSON.

To learn more about uploading Finicity JSON file containing customer details, see the Uploading Finicity JSON to Ocrolus guide.

file

JSON files containing Finicity institution data. It is used to map accounts to their respective financial institutions (banks). Must be valid JSON.

To learn more about uploading Finicity JSON file containing institution details, see the Uploading Finicity JSON to Ocrolus guide.

string

The name of the Document created from the uploaded data. If omitted, defaults to audit_copy_token.

Responses

Updated 21 days ago

Language
Credentials
OAuth2
Request
Response 
 Choose an example:
application/json
Updated 21 days ago