Reference

PDF to Word

The PDF-to-Word lane keeps the current multipart upload contract while reusing the same auth, queued job lifecycle, and download flow as the rest of the API.

Reference5 min

View as Markdown

Getting startedShared API keys, status polling, and request IDs.BillingReview credits and paid plan behavior.

Section

What It Does

Upload a PDF, optionally pass conversion settings, and stream the generated DOCX when the job finishes.

Reference

Endpoint Reference

POST/v1/pdf/to-word

Queue a PDF-to-DOCX conversion using the existing multipart service contract through the shared gateway.

Auth

Bearer token required.

Idempotency

Supports optional Idempotency-Key replay protection and upload digest hints.

Content Type

multipart/form-data

Headers

Name	Type	Required	Location	Description
Authorization	Bearer <API_KEY>	Yes	header	User-owned API key created in the DocuShell dashboard.
Idempotency-Key	string	No	header	Recommended for safely retrying submit requests without creating duplicate jobs.
X-File-Name	string	No	header	Optional idempotency and metadata hint for uploaded files.
X-File-Size	integer	No	header	Optional caller-declared byte size.
X-File-SHA256	string	No	header	Optional digest used when deduplicating retries.

Request Fields

Name	Type	Required	Location	Description
file	file	Yes	multipart	Source PDF upload.
options	JSON string	No	multipart	Optional conversion settings such as `ocr` or output `format`.

Request Notes

The public lane passes the existing multipart request through to the internal converter, so the body shape matches the current service contract.

Convert to Word

bash

curl -X POST "https://api.docushell.com/api/v1/pdf/to-word" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: word-demo-001" \
  -H "X-File-Name: contract.pdf" \
  -F "file=@./contract.pdf;type=application/pdf" \
  -F 'options={"ocr":false,"format":"docx"}'

Try It Now

Console placeholder for safe sandbox execution.

Coming soon

MethodEndpointHeadersRequest Body

{
  "example": "Paste a request body when the sandbox is enabled"
}

Queued response

json

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "queued",
  "cost": 2000,
  "service": "pdf-to-word",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}

Status response

json

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "done",
  "service": "pdf-to-word",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "result": {
    "filename": "quarterly-report.docx",
    "sizeBytes": 184322,
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  },
  "completed_at": "2026-04-24T10:12:56.145Z",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}

Completed jobs return a public download link and keep the file streaming URL behind the gateway. Downloads use application/vnd.openxmlformats-officedocument.wordprocessingml.document.

Poll And Download

Queue the conversion, poll /v1/jobs/:jobId, and stream the DOCX when the job reaches done.
The public gateway hides internal result URLs and normalizes downloads behind the shared jobs API.

Failure Notes

Missing uploads and invalid option payloads return invalid_request style failures before the job is queued.
Uploads larger than 1 GB are rejected before the worker handoff.
backend_unavailable indicates the converter was unreachable before the job could be accepted.

Upload too large

400invalid_request

The public route enforces a hard 1 GB ceiling on uploads.

400 error

json

{
  "error": {
    "code": "invalid_request",
    "message": "Upload exceeds maximum allowed size (1 GB).",
    "type": "invalid_request_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

Authentication failure

401invalid_api_key

Returned when the bearer token is missing, revoked, expired, or not allowed to use the API lane.

401 error

json

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "type": "auth_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

Idempotency conflict

409idempotency_key_reused

Returned when the same Idempotency-Key is reused with a different payload than the original request.

409 error

json

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "type": "invalid_request_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

Webhook access disabled

403webhook_access_disabled

Returned when a Starter API key submits webhook fields. Pro, Growth, and Scale include webhooks.

403 error

json

{
  "error": {
    "code": "webhook_access_disabled",
    "message": "Webhooks are available on Pro, Growth, and Scale. Starter includes API access without webhooks.",
    "type": "billing_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

Rate limit

429rate_limit_exceeded

Returned when the API key or caller fingerprint exceeds the configured request rate.

429 error

json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded.",
    "type": "rate_limit_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

Code Samples

Convert to Word

curl -X POST "https://api.docushell.com/api/v1/pdf/to-word" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: word-demo-001" \
  -H "X-File-Name: contract.pdf" \
  -F "file=@./contract.pdf;type=application/pdf" \
  -F 'options={"ocr":false,"format":"docx"}'

Queued response

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "queued",
  "cost": 2000,
  "service": "pdf-to-word",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}