Book upgrade

Use this guide when you need to change a Book's processing class (book_class) after creation, for example from Instant to Complete.

For background on how Book and document processing tiers relate, see Processing Flows. To upgrade individual documents without changing the Book class, see Upgrade a document and Upgrade a mixed document.

When you create a Book in Ocrolus, it gets assigned a book_class that controls how documents inside it are processed. You have two options: Instant, which uses fully automated AI extraction and returns results in seconds, or Complete, which adds human-in-the-loop verification for the highest accuracy.

Sometimes you need to change that class after the Book is already created. That is what a Book upgrade is for.

You upgrade a Book by calling Update Book (POST /v1/book/update) and passing a new book_class.

The one-way upgrade rule

Book class changes only go in one direction:

INSTANT ──► COMPLETE

COMPLETE is the highest tier. Once a Book reaches Complete, it stays there. This means:

• Further book_class changes are not allowed
• Downgrades such as COMPLETE to INSTANT are rejected

The reason for this is straightforward. Once documents have been verified by human reviewers under Complete processing, rolling back would create inconsistency between what was verified and what your downstream systems receive. The restriction protects the integrity of your underwriting decisions.

Allowed transitions

Book upgrade vs. document upgrade

Before you call Update Book, it helps to decide whether you actually need a Book-level or a document-level upgrade. Both change the processing tier, but they scope that change differently.

Before you upgrade

Ensure the following before calling the API:

• All documents in the Book must finish their current processing. The API blocks upgrades while any document is still in progress, so it is worth polling the Book status or waiting for a completion webhook before you make the call.
• Decide whether you need a Book upgrade or a document upgrade:
  • Upgrade the Book when the whole package needs Complete processing, including future uploads.
  • Upgrade documents when only some files need Complete and you want new uploads to stay on Instant.

How to upgrade a Book

Call Update Book with the Book identifier and the target book_class.

curl --request POST \
  --url https://api.ocrolus.com/v1/book/update \
  --header 'accept: application/json' \
  --header 'authorization: Bearer <ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data '{
    "book_uuid": "52dfdb53-6652-4d3a-a3db-fe864c6ff2fb",
    "book_class": "COMPLETE"
  }'

What happens after a successful upgrade

Webhooks and the upgrade lifecycle

A typical Instant to Complete upgrade workflow looks like this:

1. Upload documents to an Instant Book.
2. Receive the Instant completion webhook. For example book_verified.
3. Evaluate the Instant results. If they are sufficient, you are done. If you need higher accuracy, continue.
4. Call POST /v1/book/update with "book_class": "COMPLETE".
5. Wait for the Complete completion webhook.
6. Consume the final verified results.

   📘

   Note

   If Auto-Requeue is enabled for your organization, Ocrolus may automatically escalate an Instant Book to Complete when Instant processing cannot handle certain bank statement types. In that case, wait for the Complete completion webhook before underwriting. Do not rely on Instant results alone.

Errors

All upgrade failures return HTTP 400 with a message field describing the problem.

Example error response

{
  "status": 400,
  "response": null,
  "message": "Cannot change book class from COMPLETE to INSTANT",
  "meta": {
    "status": 400,
    "msg": "Cannot change book class from COMPLETE to INSTANT"
  }
}

{
  "status": 400,
  "response": null,
  "message": "Book cannot be upgraded while its document(s) are still processing",
  "meta": {
    "status": 400,
    "msg": "Book cannot be upgraded while its document(s) are still processing"
  }
}

Related pages