# Employee signatures

Work with Bitrix24 HR e-signature templates, legal profiles, documents and providers.

**Scope:** `sign.b2e` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authentication:** `X-Api-Key`

## Before you start

Company keys are not supported. Use a personal key or an application key.

A scope does not replace user permissions. `crm` is additionally required for templates and bundles, `sign.b2e.document.get`, `sign.b2e.document.send` and `sign.b2e.company.provider.list`. Updating a legal profile requires `user`.

`humanresources.hcmlink` is required only for the HCM parameters of `sign.b2e.document.send` and `sign.b2e.company.provider.list`. Reading an HCM document requires `sign.b2e` and an administrator OAuth context, with no additional HCM scope.

External signature providers, personal signed documents, the company safe and HCM Link documents require OAuth. For an incoming webhook, these seven operations return `422 BITRIX_ERROR` with the native `WRONG_AUTH_TYPE` code in `error.b24Code`.

`GET /v1/sign-b2e/company-providers` requires a READWRITE key: Bitrix24 can register the company with a provider. A READONLY key is rejected before Bitrix24 is called.

A document UID, a template UID, a company provider UID and a numeric external provider ID are different identifiers. Sending has legal consequences; there are no automatic retries. Responses with credential-bearing links are redacted, and the paths of the replaced values are listed in `meta.redacted`. Do not use such responses as the source configuration for writing back.

## Endpoint reference

| Method | Path | Description | Bitrix24 method |
|---|---|---|---|
| GET | `/v1/sign-b2e/legal-fields` | [List legal fields](./sign-b2e/list-legal-fields.md) | `sign.b2e.legal.field.list` |
| PATCH | `/v1/sign-b2e/legal-profiles/:userId` | [Update a legal profile](./sign-b2e/update-legal-profile.md) | `sign.b2e.legal.profile.update` |
| GET | `/v1/sign-b2e/templates` | [List templates](./sign-b2e/list-templates.md) | `sign.b2e.template.list` |
| POST | `/v1/sign-b2e/templates/send` | [Send a document from a template](./sign-b2e/send-template.md) | `sign.b2e.template.send` |
| POST | `/v1/sign-b2e/template-folders/tail` | [List template bundles](./sign-b2e/tail-template-folders.md) | `sign.b2e.template.folder.tail` |
| GET | `/v1/sign-b2e/template-folders/:id` | [Get a template bundle](./sign-b2e/get-template-folder.md) | `sign.b2e.template.folder.get` |
| GET | `/v1/sign-b2e/documents/:uid` | [Get a document](./sign-b2e/get-document.md) | `sign.b2e.document.get` |
| POST | `/v1/sign-b2e/documents/send` | [Send a file for signature](./sign-b2e/send-document.md) | `sign.b2e.document.send` |
| GET | `/v1/sign-b2e/company-providers` | [List company providers](./sign-b2e/list-company-providers.md) | `sign.b2e.company.provider.list` |
| GET | `/v1/sign-b2e/hcmlink/documents/:id` | [Get an HCM Link HR document](./sign-b2e/get-hcm-document.md) | `sign.b2e.hcmlink.document.get` |
| GET | `/v1/sign-b2e/personal-documents` | [Personal signed documents](./sign-b2e/list-personal-documents.md) | `sign.b2e.personal.tail` |
| GET | `/v1/sign-b2e/company-safe-documents` | [Company safe documents](./sign-b2e/list-safe-documents.md) | `sign.b2e.mysafe.tail` |
| GET | `/v1/sign-b2e/providers` | [List external providers](./sign-b2e/list-providers.md) | `sign.b2e.provider.tail` |
| POST | `/v1/sign-b2e/providers` | [Add an external provider](./sign-b2e/create-provider.md) | `sign.b2e.provider.add` |
| PATCH | `/v1/sign-b2e/providers/:id` | [Update an external provider](./sign-b2e/update-provider.md) | `sign.b2e.provider.update` |
| DELETE | `/v1/sign-b2e/providers/:id` | [Delete an external provider](./sign-b2e/delete-provider.md) | `sign.b2e.provider.delete` |

## Quick start

Get the available templates:

```bash
curl 'https://vibecode.bitrix24.com/v1/sign-b2e/templates?limit=2' \
  -H 'X-Api-Key: YOUR_API_KEY'
```

## Complete example

Read the first page of bundles, then the details of the first bundle found. The key needs sign.b2e and crm.

```javascript
const base = 'https://vibecode.bitrix24.com/v1/sign-b2e';
const headers = { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' };
const pageResponse = await fetch(base + '/template-folders/tail', { method: 'POST', headers, body: '{}' });
const page = await pageResponse.json();
if (!pageResponse.ok || !page.success) throw new Error(page.error?.message);
if (page.data.length) {
  const response = await fetch(base + '/template-folders/' + encodeURIComponent(page.data[0].id), { headers });
  const bundle = await response.json();
  if (!response.ok || !bundle.success) throw new Error(bundle.error?.message);
  console.log(bundle.data);
}
console.log(page.meta.hasMore, page.meta.cursor);
```

## Error codes

| Code | Reason |
|---|---|
| `SCOPE_DENIED` | The key lacks a required scope. |
| `METHOD_NOT_YET_AVAILABLE` | The six template and legal profile operations require sign 26.1300.0; the release is given in error.release. The classic methods carry no such marker. |
| `SIGN_B2E_TEMPLATE_FOLDER_NOT_FOUND` | The bundle is missing or unavailable for sending. The native code is preserved in `error.code` and `error.b24Code`. |
| `ENTITY_NOT_FOUND` | Bitrix24 returned a generic `NOT_FOUND` refusal. The native code is in `error.b24Code`. |

[Common API errors](/docs/errors).

## See also

- [Users](/docs/entities/users)
- [Companies](/docs/entities/companies)
