Extraction & OCR
Extract readable text and tabular data from PDF files or image batches with optional OCR.
document.extract handles documents and scans. Upload a single multi-page PDF or an ordered array of images (JPG, PNG, WEBP). Text and tables are structured into clean editable output.
| Input | Output file | Credits | Billing operation |
|---|---|---|---|
| One PDF | DOCX | 30 per page | ocr_extract_pdf |
| One or more images | DOCX | 30 per image | ocr_extract_image |
Request Schema
uploadIdstringoptionalOne upload: a single PDF, or a single image. Send either uploadId or uploadIds, not both.
uploadIdsstring[]optionalSeveral image uploads (JPG, JPEG, PNG, WEBP), one per page, in reading order. No duplicates. PDFs can't be combined: send one PDF per job with uploadId.
ocrbooleanoptionaldefault: truePDFs only. Set false for digital PDFs that already contain selectable text to skip OCR. Images always use OCR, so ocr false with images returns 400.
webhookUrlstringoptionalTop-level field, next to operation and input. HTTPS URL that receives a signed POST when the job starts running, succeeds or fails. Private and internal hosts are rejected; up to 2048 characters.
Code Example (PDF Extraction)
curl -X POST https://api.transpera.io/v1/jobs \
-H "authorization: Bearer tp_test_..." \
-H "content-type: application/json" \
-H "idempotency-key: $(uuidgen)" \
-d '{
"operation": "document.extract",
"input": {
"uploadId": "UPLOAD_ID",
"ocr": true
}
}'Response
POST /v1/jobs answers 201 Created with the new job. status moves from queued to running to succeeded or failed; poll GET /v1/jobs/{id} or use webhookUrl. If the job could not be handed to the worker, it comes back already failed with errorCode enqueue_failed and nothing is charged.
{
"job": {
"id": "8f1c2d3e-4b5a-6789-abcd-ef0123456789",
"operation": "document.extract",
"status": "queued",
"createdAt": "2026-11-20T09:30:00.000Z",
"errorCode": null,
"chargedCredits": null
}
}Result
When status is succeeded, result is a file. url is a signed download link valid for one hour; fetch the job again for a fresh link. GET /v1/jobs (the list) never includes result. The file is an editable DOCX with the extracted text and tables.
{
"job": {
"id": "8f1c2d3e-4b5a-6789-abcd-ef0123456789",
"operation": "document.extract",
"status": "succeeded",
"createdAt": "2026-11-20T09:30:00.000Z",
"errorCode": null,
"chargedCredits": 90,
"result": {
"type": "file",
"fileName": "extracted.docx",
"url": "https://storage.googleapis.com/...",
"expiresAt": "2026-11-20T10:45:00.000Z"
}
}
}Errors
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_input | Both or neither of uploadId and uploadIds, more than one PDF, PDFs mixed with images, duplicate IDs, an unsupported file type, ocr false with images, or a non-HTTPS webhookUrl. |
| 402 | insufficient_credits | The wallet can't cover the estimate, or a test key's estimate is above its spend cap. |
| 409 | conflict | The Idempotency-Key was already used with a different input. |