--- 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` ## Request - Base URL: `https://api.ocrolus.com` - URL: `https://api.ocrolus.com/v1/book/upload/json` - Auth: OAuth 2 - Client credentials - Token URL: `https://auth.ocrolus.com/oauth/token` This API uploads aggregator-provided JSON data (Plaid or Finicity) to an Ocrolus <>. 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' ## Request body `multipart/form-data` - object - `pk` string, required: A unique primary key of the <> to which the uploaded JSON files will be added. This value is used interchangeably with a **`uuid`**. You must provide either **`pk`** or **`uuid`**. - `uuid` string, required: A universally unique identifier of the <> to which the uploaded JSON files will be added. This value is used interchangeably with a **`pk`**. You must provide either **`uuid`** or **`pk`**. - `upload` string, binary, required: The JSON file containing Plaid Asset Report or Transaction data. This should be the direct output from Plaid's API. - `accounts` string, binary: 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](https://docs.ocrolus.com/docs/aggregator-finicity#uploading-finicity-json-to-ocrolus) guide. - `transactions` string, binary: 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](https://docs.ocrolus.com/docs/aggregator-finicity#uploading-finicity-json-to-ocrolus) guide. - `customers` string, binary: 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](https://docs.ocrolus.com/docs/aggregator-finicity#uploading-finicity-json-to-ocrolus) guide. - `institutions` string, binary: 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](https://docs.ocrolus.com/docs/aggregator-finicity#uploading-finicity-json-to-ocrolus) guide. - `doc_name` string: The name of the <> created from the uploaded data. If omitted, defaults to **`audit_copy_token`**. ## 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 <>. - `uuid` string: Universally unique identifier (uuid) of the uploaded <>. - `name` string: Name of the <>. - `checksum` string: An alphanumerical value used to determine the authenticity of the data. - `created_ts` string: The timestamp at which the <> was created. - `id` integer: Unique primary key of the uploaded <>. - `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.dev/ocrolus/apis/file-uploads.md) - [All operations](https://skmtc.dev/ocrolus/apis/file-uploads/llms.txt) - [OpenAPI document](https://skmtc.dev/ocrolus/apis/file-uploads/revisions/f5da69c79aff?raw)