For AI agents: markdown of this page — /docs-content-en/entities/bizproc-activities.md documentation index — /llms.txt

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

Register an activity

POST /v1/bizproc-activities

Registers a new activity for the Bitrix24 business process designer. Fields are passed flat at the JSON root — without a fields wrapper. Can only be called with an authorization key together with the Authorization: Bearer header.

Request fields (body)

Field Type Required Description
code string Yes Unique activity code. Allowed characters: a-z, A-Z, 0-9, ., -, _. Serves as the identifier in the update and delete paths
name string | object Yes Activity name. A string or a localized object like {"en": "...", "de": "..."}
handler string Yes Activity handler URL. The domain matches the application domain
description string | object No Activity description. A string or a localized object
authUserId number No ID of the user whose token is passed to the application when the activity is called. List: GET /v1/users
useSubscription string No Whether to wait for the application's response before continuing the process: Y or N
properties object No Activity input parameters — fields that are filled in when configuring the activity in the designer
returnProperties object No Activity output parameters — values the activity returns to the process
documentType array No Document type the activity applies to — module, object, type. Values: Document types
filter object No INCLUDE / EXCLUDE rules by document type
usePlacement string No Whether to open the activity settings in a slider panel: Y or N
placementHandler string No URL of the settings slider panel. Required when usePlacement: "Y"

Examples

The session token is issued by OAuth authorization, is valid for 24 hours, and cannot be renewed — Passing the key.

curl — authorization key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/bizproc-activities" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "notify_manager",
    "name": { "en": "Notify manager", "de": "Manager benachrichtigen" },
    "handler": "https://your-app.example.com/bizproc/notify"
  }'

JavaScript — authorization key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bizproc-activities', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'notify_manager',
    name: { en: 'Notify manager', de: 'Manager benachrichtigen' },
    handler: 'https://your-app.example.com/bizproc/notify',
  }),
})

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

Response fields

Field Type Description
id boolean true — Bitrix24 confirmed the activity registration. This is a success flag, not a numeric identifier. The activity identifier is the code you set

Response example

JSON 
{
  "success": true,
  "data": {
    "id": true
  }
}

Error response example

403 — calling with an API key:

JSON 
{
  "success": false,
  "error": {
    "code": "OAUTH_REQUIRED",
    "message": "bizproc-activities require an OAuth app key (vibe_app_*) with an Authorization: Bearer session — a personal vibe_api_* key lacks the per-user OAuth context Bitrix24 needs for these methods. Create an OAuth app (POST /v1/apps) and retry with its key. On this 403 switch keys — do NOT delete or recreate the app (that discards anything already registered under it, e.g. a bizproc robot you just registered)."
  }
}

Errors

HTTP Code Description
403 OAUTH_REQUIRED The request was sent with an API key. Only an authorization key can register activities
401 TOKEN_MISSING The authorization key was sent without the Authorization: Bearer header
401 WRONG_AUTH_SCHEME The authorization key was sent in the Authorization: Bearer header. The key goes in X-Api-Key, while Authorization: Bearer carries the session token
401 INVALID_SESSION The session token has expired or is invalid — authorize again
403 SCOPE_DENIED The key lacks the bizproc scope
400 MISSING_REQUIRED_FIELDS A required field is missing — code, name, or handler
422 BITRIX_ERROR Bitrix24 rejected the registration — the reason is in error.message

The full list of common API errors — Errors.

See also