## Activity fields

`GET /v1/activities/fields`

Returns the full list of available activity fields.

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/activities/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/activities/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

### JavaScript — OAuth application

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

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

## 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 | The activity field schema: field name → `type`, `readonly`, `label`, `description`. Required fields carry `required: true`, the field that can only be set on creation carries `createOnly: true`, the field accepted on creation but refused on update carries `readonlyOnUpdate: true`, and fields with a fixed set of values carry an `enum` list. Every field of the map is listed in the table below |
| `data.relations` | object | Related entities with the `includable` flag: `responsible`, `author`, and `editor`, all three pointing to users |
| `data.aggregatable` | array | Fields allowed in the `groupBy` of [activity aggregation](/docs/entities/activities/aggregate): `typeId`, `ownerTypeId`, `responsibleId`, `authorId`, `editorId`, `completed`, `status`, `direction`, `providerId`, `providerTypeId` |
| `data.aggregateFilterRequirement` | object | The narrowing filter that activity aggregation requires. `anchors` lists the accepted narrowings: the `ownerTypeId` + `ownerId` pair, the `responsibleId` field, or a date bound on `createdAt`, `updatedAt`, `deadline`. One is enough, as `mode: "anyOfAnchors"` states. `enforcement` is `enforced` when the account already rejects aggregation without a narrowing, or `advisory` while the narrowing is only recommended |
| `data.batch` | array | Activity operations available in [`POST /v1/batch`](/docs/batch): `create`, `update`, `delete` |
| `data.include` | array | The names the `include` parameter accepts |
| `meta.warnings` | array | Returned only when the field list could not be fetched from the Bitrix24 account: an element `{ code: "fields_partial", message }`. `data.fields` then holds only the fields the platform declares, and some captions may be missing. Repeat the request to get the full set |

### Fields of the `data.fields` map

| Field | Type | RO | Description |
|------|-----|:--:|---------|
| `id` | number | yes | Activity ID |
| `typeId` | number | | Type: `1` — meeting, `2` — call, `3` — task, `4` — email, `5` — action, `6` — custom action (**required** at creation). Can be set at creation only and cannot be changed |
| `ownerTypeId` | number | | Parent entity type: `1` — lead, `2` — deal, `3` — contact, `4` — company |
| `ownerId` | number | | Parent entity ID. Lookup depends on `ownerTypeId`: `GET /v1/deals`, `GET /v1/leads`, `GET /v1/contacts`, `GET /v1/companies` |
| `associatedEntityId` | number | yes | ID of the associated entity (call/email/meeting in the Bitrix24 module). Filled automatically by the corresponding provider after the activity is created |
| `subject` | string | | Activity subject (**required** at creation) |
| `communications` | object[] | | Activity communications (**required** at creation). An array of objects: `[{ "value": "+1…", "entityTypeId": 3, "entityId": 17 }]` — nested keys in camelCase or Bitrix24 UPPER case. Details — [Create activity](/docs/entities/activities/create) |
| `description` | string | | Description |
| `descriptionType` | number | | Format of `description`: `1` — plain text, `2` — BBCode, `3` — HTML |
| `responsibleId` | number | | Responsible person. List: `GET /v1/users` |
| `authorId` | number | yes | Record author. Filled by Bitrix24 based on the current user at creation |
| `editorId` | number | yes | Last editor. Updated by Bitrix24 on every change |
| `priority` | number | | Priority: `1` — low, `2` — medium, `3` — high |
| `direction` | number | | Direction: `1` — incoming, `2` — outgoing |
| `location` | string | | Venue (for meetings) |
| `completed` | boolean | | Completed |
| `status` | number | | Activity status: `1` — waiting, `2` — completed, `3` — auto-completed |
| `startTime` | datetime | | Start date |
| `endTime` | datetime | | End date |
| `deadline` | datetime | | Deadline. Activities without a deadline return the sentinel value `9999-12-30T21:00:00.000Z` — not a real date. A less-than date filter `filter[<deadline]=<date>` does not match such activities, and they are not treated as overdue. An update that includes the field is refused with `400 READONLY_FIELD` — change the deadline with [`POST /v1/activities/:id/deadline`](/docs/entities/activities/deadline). Marked `readonlyOnUpdate` in the `/fields` response |
| `createdAt` | datetime | yes | Creation date |
| `updatedAt` | datetime | yes | Modification date |
| `notifyType` | number | | Reminder type: `0` — off, `1` — minutes before, `2` — hours before, `3` — days before |
| `notifyValue` | number | | Reminder value (in the units given by `notifyType`) |
| `providerId` | string | | Activity provider ID, for example `CALL_LIST` for a [call list](/docs/entities/call-lists) activity, `CRM_EMAIL` for an email, `IMOPENLINES_SESSION` for an Open Channel conversation, `TASKS` for a task |
| `providerTypeId` | string | | Provider subtype (depends on `providerId`) |
| `providerGroupId` | string | | Provider group identifier (for example, an email thread) |
| `providerParams` | object | | Arbitrary provider parameters (structure depends on `providerId`) |
| `providerData` | string | | Serialized provider data (XML/JSON in a string) |
| `settings` | object | | Additional activity settings; the structure depends on `typeId` and `providerId`. For an email: `MESSAGE_FROM`, `DISABLE_SENDING_MESSAGE_COPY`, `IS_MESSAGE_SENT`, `MESSAGE_HEADERS`. To send an email, see [Create activity](/docs/entities/activities/create) |
| `originId` | string | | External ID, if the activity came from a third-party channel (CTI, email) |
| `originatorId` | string | | ID of the originating source (application/connector) |
| `resultStatus` | number | | Activity result status (numeric code) |
| `resultStream` | number | | Result processing stream |
| `resultSourceId` | string | | Result source |
| `resultMark` | number | | Result score/marker |
| `resultValue` | number | | Numeric result value |
| `resultSum` | number | | Result amount (for example, a receipt total) |
| `resultCurrencyId` | string | | Result currency (`USD`, …) |
| `autocompleteRule` | number | | Activity auto-completion rule (numeric code) |
| `isIncomingChannel` | boolean | yes | The activity came from an incoming channel (Open Channel/call/email). Read-only |
| `bindings` | object | | Additional CRM entity bindings of the activity. Manage bindings after creation via `/v1/activities/:activityId/bindings` |
| `files` | array | | Activity attachments: numeric IDs or `{id, url}` objects; a file name is not guaranteed. Request `files` in `select` for list and search; a single activity may include or omit the field without `select` |
| `webdavElements` | object | | Legacy Drive (WebDAV) file attachments. On list and search, returned only when explicitly requested in `select` |
| `originVersion` | string | | Sync version for the external system — prevents accidental overwrites of the data by an external integration |

> **Required at creation** (`POST /v1/activities`): `subject`, `typeId`, `communications`. These fields are flagged `required: true` in the `/fields` response. A **binding** to a CRM entity is also required — via `ownerTypeId` + `ownerId` **or** via `entityTypeId`/`entityId` inside `communications`. Details — [Create activity](/docs/entities/activities/create).

The `typeId` field is set at creation only: the `/fields` response flags it `createOnly: true`, and a [`PATCH /v1/activities/:id`](/docs/entities/activities/update) request that includes it returns `400 READONLY_FIELD`. To get an activity of a different type, create a new one and delete the previous one.

## typeId values

| Value | Activity type |
|----------|---------------|
| `1` | Meeting |
| `2` | Call |
| `3` | Task |
| `4` | Email |
| `5` | Action |
| `6` | Custom action |

## ownerTypeId values

| Value | Parent entity | Lookup |
|----------|----------------------|-------|
| `1` | Lead | `GET /v1/leads` |
| `2` | Deal | `GET /v1/deals` |
| `3` | Contact | `GET /v1/contacts` |
| `4` | Company | `GET /v1/companies` |

## Available includes

The `GET /v1/activities/fields` endpoint returns the list of available includes: `responsible`, `author`, `editor`.

Usage example: [Get activity](/docs/entities/activities/get#related-data).

More on includes: [Related data](/docs/includes).

## Response example

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID", "description": "Unique numeric identifier of the activity." },
      "typeId": { "type": "number", "readonly": false, "createOnly": true, "required": true, "label": "Type", "description": "Activity type — codes are decoded in enum (B24 crm.enum.activitytype). Required on create; set only on create and cannot be changed afterward." },
      "subject": { "type": "string", "readonly": false, "required": true, "label": "Subject", "description": "Activity subject. Required on create." },
      "communications": {"type": "array", "readonly": false, "required": true, "label": "Communications", "description": "Activity communications. Required on create. An item may contain type, value, entityTypeId, entityId, id and activityId. Write accepts camelCase or Bitrix24 UPPER keys; read preserves the keys returned by Bitrix24.", "itemSchema": {"type": "object"}},
      "files": {"type": "array", "readonly": false, "label": "Files", "description": "Activity attachments. An item can be a numeric file ID or an object with id and url, depending on the Bitrix24 method. A file name is not guaranteed. On list and search, returned only when files is requested in select; a single activity read may include it without select. The field may be absent.", "itemSchema": {}},
      "responsibleId": { "type": "number", "readonly": false, "label": "Responsible", "description": "ID of the user responsible for the activity." }
    },
    "relations": {
      "responsible": { "type": "one", "entity": "users", "includable": true },
      "author": { "type": "one", "entity": "users", "includable": true },
      "editor": { "type": "one", "entity": "users", "includable": true }
    },
    "aggregatable": ["typeId", "ownerTypeId", "responsibleId", "authorId", "editorId", "completed", "status", "direction", "providerId", "providerTypeId"],
    "aggregateFilterRequirement": {
      "mode": "anyOfAnchors",
      "anchors": [
        { "type": "allOf", "fields": ["ownerTypeId", "ownerId"] },
        { "type": "field", "field": "responsibleId" },
        { "type": "dateBound", "fields": ["createdAt", "updatedAt", "deadline"] }
      ],
      "surfaces": ["aggregate"],
      "enforcement": "advisory"
    },
    "batch": ["create", "update", "delete"],
    "include": ["responsible", "author", "editor"]
  }
}
```

Only 5 of the many fields are shown, and the `enum` array of `typeId` is omitted — the codes are decoded in the [typeId values](#typeid-values) section. The full field list is in the table above.

## Error response example

403 — the key lacks the `crm` scope:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope",
    "hint": "This request needs the 'crm' scope, which the calling key does not carry. Add 'crm' to this key in the developer cabinet (or through the management API), then repeat the call.",
    "cause": "key_scope_missing",
    "requiredScope": "crm",
    "keyScopes": ["task"],
    "fix": { "action": "edit_key_scopes", "via": "cabinet" },
    "userMessage": "The app's API key lacks the “CRM” permission. You can add it in the key settings in the developer cabinet."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | The API key lacks the `crm` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |

For the full list of common API errors, see [Errors](/docs/errors).

## See also

- [Create activity](/docs/entities/activities/create)
- [Entity API](/docs/entity-api)
- [Limits and optimization](/docs/optimization)