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

Activity fields

GET /v1/bizproc-activities/fields

Returns the field schema of a business process activity: the type of each field, whether it is writable, whether it is required for registration, its label and its description. The response describes the schema and does not query the activities registered in your Bitrix24 account.

Examples

The schema can be read only with an authorization key — both examples send an authorization key and the Authorization: Bearer header. 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 GET "https://vibecode.bitrix24.com/v1/bizproc-activities/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — authorization key

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

const { success, data } = await res.json()
console.log(Object.keys(data.fields))

Response fields

The label and description field captions are returned in English. Request headers do not switch the language.

Field Type Description
success boolean Always true on success
data.fields object Field schema: the key is the field name, the value is its description
data.fields.<name>.type string Value type: string, number, object, array
data.fields.<name>.readonly boolean true — the field is filled in by the system and is not passed in write requests
data.fields.<name>.required boolean Present only on fields that are required for registration
data.fields.<name>.label string Short field label
data.fields.<name>.description string Extended field description
data.batch array Entity operations available in POST /v1/batch

Schema composition:

Field Type RO Required Description
code string yes Unique activity code. Serves as the identifier in update and delete paths
handler string yes Activity handler URL
name string yes Activity name
description string no Activity description
authUserId number no The user whose token is passed to the app when the activity is called. List: GET /v1/users
useSubscription string no Whether to wait for the app's response before the process continues: Y or N
properties object no Activity input parameters
returnProperties object no Activity output parameters
documentType array no The document type the activity applies to — an array of three elements: module, object, type. Valid combinations: Register an activity
filter object no INCLUDE and 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

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "code": {
        "type": "string",
        "readonly": false,
        "required": true,
        "label": "Code",
        "description": "Unique activity code. Used as the identifier in update and delete paths."
      },
      "handler": {
        "type": "string",
        "readonly": false,
        "required": true,
        "label": "Handler URL",
        "description": "URL of the activity handler."
      },
      "name": {
        "type": "string",
        "readonly": false,
        "required": true,
        "label": "Name",
        "description": "Activity name."
      },
      "description": {
        "type": "string",
        "readonly": false,
        "label": "Description",
        "description": "Activity description."
      },
      "authUserId": {
        "type": "number",
        "readonly": false,
        "label": "Auth user ID",
        "description": "User whose token is passed to the app on invocation. List via GET /v1/users."
      },
      "useSubscription": {
        "type": "string",
        "readonly": false,
        "label": "Use subscription",
        "description": "Whether to wait for the app's response before continuing the process: Y or N."
      },
      "properties": {
        "type": "object",
        "readonly": false,
        "label": "Properties",
        "description": "Activity input parameters."
      },
      "returnProperties": {
        "type": "object",
        "readonly": false,
        "label": "Return properties",
        "description": "Activity output parameters."
      },
      "documentType": {
        "type": "array",
        "readonly": false,
        "label": "Document type",
        "description": "Document type the activity applies to."
      },
      "filter": {
        "type": "object",
        "readonly": false,
        "label": "Filter",
        "description": "INCLUDE and EXCLUDE rules by document type."
      },
      "usePlacement": {
        "type": "string",
        "readonly": false,
        "label": "Use placement",
        "description": "Open activity settings in a slide-out panel: Y or N."
      },
      "placementHandler": {
        "type": "string",
        "readonly": false,
        "label": "Placement handler",
        "description": "URL of the settings slide-out panel."
      }
    },
    "batch": ["create", "update", "delete"]
  }
}

Error response example

403 — the request was sent 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. The schema is available only to an authorization key
401 TOKEN_MISSING Authorization key 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
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

The full list of common API errors — Errors.

Known specifics

The schema is the same for activities and automation rules. Both entities are described by the same set of twelve fields — the meaning differs, not the composition.

See also