Ocrolus Encore API
The Encore API from Ocrolus — 5 operation(s) for encore.
OpenAPI Specification
openapi: 3.0.0
info:
title: Account Level Webhooks Book Commands Encore API
version: 1.0.0
servers:
- url: https://api.ocrolus.com
security:
- oauth: []
tags:
- name: Encore
paths:
/v1/book/copy-jobs:
post:
summary: Create Book copy jobs
operationId: create-book-copy-jobs
tags:
- Encore
description: 'This API submits asynchronous copy requests that duplicate a <<glossary:Book>> and all uploaded documents to a specified recipient organization. Each request creates a job. You can monitor job status using the [List Book Copy Jobs](https://docs.ocrolus.com/reference/list-book-copy-jobs) endpoint.
### Supported workflows
1. **Updating existing applications**: Use a prior share label on the Book you are sharing so the new docs are appended to existing Book. Prevents duplicate Books when an applicant submits additional or missing documents.
2. **Renewal/re-engagement**: This workflows support two approaches. You can create a new Book by using either a new shared Book label to initiate a new application with receivers, or a previously used shared Book label to associate the new application with an existing one. Alternatively, you can reuse an existing Book, similar to the application update workflow.
To learn more, see the [Sender''s guide](https://docs.ocrolus.com/docs/senders#supported-workflows).
> 👍 Suggestion
> We recommend using new share labels for re-engagement and renewal applications to avoid creating confusion on the receiver''s side.
> 📘 Note
> - This API is intended for small and medium business (SMB) funders.
> - This API supports a maximum of 50 requests per call meaning you can include up to 50 Book copy requests in a single API call. If you need to process more, split them into multiple calls.
'
requestBody:
description: Example of body to be sent to submit Book copy jobs.
required: true
content:
application/json:
schema:
type: object
properties:
Copy Requests:
type: array
description: An array of copy requests for Books to be copied to recipient organizations.
items:
type: object
required:
- book_uuid
- org_uuid
properties:
book_uuid:
type: string
description: Unique identifier (UUID) of the Book to be copied.
example: 79886477-5312-46e5-8052-03446c324161
org_uuid:
type: string
description: Unique identifier (UUID) of the recipient organization.
example: 63b7a1c6-8e21-477d-9e64-3a20e240890e
shared_book_label:
type: string
description: Optional label for the shared Book in the recipient organization. Maximum length limit is 255 characters.
example: Recipient_Label_1
doc_uuids:
type: array
description: Optional list of document UUIDs to be copied from the source Book. If not provided, all documents from the source Book will be shared by default.
example:
- d290f1ee-6c54-4b01-90e6-d701748f0851
- c1a5f1ee-7c54-4b01-90e6-d701748f0123
items:
type: string
format: uuid
example:
books:
- book_uuid: 79886477-5312-46e5-8052-03446c324161
org_uuid: 63b7a1c6-8e21-477d-9e64-3a20e240890e
shared_book_label: Recipient_Label_1
- book_uuid: 79886477-5312-46e5-8052-03446c324161
org_uuid: 72118156-272a-41a7-8505-951743742889
shared_book_label: Recipient_Label_2
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
properties:
copy_jobs:
type: array
description: A list of copy job objects.
items:
type: object
properties:
job_id:
type: string
description: The unique identifier (UUID) for the copy job.
example: 1234abcd-5678-90ef-1234-567890abcdef
book_uuid:
type: string
description: The UUID of the Book.
example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
org_uuid:
type: string
description: The UUID of the recipient organization.
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
status:
type: string
description: 'The status of the copy job. Possible values:
- **`PENDING`**: Job created, awaiting processing.
- **`AWAITING_RECIPIENT`**: Waiting for recipient acceptance.
- **`IN_PROGRESS`**: Currently processing.
- **`SUCCESSFUL`**: Completed successfully.
- **`REJECTED`**: Rejected by recipient.
- **`FAILED`**: Failed with error.
'
example: PENDING
created_ts:
type: string
format: date-time
description: The timestamp when the copy job was created.
example: '2025-01-15T10:30:00Z'
shared_book_label:
type: string
description: An optional unique identifier assigned for each individual Book share request.
example: Recipient_Label_1
examples:
Success:
value:
copy_jobs:
- job_id: 1234abcd-5678-90ef-1234-567890abcdef
book_uuid: 7c9e6679-7425-40de-944b-e07fc1f90ae7
org_uuid: 3fa85f64-5717-4562-b3fc-2c963f66afa6
status: PENDING
created_ts: '2025-01-15T10:30:00Z'
shared_book_label: Sample_ECG
'400':
description: Client Errors
content:
application/json:
schema:
oneOf:
- title: Invalid auth
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.
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.
- title: Bad request
type: object
properties:
status:
type: integer
description: A numerical code that indicates the status of the request.
example: 400
message:
type: string
description: A textual description that indicates details about this response's status.
example: Validation error
body_params:
type: array
description: List of validation errors for request body parameters.
items:
type: object
properties:
loc:
type: array
description: Location of the error in the request body.
items:
type: string
example:
- books
- 0
- book_uuid
msg:
type: string
description: Description of the validation error.
example: Input should be a valid UUID
type:
type: string
description: Type of validation error.
example: uuid_parsing
examples:
Invalid Auth:
value:
status: 400
code: 1200
message: Authentication failed
meta:
status: 400
msg: Authentication failed
code: 1200
Bad Request:
value:
status: 400
message: Validation error
body_params:
- loc:
- books
- 0
- book_uuid
msg: Input should be a valid UUID
type: uuid_parsing
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/paths/~1v1~1book~1copy-jobs/get/responses/401/content/application~1json/schema'
examples:
Request body unavailable:
value:
status: 401
message: Authentication failed
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/paths/~1v1~1book~1copy-jobs/get/responses/401/content/application~1json/schema'
examples:
Forbidden (Recipient Not Allowed):
value:
status: 403
message: Book copy is not allowed for the given recipient organizations
Forbidden (No Recipients):
value:
status: 403
message: No recipients provided
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/paths/~1v1~1book~1copy-jobs/get/responses/401/content/application~1json/schema'
examples:
Internal Server Error:
value:
status: 500
message: Internal Server Error.
get:
summary: List Book copy jobs
operationId: list-book-copy-jobs
tags:
- Encore
description: 'This API retrieves a list of <<glossary:Book>> copy jobs and their details. By default, it returns outbound jobs—requests your organization sent. You can also fetch inbound jobs—requests sent to your organization.
> 📘 Note
> This API is intended for small and medium business (SMB) funders.
'
parameters:
- name: job_type
in: query
description: 'Type of job to retrieve. By default, the API returns **`OUTBOUND`** jobs. The available options are:
- **`OUTBOUND`**: Books you''re sending to others.
- **`INBOUND`**: Books others are sending to you.
'
required: false
schema:
type: string
enum:
- OUTBOUND
- INBOUND
default: OUTBOUND
- name: org_uuid
in: query
description: A unique identifier (UUID) of the organization.
required: false
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
schema:
type: string
format: uuid
- name: offset
in: query
description: The starting point (number of records to skip) from the latest record to fetch results.
required: false
schema:
type: integer
minimum: 0
default: 0
- name: limit
in: query
description: The maximum number of records to be fetched starting from the specified **`offset`** value.
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 50
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
properties:
copy_jobs:
type: array
description: A list of copy job objects.
items:
type: object
properties:
job_id:
type: string
description: The unique identifier (UUID) for the copy job.
example: 1234abcd-5678-90ef-1234-567890abcdef
book_uuid:
type: string
description: The UUID of the Book.
example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
org_uuid:
type: string
description: The UUID of the sendor or recipient organization based on the specified job types. For `INBOUND` jobs, this will be the sender's organization UUID and for `OUTBOUND` jobs, this will be the recipient's organization UUID.
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
status:
type: string
description: 'The status of the copy job. Possible values:
- **`PENDING`**: Job created, awaiting processing.
- **`AWAITING_RECIPIENT`**: Waiting for recipient acceptance.
- **`IN_PROGRESS`**: Currently processing.
- **`SUCCESSFUL`**: Completed successfully.
- **`REJECTED`**: Rejected by recipient.
- **`FAILED`**: Failed with error.
'
example: IN_PROGRESS
created_ts:
type: string
format: date-time
description: The timestamp when the copy job was created.
example: '2025-01-15T10:30:00Z'
shared_book_label:
type: string
description: An optional unique identifier assigned for each individual Book share request.
example: Recipient_Label_1
total:
type: integer
description: Total number of copy jobs.
example: 42
offset:
type: integer
description: The starting index of the result.
example: 0
limit:
type: integer
description: The maximum number of transactions returned per page starting from the specified **`offset`** value.
example: 50
examples:
Success:
value:
copy_jobs:
- job_id: 1234abcd-5678-90ef-1234-567890abcdef
book_uuid: 7c9e6679-7425-40de-944b-e07fc1f90ae7
org_uuid: 3fa85f64-5717-4562-b3fc-2c963f66afa6
status: IN_PROGRESS
created_ts: '2025-01-15T10:30:00Z'
shared_book_label: Sample_ECG
total: 42
offset: 0
limit: 50
'400':
description: Client Errors
content:
application/json:
schema:
oneOf:
- title: Invalid auth
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.
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.
- title: Bad request
type: object
properties:
status:
type: integer
description: A numerical code that indicates the status of the request.
example: 400
message:
type: string
description: A textual description that indicates details about this response's status.
example: Validation error
body_params:
type: array
description: List of validation errors for request body parameters.
items:
type: object
properties:
loc:
type: array
description: Location of the error in the request body.
items:
type: string
example:
- books
- 0
- book_uuid
msg:
type: string
description: Description of the validation error.
example: Input should be less than or equal to 100
type:
type: string
description: Type of validation error.
example: less_than_equal
examples:
Invalid Auth:
value:
status: 400
code: 1200
message: Authentication failed
meta:
status: 400
msg: Authentication failed
code: 1200
Bad Request:
value:
status: 400
message: Validation error
query_params:
- loc:
- limit
msg: Input should be less than or equal to 100
type: less_than_equal
'401':
description: Unauthorized
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:
Request body unavailable:
value:
status: 401
message: Authentication failed
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/paths/~1v1~1book~1copy-jobs/get/responses/401/content/application~1json/schema'
examples:
Internal Server Error:
value:
status: 500
message: Internal Server Error.
/v1/book/copy-jobs/{job_id}/accept:
post:
summary: Accept Book copy jobs
operationId: copy-jobs-accept
tags:
- Encore
description: "This API enables a recipient organization to accept an incoming <<glossary:Book>> copy request. Once accepted, Ocrolus begins copying the Book and its associated documents to the recipient organization. The recipient may optionally change the Book name when accepting a Book copy request. Alternatively, the recipient can rename the Book after it has been accepted.\nA `book.copy.request_accepted` webhook event is then triggered and sent to the sender organization.\n\n> \U0001F4D8 Note\n> - This API is intended for small and medium business (SMB) funders using the Book copy feature. \n> - A Book copy job can be accepted only when its status is `AWAITING_RECIPIENT` or `REJECTED`.\n"
parameters:
- name: job_id
in: path
required: true
description: UUID of the Book copy job to accept.
example: 019afd81-59ed-7fce-b5f8-477927bbf31d
schema:
type: string
format: uuid
requestBody:
description: Optional custom name for the copied Book.
required: false
content:
application/json:
schema:
type: object
properties:
book_name:
type: string
description: 'Custom name for the copied Book. If not provided, the Book will be named using the sender''s original Book name followed by a timestamp.
> 📘 Book name sanitization
> - The provided `book_name` is automatically cleaned.
> - The Book name must be between 4 and 255 characters long.
> - Leading and trailing whitespace is removed.
> - Non-ASCII characters such as emojis or special Unicode characters are removed.
> - If the resulting name is empty after sanitization, a 400 error is returned.
'
minLength: 4
maxLength: 255
additionalProperties: false
example:
book_name: Custom Copied Book Name
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'204':
description: The Book copy job was successfully accepted.
content:
application/json:
schema:
properties:
message:
type: object
description: "\nThe Book copy job was successfully accepted.\n > \U0001F4D8 When a Book is successfully accepted, the API returns a `204 No Content` response with no response body. Since no payload is returned, an example response is not shown.\n"
examples:
The Book copy job was successfully accepted:
value: {}
'400':
description: Client Errors
content:
application/json:
schema:
oneOf:
- title: Invalid auth
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.
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.
- title: Invalid UUID
type: object
properties:
status:
type: integer
description: A numerical code that indicates the status of the request.
example: 400
message:
type: string
description: A textual description that indicates details about this response's status.
example: Validation error
examples:
Invalid Auth:
value:
status: 400
code: 1200
message: Authentication failed
meta:
status: 400
msg: Authentication failed
code: 1200
Bad Request:
value:
status: 400
message: Invalid UUID
'404':
description: Job ID not found
content:
application/json:
schema:
$ref: '#/paths/~1v1~1book~1copy-jobs/get/responses/401/content/application~1json/schema'
examples:
Request body unavailable:
value:
status: 404
message: Book copy job not found
'412':
description: Trying to accept in invalid state
content:
application/json:
schema:
$ref: '#/paths/~1v1~1book~1copy-jobs/get/responses/401/content/application~1json/schema'
examples:
The Book copy job cannot be accepted in its current status:
value:
status: 412
message: Book copy job cannot be accepted in its current status
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/paths/~1v1~1book~1copy-jobs/get/responses/401/content/application~1json/schema'
examples:
Internal Server Error:
value:
status: 500
message: Internal Server Error.
/v1/book/copy-jobs/{job_id}/reject:
post:
summary: Reject Book copy jobs
operationId: copy-jobs-reject
tags:
- Encore
description: 'This API allows the recipient organization to reject an incoming <<glossary:Book>> copy request. A `book.copy.request_rejected` webhook event is then triggered and sent to the sender organization.
> 📘 Note
> - This API is intended for small and medium business (SMB) funders using the Book copy feature.
> - A Book copy job can be rejected only when its status is `AWAITING_RECIPIENT`.
> - A Book cannot be rejected after it has been accepted. Additionally, a previously rejected Book cannot be rejected again.
'
parameters:
- name: job_id
in: path
required: true
description: UUID of the Book copy job to reject.
example: 019afd81-59ed-7fce-b5f8-477927bbf31d
schema:
type: string
format: uuid
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'204':
description: The Book copy job was successfully rejected.
content:
application/json:
schema:
properties:
message:
type: object
description: "\nThe Book copy job was successfully rejected.\n > \U0001F4D8 When a Book is successfully rejected, the API returns a `204 No Content` response with no response body. Since no payload is returned, an example response is not shown.\n"
examples:
The Book copy job was successfully rejected:
value: {}
'400':
description: Client Errors
content:
application/json:
schema:
oneOf:
- title: Invalid auth
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.
message:
type: string
description: A textual description that indicates details about this response's
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ocrolus/refs/heads/main/openapi/ocrolus-encore-api-openapi.yml