Sign in

v1

latestOpenAPI 3.0.02026-07-2482421001.1 KB
File Uploads

Upload aggregator JSON to Book

This API uploads aggregator-provided JSON data (Plaid or Finicity) to an Ocrolus <glossary: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.

post/v1/book/upload/json

Query parameters

upload_intent'add_analytics' | 'docs_to_digital'

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.
aggregate_source'FINICITY' | '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.

Response

200

OR

Example response

{
  "status": 200,
  "response": {
    "uploaded_docs": [
      {
        "uuid": "8dc88eed-2b6f-414a-82f2-a99bd181cf6e",
        "name": "plaid-asset-and-txn.json",
        "checksum": "50a62f72f4b5b80b18f75fbed690dc47",
        "created_ts": "2023-05-25T17:23:45Z"
      }
    ]
  },
  "message": "OK"
}