Skip to navigation
OCR API Reference

Submit a document

Submit one document as the raw request body and start a job.

Poll status_url until state is done or failed, then fetch result_url.

X-Filename sets the job’s display name. It does not affect processing. X-Output-Type sets the text format of tables in the result. X-Header-Footer-Marker sets whether the result wraps page header and footer text in tags. Idempotency-Key de-duplicates submissions in your organization. When a job with the same key exists, the response is 200 with that job’s status, and the server does not read the body. The key becomes free again when its job is deleted or expires.

Authentication

AuthorizationBearer

An emtelligent API key, sent as Authorization: Bearer <key>.

Headers

x-filenamestring or nullOptional

Optional display name for the job, percent-encoded as UTF-8. Metadata only; does not affect processing.

idempotency-keystring or nullOptionalformat: "^[\x20-\x7e]+$"1-255 characters

Optional de-duplication key, scoped to your organization. A repeat submission with the same key answers 200 with the existing job’s status and skips the upload. A repeat with a different output type answers 422.

x-output-typeenum or nullOptional

Optional text format for tables in the result’s text fields: markdown, plaintext or alignedtext. Text that is not in a table does not change. When omitted, the server’s default type applies. The job status shows the type of the job.

Allowed values:

Request

The raw bytes of one PDF, PNG, JPEG or TIFF file. Do not use multipart/form-data. The server ignores the Content-Type header and identifies the file type from its signature (its leading bytes).

Response

Idempotent replay: a job with this Idempotency-Key already exists in your organization. Its current status is returned and no job is created.

job_idstring
filenamestring
output_typeenum
Allowed values:
stateenum
Allowed values:
created_atstring
updated_atstring
renderobject
ocrobject
mime_typeenum or nullOptional
Allowed values:
finished_atstring or nullOptional
results_expire_atstring or nullOptional
results_purged_atstring or nullOptional
purge_reasonenum or nullOptional
Why the job's content was deleted.
Allowed values:
purged_bystring or nullOptional
errorstring or nullOptional
page_timingsobject or nullOptional

Per-page timings for the render and OCR stages.

ocr_servicemap from strings to integers or nullOptional
page_budgetmap from strings to integers or nullOptional
render_poolmap from strings to integers or nullOptional
result_availablebooleanOptionalDefaults to false

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
409
Conflict Error
413
Content Too Large Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
503
Service Unavailable Error