Ocrolus File Uploads API
The File Uploads API from Ocrolus — 7 operation(s) for file uploads.
OpenAPI Specification
openapi: 3.0.0
info:
title: Account Level Webhooks Book Commands File Uploads API
version: 1.0.0
servers:
- url: https://api.ocrolus.com
security:
- oauth: []
tags:
- name: File Uploads
paths:
/v1/book/upload:
post:
summary: Upload PDF to Book
operationId: upload-pdf-to-book
description: "Upload a PDF file to a <<glossary:Book>> for processing.\n\n---\nYou can upload a file to this endpoint as a `multipart/form-data` encoded payload. Visit [our guide](https://docs.ocrolus.com/reference/multipartform-data-payloads) for more information. \n> \U0001F4D8 \n> - The maximum file size for upload is 200 MB.\n\n\nFor all Documents *except* bank statements, the optional `form_type` parameter can be used to specify the type of <<glossary:Document>>. \n\nYou can see form types we support in our [forms directory](https://docs.ocrolus.com/docs/all-supported-documents). For more information, please contact your Account Executive or Customer Success Executive to discuss other options for your organization."
tags:
- File Uploads
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- upload
properties:
upload:
type: string
description: The PDF file to upload.
format: binary
book_uuid:
type: string
description: The unique identifier of the <<glossary:Book>> that the uploaded <<glossary:Document>> will be saved to. Mutually exclusive with `pk`.
pk:
type: string
description: The <<glossary:PK>> of the <<glossary:Book>> that the uploaded <<glossary:Document>> will be saved to. Mutually exclusive with `book_uuid`.
form_type:
type: string
description: The code identifying the type of <<glossary:Document>> that you're uploading.
doc_name:
type: string
description: The name of the <<glossary:Document>> that will be created from the imported file. Defaults to the name of the file if not given.
example:
pk: 30219565
book_uuid: 19aab921-25a5-4beb-a59e-ac72320061d6
form_type: PAYSTUB
doc_name: example_document
x-readme:
headers:
- key: content-type
value: multipart/form-data
samples-languages:
- curl
- python
explorer-enabled: false
code-samples:
- language: curl
name: Sample cURL Code
code: "curl --request POST 'https://api.ocrolus.com/v1/book/upload' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <BEARER_TOKEN>' \\\n --form 'book_uuid=19aab921-25a5-4beb-a59e-ac72320061d6' \\\n --form 'form_type=W2' \\\n --form 'doc_name=ExampleDocument' \\\n --form 'upload=@/path/to/example-w2.pdf'"
- language: python
name: Sample Python Code
code: "import requests\nresponse = requests.post(\n url = 'https://api.ocrolus.com/v1/book/upload',\n\n headers = {\n 'Accept': 'application/json',\n 'Authorization': 'Bearer <BEARER_TOKEN>',\n },\n\n data = {\n 'book_uuid': '19aab921-25a5-4beb-a59e-ac72320061d6', # The book's primary uuid\n 'form_type': 'W2', # The form type of the document.\n 'doc_name': 'ExampleDocument', # The name of document that will be created.\n },\n\n files = {\n 'upload': open('/path/to/example-w2.pdf','rb'),\n },\n)\nprint(response.json())"
responses:
'200':
description: '200'
content:
application/json:
examples:
Successful Upload:
value:
status: 200
response:
uploaded_docs:
- pk: 51542103
uuid: 05afcf59-cd34-44a6-a8e3-efaa6de24512
name: bank-statement.pdf
page_count: 4
checksum: 716a9e2119b197fc8fed9e2ca3e56cae
created_ts: '2023-02-09T10:47:40Z'
id: 51542103
message: OK
Invalid PDF:
value:
status: 200
response:
status: 400
message: 'document.pdf is not a valid pdf
'
original_existing_doc_pks: []
original_existing_doc_uuids: []
uploaded_docs: []
message: OK
Document Already Exists:
value:
status: 200
response:
status: 400
message: 'bank_statement.pdf already exists
'
original_existing_doc_pks:
- 51431111
original_existing_doc_uuids:
- 05afcf59-cd34-44a6-a8e3-efaa6de24512
uploaded_docs: []
message: OK
schema:
oneOf:
- title: Successful Upload
type: object
properties:
status:
type: integer
example: 200
description: A numerical code that indicates the status of the request.
response:
type: object
description: An object received from the server that potentially contains data.
properties:
uploaded_docs:
type: array
description: Lists the details of the uploaded <<glossary:Document>>
items:
type: object
properties:
pk:
type: integer
example: 1
description: Unique primary key of the uploaded <<glossary:Document>>.
uuid:
type: string
example: 8dc88eed-2b6f-414a-82f2-a99bd181cf6e
description: Universally unique identifier (uuid) of the uploaded <<glossary:Document>>.
name:
type: string
example: bank-statement.pdf
description: Name of the uploaded <<glossary:Document>>.
page_count:
type: integer
example: 16
description: Total number of pages in the uploaded <<glossary:Document>>.
checksum:
type: string
example: 50a62f72f4b5b80b18f75fbed690dc47
description: Small data block to check error in the uploaded <<glossary:Document>>.
created_ts:
type: string
example: '2018-06-20T19:47:12Z'
description: A timestamp of when the <<glossary:Document>> was created.
id:
type: integer
example: 1
description: Unique primary key of the uploaded <<glossary:Document>>.
message:
type: string
example: OK
description: A textual description that indicates details about this response's status.
- title: Error
type: object
properties:
status:
type: integer
example: 200
description: A numerical code that indicates the status of the request.
response:
type: object
description: An object received from the server that potentially contains data.
properties:
status:
type: integer
example: 400
description: A numerical code that indicates the status of the request.
message:
type: string
example: document.pdf is not a valid PDF
description: A textual description that indicates details about this response's status.
original_existing_doc_pks:
type: array
description: Tbe unique primary keys of the uploaded <<glossary:Document>>s that match the provided file.
original_existing_doc_uuids:
type: array
description: An array of universal unique identifiers of the uploaded <<glossary:Document>> that match the provided file.
uploaded_docs:
type: array
description: An array of <<glossary:Document>>s uploaded to the specified <<glossary:Book>>.
items:
type: object
properties:
name:
type: string
example: bank-statement.pdf
description: Name of the uploaded <<glossary:Document>>.
status:
type: string
description: Processing status of the uploaded <<glossary:Document>>.
pages:
type: integer
example: 16
description: Total number of pages in the uploaded <<glossary:Document>>.
pk:
type: integer
example: 1
description: Unique primary key of the uploaded <<glossary:Document>>.
uuid:
type: string
example: 8dc88eed-2b6f-414a-82f2-a99bd181cf6e
description: Universally unique identifier (uuid) of the uploaded <<glossary:Document>>.
message:
type: string
example: OK
description: A textual description that indicates details about this response's status.
'400':
description: Client Errors
content:
application/json:
examples:
Invalid form type:
value:
status: 400
message: Form Type Not Found
code: 6001
meta:
status: 400
msg: Form Type Not Found
code: 6001
response: null
Book not found:
value:
status: 400
code: 1401
response: null
message: Book not found
meta:
status: 400
msg: Book not found
code: 1401
Missing Required Parameters:
value:
status: 400
code: 1103
response: null
message: Required pk or book uuid
meta:
status: 400
msg: Required pk or book uuid
code: 1103
No Permission:
value:
status: 400
code: 2102
response: null
message: No permission to access this book
meta:
status: 400
msg: No permission to access this book
code: 2102
schema:
properties:
status:
type: integer
description: A numerical code that indicates the status of the request.
example: 400
code:
type: integer
description: A numerical code that indicates the nature of an error.
example: 1401
response:
type: object
description: An object received from the server that potentially contains data.
message:
type: string
description: A textual description that indicates details about this response's status.
example: Book not found
meta:
type: object
description: An object received from the server that potentially contains data.
properties:
status:
type: integer
example: 400
description: A numerical code that indicates the status of the request.
message:
type: string
example: Book not found
description: A textual description that indicates details about this response's status.
code:
type: integer
example: 1401
description: A numerical code that indicates the nature of an error.
/v1/book/upload/mixed:
post:
summary: Upload Mixed Document PDF to Book
operationId: upload-mixed-document
description: 'Upload a PDF file containing more than one <<glossary:Document>> to a <<glossary:Book>>.
---
You can upload a file to this endpoint as a `multipart/form-data` encoded payload. Visit [our guide](https://docs.ocrolus.com/reference/multipartform-data-payloads) for more information.
> 📘
> - The maximum file size for upload is 200 MB.
'
tags:
- File Uploads
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- upload
properties:
upload:
type: string
description: The PDF file to upload.
format: binary
book_uuid:
type: string
description: The unique identifier of the <<glossary:Book>> that the uploaded <<glossary:Document>>s will be saved to. Mutually exclusive with `pk`.
pk:
type: string
description: The <<glossary:PK>> of the <<glossary:Book>> that the uploaded <<glossary:Document>>s will be saved to. Mutually exclusive with `book_uuid`.
doc_name:
type: string
description: The name of the Mixed <<glossary:Document>> that will be created from the imported file. Defaults to the name of the file if not given.
example:
pk: 30219565
book_uuid: 19aab921-25a5-4beb-a59e-ac72320061d6
doc_name: example_documents
x-readme:
headers:
- key: content-type
value: multipart/form-data
samples-languages:
- curl
- python
explorer-enabled: false
code-samples:
- language: curl
name: Sample cURL Code
code: "curl --request POST 'https://api.ocrolus.com/v1/book/upload/mixed' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <BEARER_TOKEN>' \\\n --form 'book_uuid=19aab921-25a5-4beb-a59e-ac72320061d6' \\\n --from 'doc_name=ExampleDocName' \\\n --form 'upload=@/path/to/document.pdf'"
- language: python
name: Sample Python Code
code: "import requests\nresponse = requests.post(\n url = 'https://api.ocrolus.com/v1/book/upload/mixed',\n\n headers = {\n 'Accept': 'application/json',\n 'Authorization': 'Bearer <BEARER_TOKEN>'',\n },\n\n data = {\n 'book_uuid': '19aab921-25a5-4beb-a59e-ac72320061d6', # The book's primary uuid\n 'doc_name': 'ExampleDocName', # The name of document that will be created.\n },\n\n files={\n 'upload': open('/path/to/document.pdf','rb'),\n },\n)\nprint(response.json())"
responses:
'200':
description: '200'
content:
application/json:
examples:
Upload successful:
value:
status: 200
response:
mixed_uploaded_docs:
- pk: 11585733
uuid: e3f2f66a-2792-439e-905f-240c33a84bd1
name: documents.pdf
page_count: 1
checksum: e78045a805517d962fc78289d98b2573
created_ts: '2023-06-03T00:40:13Z'
id: 11585733
message: OK
Invalid PDF:
value:
status: 200
response:
status: 400
message: 'document.pdf is not a valid pdf
'
original_existing_doc_pk: []
original_existing_doc_uuid: []
mixed_uploaded_docs: []
message: OK
Document Already Exists:
value:
status: 200
response:
status: 400
message: 'bank_statement.pdf already exists
'
original_existing_doc_pk:
- 51431111
original_existing_doc_uuid:
- 05afcf59-cd34-44a6-a8e3-efaa6de24512
uploaded_docs: []
message: OK
schema:
oneOf:
- title: Successful Upload
type: object
properties:
status:
type: integer
description: A numerical code that indicates the status of the request.
example: 200
default: 0
message:
type: string
description: A textual description that indicates details about this response's status.
example: OK
response:
type: object
description: An object received from the server that potentially contains data.
properties:
mixed_uploaded_docs:
type: array
description: An array of Mixed <<glossary:Document>>s uploaded to the <<glossary:Book>>.
items:
type: object
properties:
pk:
type: integer
example: 1
description: Unique integer identifier of the Mixed <<glossary:Document>>.
uuid:
type: string
example: 8dc88eed-2b6f-414a-82f2-a99bd181cf6e
description: Universally unique identifier (uuid) of the Mixed <<glossary:Document>>.
name:
type: string
example: documents.pdf
description: Name of the Mixed <<glossary:Document>>.
page_count:
type: integer
example: 16
description: Total number of pages in the Mixed <<glossary:Document>>.
checksum:
type: string
example: e78045a805517d962fc78289d98b2573
description: An alphanumerical value used to determine the authenticity of the data.
created_ts:
type: string
example: '2023-06-03T00:40:13Z'
description: The timestamp when the Mixed <<glossary:Document>> was created.
id:
type: integer
example: 1
description: Unique primary key of the Mixed <<glossary:Document>>.
- title: Invalid PDF
type: object
properties:
status:
type: integer
example: 200
description: A numerical code that indicates the status of the request.
response:
type: object
description: An object received from the server that potentially contains data.
properties:
status:
type: integer
example: 400
description: A numerical code that indicates the status of the request.
message:
type: string
example: document.pdf is not a valid PDF
description: A textual description that indicates details about this response's status.
original_existing_doc_pks:
type: array
description: Tbe unique primary key(s) of the uploaded <<glossary:Document>> that match the provided file.
mixed_uploaded_docs:
type: array
description: An array of Mixed <<glossary:Document>>s uploaded to the specified <<glossary:Book>>.
items:
type: object
properties:
name:
type: string
description: Name of the Mixed <<glossary:Document>>.
example: bank-statement.pdf
status:
type: string
description: Processing status of the Mixed <<glossary:Document>>.
pages:
type: integer
example: 16
description: Total number of pages in the Mixed <<glossary:Document>>.
pk:
type: integer
example: 1
description: Unique primary key of the Mixed <<glossary:Document>>.
uuid:
type: string
example: 8dc88eed-2b6f-414a-82f2-a99bd181cf6e
description: Universally unique identifier (uuid) of the Mixed <<glossary:Document>>.
message:
type: string
example: OK
description: A textual description that indicates details about this response's status.
- title: Document Already Exists
type: object
properties:
status:
type: integer
example: 200
description: A numerical code that indicates the status of the request.
response:
type: object
description: An object received from the server that potentially contains data.
properties:
status:
type: integer
example: 400
description: A numerical code that indicates the status of the request.
message:
type: string
example: bank_statement.pdf already exists
description: A textual description that indicates details about this response's status.
original_existing_doc_pks:
type: array
description: An array of unique primary key(s) of the uploaded <<glossary:Document>> that match the provided file.
original_existing_doc_uuids:
type: array
description: An array of universal unique identifiers of the uploaded <<glossary:Document>> that match the provided file.
uploaded_docs:
type: array
description: An array of <<glossary:Document>> uploaded to the specified <<glossary:Book>>.
items:
type: object
properties:
name:
type: string
example: bank-statement.pdf
description: Name of the uploaded <<glossary:Document>>.
status:
type: string
description: Processing status of the uploaded <<glossary:Document>>.
pages:
type: integer
example: 16
description: Total number of pages in the uploaded <<glossary:Document>>.
pk:
type: integer
example: 1
description: Unique primary key of the uploaded <<glossary:Document>>.
uuid:
type: string
example: 8dc88eed-2b6f-414a-82f2-a99bd181cf6e
description: Universally unique identifier (uuid) of the uploaded <<glossary:Document>>.
message:
type: string
example: OK
description: A textual description that indicates details about this response's status.
'400':
description: Client Errors
content:
application/json:
examples:
Book not found:
value:
status: 400
code: 1401
response: null
message: Book not found
meta:
status: 400
msg: Book not found
code: 1401
Missing Required Parameters:
value:
status: 400
code: 1103
response: null
message: Required pk or book uuid
meta:
status: 400
msg: Required pk or book uuid
code: 1103
No Permission:
value:
status: 400
code: 2102
response: null
message: No permission to access this book
meta:
status: 400
msg: No permission to access this book
code: 2102
schema:
oneOf:
- title: Book not found
type: object
properties:
status:
type: integer
description: A numerical code that indicates the status of the request.
example: 400
code:
type: integer
description: A numerical code that indicates the nature of an error.
example: 1401
response:
type: object
description: An object received from the server that potentially contains data.
example: null
message:
type: string
default: OK
description: A textual description that indicates details about this response's status.
example: Book not found
meta:
type: object
description: An object received from the server that potentially contains information about the request.
properties:
status:
type: integer
example: 400
description: A numerical code that indicates the status of the request.
message:
type: string
example: Book not found
description: A textual description that indicates details about this response's status.
code:
type: integer
example: 1401
description: A numerical code that indicates the nature of an error.
- title: Missing Required Parameter
type: object
properties:
status:
type: integer
example: 400
description: A numerical code that indicates the status of the request.
code:
type: integer
example: 1103
description: A numerical code that indicates the nature of an error.
response:
type: object
example: null
description: An object received from the server that potentially contains data.
message:
type: string
example: Required pk or book uuid
description: A textual description that indicates details about this response's status.
meta:
type: object
description: An object received from the server that potentially contains information about the request.
properties:
status:
type: integer
example: 400
description: A numerical code that indicates the status of the request.
msg:
type: string
example: Required pk or book uuid
description: A textual description that indicates details about this response's status.
code:
type: integer
example: 1103
description: A numerical code that indicates the nature of an error.
- title: No Permission
type: object
properties:
status:
type: integer
example: 400
description: A numerical code that indicates the status of the request.
code:
# --- truncated at 32 KB (106 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ocrolus/refs/heads/main/openapi/ocrolus-file-uploads-api-openapi.yml