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

Source: https://docs.docushell.com/pdf-to-word
Category: Reference
Read time: 5 min

## Related

- [Getting started](/getting-started.md): Shared API keys, status polling, and request IDs.
- [Billing](/billing.md): Review credits and paid plan behavior.

## What It Does

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

## Endpoint Reference

- Method: `POST`
- Path: `/v1/pdf/to-word`
- Auth: Bearer token required.
- Idempotency: Supports optional `Idempotency-Key` replay protection and upload digest hints.
- Content type: `multipart/form-data`

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

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

### Sample Requests

#### 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"}'
```

### Queued Response

#### 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

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

### Error Examples

#### Upload too large

- Status: `400`
- Code: `invalid_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

- Status: `401`
- Code: `invalid_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

- Status: `409`
- Code: `idempotency_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

- Status: `403`
- Code: `webhook_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

- Status: `429`
- Code: `rate_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"
  }
}
```