Doc Studio

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.

InputOutput fileCreditsBilling operation
One PDFDOCX30 per pageocr_extract_pdf
One or more imagesDOCX30 per imageocr_extract_image

Request Schema

uploadIdstringoptional

One upload: a single PDF, or a single image. Send either uploadId or uploadIds, not both.

uploadIdsstring[]optional

Several 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: true

PDFs 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.

webhookUrlstringoptional

Top-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.

201 Created: POST /v1/jobs
{
  "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.

200 OK: GET /v1/jobs/{id} after the job succeeds
{
  "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

HTTPCodeWhen
400invalid_inputBoth 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.
402insufficient_creditsThe wallet can't cover the estimate, or a test key's estimate is above its spend cap.
409conflictThe Idempotency-Key was already used with a different input.