Guides
Ocrolus.comStart free trialRaise a request

Endpoint types

Suggest Edits

Different types of endpoints handle input data and return responses in their unique ways, especially when it comes to the Content-Type of the response. The Ocrolus API supports the following four endpoint types:

Command

A Command endpoint instructs the API to execute a specific action. For requests to a Command endpoint, expect the query string in the following format:

  • Request Method: POST
  • Request Content-Type: application/json
  • Response Content-Type: application/json

A few common examples are Create a Book, Update a Book, and Delete a Book.

Upload

An Upload endpoint sends the file to Ocrolus for processing. For requests to an Upload endpoint, expect the query string in the following format:

  • Request Method: POST
  • Request Content-Type: multipart/form-data
  • Response Content-Type: application/json

A few common examples are Upload PDF to Book, Upload mixed PDF to Book, and Upload image.

The formal specification of multipart/form-data request payloads can be found in RFC 7578. For more information, see the multipart/form-data Payloads Guide.

Size limits

For optimal product efficiency, we enforce a hard size limit of 200 MB or 3000 pages per Document. Uploaded files that exceed either of these limits will be discarded and you will receive the following error message:

{
  "status": 400,
  "code": 1512,
  "response": null,
  "message": "Document contains more than the maximum allowed pages. Please break the document up into multiple documents or contact support for assistance."
}

If your file exceeds the size limit, you will receive an HTTP 413 status code without a JSON body.

In such cases, consider one of the following solutions:

  • Compress your document. Ensure that embedded text data is preserved and that image data is legible.
  • If your file represents multiple documents, break each Document into its own file. For instance, you can submit each Schedule of a 1040 form separately.
  • Remove extra pages that don't contain relevant information, such as instructions for filling out forms.
  • If the document in question is a scanned image, submit a digital version with embedded text data if you have one.
  • Convert your document's scanned image data to grayscale or monochrome.

If you can't reduce the size of your file, contact customer support and we'll help resolve the issue.

Query

A Query endpoint retrieves information about files uploaded for processing. For requests to a Query endpoint, expect the query string in the following format:

  • Request Method: GET
  • Request Content-Type: application/json
  • Response Content-Type: application/json

A few common examples are Book information, Book list, and Book status

Download

A Download endpoint retrieves available results after files have completed processing. For requests to a Download endpoint, expect the query string in the following format:

  • Request Method: GET
  • Request Content-Type: application/json
  • Response Content-Type:

A common example is Transactions endpoint.

Updated 5 months ago

See also