Ocrolus Book Queries API
The Book Queries API from Ocrolus — 5 operation(s) for book queries.
OpenAPI Specification
openapi: 3.0.0
info:
title: Account Level Webhooks Book Commands Book Queries API
version: 1.0.0
servers:
- url: https://api.ocrolus.com
security:
- oauth: []
tags:
- name: Book Queries
paths:
/v2/los-connect/encompass/book:
get:
summary: Book from loan
description: "This API endpoint lets you retrieve the Ocrolus <<glossary:Book>> associated with a specific Encompass loan. You can query it using either the `Encompass loan_id` (GUID) or the `loan_number`, depending on which identifier you have available. \n\n> \U0001F4D8 Note:\n> The system accepts either `loan_id` or `loan_number` to identify the loan. If both parameters are provided, or if neither is included in the request payload, the API returns a 400 error.\n"
operationId: book-from-loan
deprecated: false
tags:
- Book Queries
parameters:
- name: loan_id
in: query
description: The unique Encompass loan identifier expressed in Globally Unique Identifier (GUID) format.
example: c3f7e84d-8a91-4b1c-9460-192a746ad3c9
required: false
schema:
type: string
- name: loan_number
in: query
description: The numeric identifier assigned to an Encompass loan.
example: LN250918342
required: false
schema:
type: string
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
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:
loan_number:
type: string
description: The loan number associated with the request.
example: TEST250918342
loan_guid:
type: string
description: GUID of the loan.
example: c3f7e84d-8a91-4b1c-9460-192a746ad3c9
client_instance_id:
type: string
description: Identifier for the client instance.
example: DEMO99887766
client_name:
type: string
description: Name of the client.
example: Encompass QA Sandbox
book_details:
type: object
description: Details of the book associated with the loan.
properties:
book_pk:
type: integer
description: Primary key of the book.
example: 472391
name:
type: string
description: Name of the book.
example: Encompass QA Sandbox-c3f7e84d-8a91-4b1c-9460-192a746ad3c9-521
book_status:
type: string
description: Status of the book.
example: ACTIVE
created_ts:
type: string
format: date-time
description: Timestamp when the book was created.
example: '2025-02-12T15:23:47.382194'
book_uuid:
type: string
description: UUID of the book.
message:
type: string
description: A message describing the result of the request.
example: OK
examples:
Success:
value:
status: 200
response:
loan_number: TEST250918342
loan_guid: c3f7e84d-8a91-4b1c-9460-192a746ad3c9
client_instance_id: DEMO99887766
client_name: Encompass QA Sandbox
book_details:
book_pk: 472391
name: Encompass QA Sandbox-c3f7e84d-8a91-4b1c-9460-192a746ad3c9-521
book_status: ACTIVE
created_ts: '2025-02-12T15:23:47.382194'
book_uuid: 7a82f03c-4d7d-4a2e-baf4-63bbccff7b92
message: OK
'400':
description: Client Errors
content:
application/json:
schema:
oneOf:
- title: AUTH FAILED
$ref: '#/paths/~1v1~1book~1info/get/responses/400/content/application~1json/schema'
- title: BAD REQUEST
$ref: '#/paths/~1v2~1los-connect~1encompass~1book/get/responses/403/content/application~1json/schema'
examples:
AUTH FAILED:
value:
status: 400
code: 1200
message: Authentication failed
meta:
status: 400
msg: Authentication failed
code: 1200
BAD REQUEST:
value:
status: 400
message: Exactly one of loan_id or loan_number must be provided
'403':
description: Forbidden
content:
application/json:
schema:
properties:
status:
type: integer
description: A numerical code that indicates the status of the request.
message:
type: string
description: A textual description that indicates details about this response's status.
examples:
Forbidden:
value:
status: 403
message: ''
'404':
description: NOT FOUND
content:
application/json:
schema:
$ref: '#/paths/~1v2~1los-connect~1encompass~1book/get/responses/403/content/application~1json/schema'
examples:
NOT FOUND:
value:
status: 404
message: Not found
'500':
description: INTERNAL SERVER ERROR
content:
application/json:
schema:
$ref: '#/paths/~1v2~1los-connect~1encompass~1book/get/responses/403/content/application~1json/schema'
examples:
INTERNAL SERVER ERROR:
value:
status: 500
message: Internal server error
/v2/los-connect/book/{book_uuid}/loans:
get:
summary: Loan details from Book
description: 'This API retrieves the Encompass Loan GUID and related loan metadata using the Ocrolus <<glossary:Book>> UUID. It enables seamless mapping between an Ocrolus Book and its corresponding Encompass Loan, supporting accurate LOS integration, tracking, and synchronization between Ocrolus and Encompass systems.
'
operationId: loan-from-book
deprecated: false
tags:
- Book Queries
parameters:
- name: book_uuid
in: path
description: The unique identifier of the <<glossary:Book>> from which you want to retrieve loan details. Mutually exclusive with `book_pk`.
example: 19aab921-25a5-4beb-a59e-ac72320061d6
required: true
schema:
type: string
format: uuid
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
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:
loan_details:
type: object
description: Details of the loan associated with the request.
properties:
loan_id:
type: string
description: Unique identifier (UUID) of the Encompass loan GUID.
example: c45d08b2-f123-4dff-82b0-11aa3f5c34d9
loan_number:
type: string
description: The Encompass loan number.
example: TEST202512345
client_instance_id:
type: string
description: Identifier for the client instance.
example: TEBE98765432
format: TEBE or BE
created_ts:
type: string
format: date-time
description: Timestamp when the loan was created.
example: '2025-10-27T17:47:18.955864+00:00'
book_details:
type: object
description: Details of the Book associated with the loan.
properties:
book_pk:
type: integer
description: Primary key of the Book.
example: 764839
name:
type: string
description: Name of the Book.
example: Encompass TE Integration Testing-c45d08b2-f123-4dff-82b0-11aa3f5c34d9-001
book_status:
type: string
description: Current status of the Book.
example: ACTIVE
created_ts:
type: string
format: date-time
description: Timestamp when the Book was created.
example: '2025-10-27T17:47:21.129183'
book_uuid:
type: string
description: A unique identifier of the Book.
example: abf37196-12e5-47ca-b33c-e12aa3c9de11
message:
type: string
description: A message describing the result of the request.
example: OK
examples:
Success:
value:
loan_details:
loan_id: c45d08b2-f123-4dff-82b0-11aa3f5c34d9
loan_number: TEST202512345
client_instance_id: TEBE98765432
created_ts: '2025-10-27T17:47:18.955864+00:00'
book_details:
book_pk: 764839
name: Encompass TE Integration Testing-c45d08b2-f123-4dff-82b0-11aa3f5c34d9-001
book_status: ACTIVE
created_ts: '2025-10-27T17:47:21.129183'
book_uuid: abf37196-12e5-47ca-b33c-e12aa3c9de11
'400':
description: Client Errors
content:
application/json:
schema:
oneOf:
- title: AUTH FAILED
$ref: '#/paths/~1v1~1book~1info/get/responses/400/content/application~1json/schema'
- title: BAD REQUEST
$ref: '#/paths/~1v2~1los-connect~1encompass~1book/get/responses/403/content/application~1json/schema'
examples:
AUTH FAILED:
value:
status: 400
code: 1200
message: Authentication failed
meta:
status: 400
msg: Authentication failed
code: 1200
BAD REQUEST:
value:
status: 400
message: Book UUID not provided
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/paths/~1v2~1los-connect~1encompass~1book/get/responses/403/content/application~1json/schema'
examples:
Forbidden:
value:
status: 403
message: ''
'404':
description: NOT FOUND
content:
application/json:
schema:
$ref: '#/paths/~1v2~1los-connect~1encompass~1book/get/responses/403/content/application~1json/schema'
examples:
NOT FOUND:
value:
status: 404
message: Not found
'500':
description: INTERNAL SERVER ERROR
content:
application/json:
schema:
$ref: '#/paths/~1v2~1los-connect~1encompass~1book/get/responses/403/content/application~1json/schema'
examples:
INTERNAL SERVER ERROR:
value:
status: 500
message: Internal server error
/v1/book/info:
get:
summary: Book information
description: Retrieve details of a <<glossary:Book>>, including uploaded <<glossary:Document>>s, bank account information, and transaction periods.
operationId: book-info
deprecated: false
tags:
- Book Queries
parameters:
- name: book_uuid
in: query
description: The unique identifier of the <<glossary:Book>> whose information you want to retrieve. Mutually exclusive with `book_pk`.
example: 19aab921-25a5-4beb-a59e-ac72320061d6
schema:
type: string
format: uuid
- name: pk
in: query
description: Unique primary key (pk) of the <<glossary:Book>> whose information you want to retrieve. Mutually exclusive with `book_uuid`.
example: 30219565
schema:
type: string
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
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:
name:
type: integer
description: Name of the <<glossary:Book>> from which information is retrieved.
example: Sample bank statement
created:
type: string
description: A timestamp of when the <<glossary:Book>> was created.
example: '2023-03-03T04:36:31Z'
created_ts:
type: string
description: The timestamp at which <<glossary:Book>> was created.
example: '2023-03-03T04:36:31Z'
pk:
type: integer
description: Unique primary key for the <<glossary:Book>>.
example: 133771
owner_email:
type: string
description: Name of the owner who has created the <<glossary:Book>>.
example: email@address.com
is_public:
type: boolean
description: Indicates if all users in your organization can see and upload <<glossary:Document>>s into this <<glossary:Book>>."
example: true
book_uuid:
type: string
description: Universally unique identifier (UUID) for the <<glossary:Book>>.
example: 19aab921-25a5-4beb-a59e-ac72320061d6
id:
type: integer
description: Unique identifier for the <<glossary:Book>>.
example: 30219565
xid:
type: string
description: A free form field that can be used to associate a Book with some identity outside of Ocrolus.
example: 123ABC
book_type:
type: string
description: Determines what type of processing the Book will go through. Options include DEFAULT, OPTIMA, or WIDGET.
example: DEFAULT
is_shared_or_public_book:
type: boolean
description: Indicates if this <<glossary:Book>> is a public <<glossary:Book>> and can be shared with other users.
example: true
docs:
items:
type: array
description: An array of all the <<glossary:Document>>s uploaded to the <<glossary:Book>>.
properties:
pk:
type: integer
description: Unique identifier (primary key) for the <<glossary:Document>>.
example: 51542103
status:
type: string
description: Processing status of the <<glossary:Document>>.
example: REJECTED
name:
type: string
description: Name of the <<glossary:Document>>.
example: Ocrolus Sample PDF
pages:
type: integer
description: The total number of pages present in the <<glossary:Document>>.
example: 4
md5:
type: string
description: A cryptographic hash function used to secure the file by producing a fixed-length alphanumeric string as its output. It is commonly used to verify the integrity of a file by comparing the hash value of the original file with the hash value of the downloaded or received file.
example: 716a9e2119b197fc8fed9e2ca3e56cae
image_group_pk:
type: integer
description: Unique identifier (primary key) for the image group associated with the <<glossary:Document>>. Image group is a collection of images that consists of one or more images.
example: 10423247
mixed_uploaded_doc_pk:
type: integer
description: Unique identifier (primary key) for the uploaded Mixed Document. A Mixed Document is a single or multipage PDF that contains more than one doc type.
example: 10423257
mixed_docs:
items:
type: array
description: An array of all the Mixed Documents uploaded to the <<glossary:Book>>. A Mixed Document is a single or multipage PDF that contains more than one doc type. This array is optional and is only returned when the <<glossary:Book>> has Mixed Documents uploaded to it.
properties:
pk:
type: integer
description: Unique identifier (primary key) for the Mixed Document.
example: 51542103
status:
type: string
description: Processing status of the Mixed Document.
example: REJECTED
name:
type: string
description: Name of the Mixed Document.
example: Ocrolus Sample PDF
pages:
type: integer
description: The total number of pages present in the Mixed Document.
example: 4
md5:
type: string
description: A cryptographic hash function used to secure the file by producing a fixed-length alphanumeric string as its output. It is commonly used to verify the integrity of a file by comparing the hash value of the original file with the hash value of the downloaded or received file.
example: 716a9e2119b197fc8fed9e2ca3e56cae
image_group_pk:
type: integer
description: Unique identifier (primary key) for the image group associated with the Mixed Document. Image group is a collection of images that consists of one or more images.
example: 10423247
rejection_reason:
type: string
description: An optional attribute that briefly explains why a Document was rejected.
example: INVALID DOCUMENT
document_class:
type: string
description: The processing type of the Document.
bank_accounts:
type: array
description: An array of all the bank accounts present in the <<glossary:Book>> where every key is the bank account pk.
items:
type: object
properties:
pk:
type: string
description: A unique integer identifier of the bank account using which the transaction was done.
example: 12942296
book_pk:
type: string
description: A unique integer identifier of the <<glossary:Book>> to which the <<glossary:Document>> is uploaded.
example: 28741420
name:
type: integer
description: Name of the bank account holder.
example: 488083738759 CHASE CHECKING
bank_name:
type: string
description: Name of the bank.
example: CHASE
activity_info:
type: array
description: It displays the start and end period in which transactions have occurred for a given bank account.
items:
type: object
properties:
active:
type: array
items:
type: object
properties:
start:
type: array
description: It displays the start duration in which transactions have occurred.
items:
type: object
properties:
year:
type: integer
description: It displays the start year in which transactions have occurred.
example: 2022
month:
type: integer
description: It displays the start month in which transactions have occurred.
example: 9
day:
type: integer
description: It displays the start day in which transactions have occurred.
example: 10
end:
type: array
description: It displays the end duration in which transactions have occurred.
items:
type: object
properties:
year:
type: integer
description: It displays the end year in which transactions have occurred.
example: 2020
month:
type: integer
description: It displays the end month in which transactions have occurred.
example: 9
day:
type: integer
description: It displays the end day in which transactions have occurred.
example: 10
missing:
type: object
description: An array of date ranges when the bank account had no transactional data similarly structured to the active object.
example: []
account_type:
type: string
description: Type of the account from which transactions are retrieved.
example: CHECKING
account_holder:
type: string
description: Name of the account holder from which transactions are retrieved.
example: JILL SMITH
account_number:
type: string
description: Account number from which transactions are retrieved.
example: 488083738759
holder_zip:
type: string
description: Zip code of the account holder's address.
example: 11215
holder_country:
type: string
description: Country of the account holder.
example: US
holder_state:
type: string
description: State of the account holder.
example: NY
holder_city:
type: string
description: City of the account holder.
example: New York
holder_address_1:
type: string
description: The first line address of the account holder.
example: 74 Prospect Park
holder_address_2:
type: string
description: The second line address of the account holder.
example: West Park Slope
account_category:
type: string
description: Category of the account.
example: PERSONAL ACCOUNT
id:
type: string
description: Unique id of the bank.
example: 12942296
periods:
type: array
description: An array of bank account statement periods.
items:
properties:
pk:
type: string
description: Unique ID of the period from where transactions are retrieved.
example: 37445192
uuid:
type: string
description: Universally unique identification code (uuid) of the period from where transactions are retrieved.
example: c283613c-d20a-4aac-b8b3-5dfd608ba111
bank_account_pk:
type: integer
description: A unique integer identifier of the bank account that completed the transaction.
example: 12942296
begin_date:
type: string
description: Start of date of the transction.
example: 09/10/2020
end_date:
type: string
description: End of date of the transction.
example: 09/10/2022
begin_balance:
type: string
description: Starting balance of the transction retrieved.
example: 2935.81
end_balance:
type: string
description: Ending balance of the transction retrieved.
example: 3956.07
primary_recon_error_reason:
type: string
description: Manual verifier flag for suspicious activity after inspection. If the period is not reconciled, the verifiers will add the predefined values like Potential Fraud, Incomplete Information, and Unreconciled Period.
example: File Tampering Detected
secondary_recon_error_reason:
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ocrolus/refs/heads/main/openapi/ocrolus-book-queries-api-openapi.yml