## Download document PDF

`GET /v1/documents/:id/pdf`

Downloads the PDF file of a generated document through Vibecode: the platform adds Bitrix24 authorization to the request itself. A CRM record document downloads the same way through its own route.

| Document | Route | Scope |
|----------|---------|-------|
| App document | `GET /v1/documents/:id/pdf` | `documentgenerator` |
| CRM record document | `GET /v1/crm-documents/:id/pdf` | `crm` |

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `id` (path) | number | yes | Document ID, a positive integer. App documents: [`GET /v1/documents`](/docs/entities/documents/list), CRM record documents: [`GET /v1/crm-documents`](/docs/entities/documents/crm-list) |

No request body is sent. The examples below are for an app document. For a CRM record document, replace `documents` with `crm-documents` in the URL.

## Examples

### curl — personal key

```bash
curl --fail-with-body "https://vibecode.bitrix24.com/v1/documents/2001/pdf" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o document-2001.pdf
```

### curl — OAuth application

```bash
curl --fail-with-body "https://vibecode.bitrix24.com/v1/documents/2001/pdf" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -o document-2001.pdf
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/documents/2001/pdf', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

if (!res.ok) {
  const body = await res.json()
  throw new Error(body.error?.code ?? String(res.status))
}

const blob = await res.blob()
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/documents/2001/pdf', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

if (!res.ok) {
  const body = await res.json()
  throw new Error(body.error?.code ?? String(res.status))
}

const blob = await res.blob()
```

## Response fields

On success, the response is HTTP status `200 OK` and the body is the bytes of the PDF file. File details come in the headers.

| Header | Example value | Description |
|-----------|-----------------|----------|
| `Content-Type` | `application/pdf` | Content type that Bitrix24 returned for the document file |
| `Content-Disposition` | `attachment; filename="document-2001.pdf"` | File name for saving, in the form `document-<id>.pdf`. The document title is not part of it |

## Response example

```http
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="document-2001.pdf"
Content-Length: 11733

<binary .pdf content, 11733 bytes, starts with %PDF>
```

## Error response example

404 — document not found:

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Document not found."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `id` is not a positive integer. Message: `Document ID must be a positive integer.` |
| 404 | `ENTITY_NOT_FOUND` | No document with this `id`. Message: `Document not found.` |
| 409 | `DOCUMENT_NOT_READY` | The document file has not been generated yet. Retry the request in a few seconds |
| 502 | `DOWNLOAD_FAILED` | Bitrix24 did not return the file: it responded with an error code, sent JSON instead of the file, pointed to an address outside the Bitrix24 account, or the response could not be read in full. For an app document, also when the file is larger than 10 MiB |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request. The reason text is in `error.message` |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access to the document. For a CRM record document, also when the record it is attached to does not exist |
| 403 | `SCOPE_DENIED` | The key lacks the route's scope: `documentgenerator` for an app document, `crm` for a CRM record document |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `TOKEN_MISSING` | No tokens are mapped to the key — an OAuth application key was called without a user session |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**A read-only key works.** Downloading does not count as a write, so a key without write permission gets the file the same way as a full-access key.

**The PDF is generated after the document is created or updated.** For the first few seconds after that, the route responds with `409 DOCUMENT_NOT_READY`, while the DOCX is already downloadable.

**A PDF hash is not a reliable way to compare documents.** Until the PDF of a CRM record document is regenerated, a repeated download returns the same file byte for byte. When Bitrix24 regenerates the PDF, the file gets a new creation date, new conversion dates in its metadata and a new file identifier, while the pages and text stay the same. Compare content using the DOCX file from [`GET /v1/crm-documents/:id/download`](/docs/entities/documents/download): regenerating the PDF does not change it.

**The `pdfUrlMachine` field points to this route.** In [`GET /v1/documents/:id`](/docs/entities/documents/get) and [`GET /v1/crm-documents/:id`](/docs/entities/documents/crm-get) responses, the field contains this route's address for the same document. API responses contain no Bitrix24 access secrets.

## See also

- [Download document DOCX](/docs/entities/documents/download)
- [Download document image](/docs/entities/documents/image)
- [Get document](/docs/entities/documents/get)
- [Get CRM document](/docs/entities/documents/crm-get)
- [Documents](/docs/entities/documents)