---
title: "Upload aggregator JSON to Book"
method: POST
path: "/v1/book/upload/json"
tags: ["File Uploads"]
---

# Upload aggregator JSON to Book

`POST /v1/book/upload/json`

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`**](https://plaid.com/docs/api/products/#transactionsget) or [**`/asset_report/get`**](https://plaid.com/docs/api/products/#asset_reportget) endpoints. To learn more, see the [Plaid integration](https://docs.ocrolus.com/docs/plaid) 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](https://docs.ocrolus.com/docs/aggregator-finicity) 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 parameters

- `upload_intent` 'add_analytics' | 'docs_to_digital'
- `aggregate_source` 'FINICITY' | 'PLAID'

## Response `200`

200

- union
  - object
    - `status` integer — A numerical code that indicates the status of the request.
    - `response` object — An object received from the server that potentially contains data.
      - `uploaded_docs` object[]
        - `pk` integer — The primary key of the <<glossary:Document>>.
        - `uuid` string — Universally unique identifier (uuid) of the uploaded <<glossary:Document>>.
        - `name` string — Name of the <<glossary:Document>>.
        - `checksum` string — An alphanumerical value used to determine the authenticity of the data.
        - `created_ts` string — The timestamp at which the <<glossary:Document>> was created.
        - `id` integer — Unique primary key of the uploaded <<glossary:Document>>.
    - `message` string — A textual description that indicates details about this response's status.
  - object
    - `status` integer — A numerical code that indicates the status of the request.
    - `response` object — An object received from the server that potentially contains data.
      - `status` integer — A numerical code that indicates the status of the request.
      - `message` string — A textual description that indicates details about this response's status.
    - `message` string — A textual description that indicates details about this response's status.

## Other responses

- `400` — Client Errors

---

[API](https://skmtc.net/ocrolus/apis/user-management.md) · [All operations](https://skmtc.net/ocrolus/apis/user-management/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ocrolus/user-management/versions/3571ef602d13/schema)