# Business process activities

Register your own activities for the Bitrix24 business process designer. An activity is an external handler that appears in the business process designer and is called during the process: it receives input parameters, runs its logic on the application side, and returns the result back to the process.

Activities can be read, registered, updated, and deleted only with the `vibe_app_…` authorization key — the `vibe_api_…` API key does not work with these methods. Only a Bitrix24 account administrator can manage activities.

Bitrix24 API: `bizproc.activity.*`
Scope: `bizproc`

## Operations

- [Register an activity](./bizproc-activities/create.md) — `POST /v1/bizproc-activities`
- [Activity list](./bizproc-activities/list.md) — `GET /v1/bizproc-activities`
- [Update an activity](./bizproc-activities/update.md) — `PATCH /v1/bizproc-activities/:code`
- [Delete an activity](./bizproc-activities/delete.md) — `DELETE /v1/bizproc-activities/:code`
- [Activity fields](./bizproc-activities/fields.md) — `GET /v1/bizproc-activities/fields`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `code` | string | Unique activity code. Serves as the identifier in the update and delete paths |
| `handler` | string | Activity handler URL. The domain must match the application domain |
| `name` | string \| object | Activity name. A string or a localized object |
| `properties` | object | Activity input parameters — fields that are filled in when configuring the activity in the designer |
| `returnProperties` | object | Activity output parameters — values the activity returns to the process |
| `documentType` | array | Document type the activity applies to — module, object, type |
| `authUserId` | number | The user whose token is passed to the application on call. List: `GET /v1/users` |

The full field list — [Activity fields](./bizproc-activities/fields.md). All of them are passed on [registration](./bizproc-activities/create.md) and [update](./bizproc-activities/update.md). The activity identifier is the string code `code`, not a numeric `id`.
### Document types

The `documentType` value is an array of three strings — `[module, object, type]`.

| Entity | `documentType` |
|----------|----------------|
| Leads | `["crm", "CCrmDocumentLead", "LEAD"]` |
| Contacts | `["crm", "CCrmDocumentContact", "CONTACT"]` |
| Companies | `["crm", "CCrmDocumentCompany", "COMPANY"]` |
| Deals | `["crm", "CCrmDocumentDeal", "DEAL"]` |
| Quotes | `["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\Quote", "QUOTE"]` |
| Invoices | `["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\SmartInvoice", "SMART_INVOICE"]` |
| Smart processes | `["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\Dynamic", "DYNAMIC_<entityTypeId>"]` |
| Processes in the Feed | `["lists", "BizprocDocument", "iblock_<id>"]` |
| Lists in workgroups | `["lists", "Bitrix\\Lists\\BizprocDocumentLists", "iblock_<id>"]` |
| Drive documents | `["disk", "Bitrix\\Disk\\BizProcDocument", "STORAGE_<id>"]` |

The set is wider than for [automation rules](/docs/entities/bizproc-robots) — those apply only to CRM entities.

## What you need to know before you start

1. **An authorization key `vibe_app_…` is required, not an API key `vibe_api_…`.** All five operations require application context. An API key returns `403 OAUTH_REQUIRED` on any of them. Send the authorization key together with the `Authorization: Bearer <session>` header — see [Keys and authorization](/docs/keys-auth). The session token is issued by OAuth authorization, is valid for 24 hours, and cannot be renewed — after it expires, calls return `401 INVALID_SESSION` and you need to authorize again. How to obtain and pass the token — [Passing the key](/docs/keys-auth#passing-the-key).
2. **Administrator only.** Only a user with Bitrix24 account administrator rights can manage activities. For all other users, Bitrix24 returns an access error.
3. **The identifier is the string `code`.** The update and delete paths take `code` (a string), not a numeric identifier. There is no way to fetch a single activity by code — the `get` operation is unavailable.
4. **The list returns codes only.** [`GET /v1/bizproc-activities`](./bizproc-activities/list.md) returns an array of strings — the codes of registered activities, without the other fields.
5. **Handler domain.** The URL in `handler` and `placementHandler` must be on the application domain — Bitrix24 calls the handler at that address while the process runs.

## Related entities

| Entity | Endpoint | Purpose |
|----------|----------|-----------|
| Automation rules | [`/v1/bizproc-robots`](/docs/entities/bizproc-robots) | Bitrix24 automation rules. They appear both in the automation designer and in the business process designer — the format Bitrix24 recommends instead of activities |
| Process log | [`POST /v1/workflows/activity-log`](/docs/automation/workflows/activity-log) | Write a handler message to the business process log |

## Typical scenario

1. Register the activity via [`POST /v1/bizproc-activities`](./bizproc-activities/create.md): set `code`, `name`, the `handler` on the application domain, and the input `properties`.
2. The activity appears in the business process designer. When the process reaches it, Bitrix24 calls the `handler` with the filled-in parameters.
3. With `useSubscription: "Y"` the process waits for the application's response. With `"N"` it continues immediately.
4. To review the registered activities, use [`GET /v1/bizproc-activities`](./bizproc-activities/list.md). Delete an activity you no longer need by its code via [`DELETE /v1/bizproc-activities/:code`](./bizproc-activities/delete.md).

## Limits

| Limit | Value |
|-------|----------|
| Batch requests | up to 50 operations per [`POST /v1/batch`](/docs/batch) |
| Request rate | shared Vibecode API limit — see [Limits and optimization](/docs/optimization) |

## See also

- [Automation rules](/docs/entities/bizproc-robots)
- [Business process log](/docs/automation/workflows/activity-log)
- [Keys and authorization](/docs/keys-auth)
- [Entity reference](/docs/entities-index)