## Document fields

`GET /v1/documents/fields`

Returns the full document field schema: field name, type, the read-only flag, and whether it is required at creation. Fields marked ★ are required in the request body when creating a document.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/documents/fields" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/documents/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

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

const { success, data } = await res.json()
console.log('Total fields:', Object.keys(data.fields).length)
```

### JavaScript — OAuth application

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

const { success, data } = await res.json()
```

## Response fields

`data.fields` is an object whose key matches the field name, and whose value contains `type` (the field type), `readonly` (`true` — the field cannot be passed on create or update), `label` (the display name), and `description` (a short description). The `label`/`description` values are returned in English.

| Field | Bitrix24 | Type | RO | Description |
|------|----------|-----|:--:|---------|
| `id` | `id` | number | yes | Document identifier |
| `title` | `title` | string | | Document title |
| `number` | `number` | string | | Document number |
| `templateId` | `templateId` | number | | ★ Template identifier. List: `GET /v1/doc-templates` |
| `providerClassName` | `providerClassName` | string | | ★ Data provider class, for example `Bitrix\DocumentGenerator\DataProvider\Rest` |
| `value` | `value` | string | | ★ External identifier of the source object that data is pulled from |
| `values` | `values` | object | | Values for the template's label fields |
| `fields` | `fields` | object | | Field formatting description |
| `createTime` | `createTime` | datetime | yes | Creation date |
| `updateTime` | `updateTime` | datetime | yes | Last modified date |
| `fileId` | `fileId` | number | | DOCX file identifier |
| `pdfId` | `pdfId` | number | | PDF file identifier |
| `imageId` | `imageId` | number | | Image file identifier |
| `stampsEnabled` | `stampsEnabled` | boolean | | Whether stamps and signatures are enabled |
| `provider` | `provider` | string | yes | Document data provider class |
| `downloadUrl` | `downloadUrl` | string | yes | DOCX download link for the user |
| `pdfUrl` | `pdfUrl` | string | yes | PDF download link for the user |
| `imageUrl` | `imageUrl` | string | yes | Image link for the user |
| `downloadUrlMachine` | `downloadUrlMachine` | string | yes | DOCX download link for the application |
| `pdfUrlMachine` | `pdfUrlMachine` | string | yes | PDF download link for the application |
| `imageUrlMachine` | `imageUrlMachine` | string | yes | Image link for the application |
| `createdBy` | `createdBy` | number | yes | Identifier of the user who created the document. List: `GET /v1/users` |
| `updatedBy` | `updatedBy` | number \| null | yes | Identifier of the user who last modified the document. `null` if the document has not been modified. List: `GET /v1/users` |
| `publicUrl` | `publicUrl` | string \| null | yes | Public link to the document. `null` if the public link has not been generated |

★ — fields `templateId`, `providerClassName`, `value` are required in the request body when creating a document.

## Response example

8 of 24 fields shown. The full list is in the table above.

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID", "description": "Unique numeric identifier of the generated document." },
      "title": { "type": "string", "readonly": false, "label": "Title", "description": "Document title." },
      "number": { "type": "string", "readonly": false, "label": "Number", "description": "Document number as shown in the printed form." },
      "templateId": { "type": "number", "readonly": false, "required": true, "label": "Template", "description": "ID of the template the document is generated from. List: GET /v1/doc-templates." },
      "providerClassName": { "type": "string", "readonly": false, "required": true, "label": "Data provider", "description": "Class name of the data provider that supplies the values for the template." },
      "value": { "type": "string", "readonly": false, "required": true, "label": "Owner identifier", "description": "Identifier of the entity the data provider builds the document for (e.g. a deal ID)." },
      "createTime": { "type": "datetime", "readonly": true, "label": "Created at", "description": "Date and time the document was created." },
      "publicUrl": { "type": "string", "readonly": true, "label": "Public URL", "description": "Public URL for sharing the document." }
    },
    "batch": ["create", "update", "delete"]
  }
}
```

The `batch` field lists the document operations available in a [batch request](/docs/batch).

## Error response example

403 — the key does not have the required scope:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'documentgenerator' scope"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | The API key is missing the `documentgenerator` scope |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not provided |

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

## See also

- [List documents](/docs/entities/documents/list)
- [Create document](/docs/entities/documents/create)
- [Entity reference](/docs/entity-api)
- [Filtering syntax](/docs/filtering)