## Create activity

`POST /v1/activities`

Creates a new CRM activity: a call, meeting, task or email. The activity is linked to a CRM entity via `ownerTypeId` + `ownerId`.

## Request fields (body)

The minimum set to create an activity is `subject`, `typeId`, `communications` plus a **binding** to a CRM entity. The binding is provided **either** by the `ownerTypeId` + `ownerId` pair, **or** by the `entityTypeId` + `entityId` keys inside a `communications` item. If neither is provided, Bitrix24 cannot bind the communication and returns an error about `communications`.

| Parameter | Type | Req. | Description |
|----------|-----|:-----:|---------|
| `subject` | string | yes | Activity subject |
| `typeId` | number | yes | Type: `1` — meeting, `2` — call, `3` — task, `4` — email, `5` — action, `6` — custom action |
| `communications` | object[] | yes | Activity communications. An array of objects: `[{ "value": "+1…", "entityTypeId": 3, "entityId": 17 }]`. Nested keys are accepted in camelCase (`type`, `value`, `entityTypeId`, `entityId`) — consistent with the rest of the API — or in Bitrix24 UPPER case (`TYPE`, `VALUE`, `ENTITY_TYPE_ID`, `ENTITY_ID`). `value` is a phone/e-mail; `entityTypeId` + `entityId` is the CRM entity the communication belongs to (provides the binding when `ownerTypeId`/`ownerId` are omitted). When an owner is set, `[{ "value": "+1…" }]` is enough |
| `ownerTypeId` | number | yes¹ | Parent entity type: `1` — lead, `2` — deal, `3` — contact, `4` — company |
| `ownerId` | number | yes¹ | Parent entity ID. Lookup: `GET /v1/deals`, `GET /v1/leads`, `GET /v1/contacts`, `GET /v1/companies` |
| `responsibleId` | number | | Responsible person. Defaults to the current user. List: `GET /v1/users` |
| `description` | string | | Description |
| `priority` | number | | Priority: `1` — low, `2` — medium, `3` — high |
| `direction` | number | | Direction: `1` — incoming, `2` — outgoing |
| `completed` | boolean | | Completed |
| `startTime` | datetime | | Start date |
| `endTime` | datetime | | End date |
| `deadline` | datetime | | Deadline. **On create Bitrix24 ignores the provided value and derives `deadline` from `startTime`/`endTime`** — it cannot be set separately on `POST` |

¹ The `ownerTypeId` + `ownerId` pair is needed together and **only if** the binding is not provided via `entityTypeId`/`entityId` inside `communications`. If the binding comes through a communication, both fields may be omitted.

> ℹ️ The nested `communications` keys are accepted in two forms: camelCase (`type`, `value`, `entityTypeId`, `entityId`) — consistent with the rest of the API — and Bitrix24 UPPER case (`TYPE`, `VALUE`, `ENTITY_TYPE_ID`, `ENTITY_ID`). If both forms of the same key appear in one object, the UPPER-case one wins.

Full list of fields: [GET /v1/activities/fields](/docs/entities/activities/fields).

## Examples

### curl — personal key

```bash
curl -X POST https://vibecode.bitrix24.com/v1/activities \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": 2,
    "ownerTypeId": 3,
    "ownerId": 17,
    "subject": "Call the client",
    "description": "Discuss delivery terms",
    "responsibleId": 1,
    "priority": 2,
    "direction": 2,
    "communications": [
      { "value": "+12025550123", "entityTypeId": 3, "entityId": 17 }
    ],
    "startTime": "2026-04-16T10:00:00+00:00",
    "endTime": "2026-04-16T10:15:00+00:00"
  }'
```

### curl — OAuth application

```bash
curl -X POST https://vibecode.bitrix24.com/v1/activities \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": 2,
    "ownerTypeId": 3,
    "ownerId": 17,
    "subject": "Call the client",
    "description": "Discuss delivery terms",
    "responsibleId": 1,
    "priority": 2,
    "direction": 2,
    "communications": [
      { "value": "+12025550124", "entityTypeId": 3, "entityId": 17 }
    ],
    "startTime": "2026-04-16T10:00:00+00:00",
    "endTime": "2026-04-16T10:15:00+00:00"
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/activities', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    typeId: 2,
    ownerTypeId: 3,
    ownerId: 17,
    subject: 'Call the client',
    description: 'Discuss delivery terms',
    responsibleId: 1,
    priority: 2,
    direction: 2,
    communications: [
      { value: '+12025550125', entityTypeId: 3, entityId: 17 },
    ],
    startTime: '2026-04-16T10:00:00+00:00',
    endTime: '2026-04-16T10:15:00+00:00',
  }),
})

const { success, data } = await res.json()
console.log('Activity ID:', data.id)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/activities', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    typeId: 2,
    ownerTypeId: 3,
    ownerId: 17,
    subject: 'Call the client',
    description: 'Discuss delivery terms',
    responsibleId: 1,
    priority: 2,
    direction: 2,
    communications: [
      { value: '+12025550126', entityTypeId: 3, entityId: 17 },
    ],
    startTime: '2026-04-16T10:00:00+00:00',
    endTime: '2026-04-16T10:15:00+00:00',
  }),
})

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

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `id` | number | ID of the created activity |
| `typeId` | number | Activity type |
| `ownerTypeId` | number | Parent entity type |
| `ownerId` | number | Parent entity ID |
| `subject` | string | Subject |
| `responsibleId` | number | Responsible person |
| `createdAt` | datetime | Creation date |
| `updatedAt` | datetime | Modification date |

The response contains all activity fields.

## Response example

```json
{
  "success": true,
  "data": {
    "id": 3894,
    "typeId": 2,
    "ownerTypeId": 3,
    "ownerId": 17,
    "subject": "Call the client",
    "description": "Discuss delivery terms",
    "responsibleId": 1,
    "priority": 2,
    "direction": 2,
    "completed": false,
    "startTime": "2026-04-16T10:00:00+00:00",
    "endTime": "2026-04-16T10:15:00+00:00",
    "deadline": "2026-04-16T10:00:00+00:00",
    "createdAt": "2026-04-15T14:30:00+00:00",
    "updatedAt": "2026-04-15T14:30:00+00:00"
  }
}
```

## Error response example

400 — a required field is missing (`subject`, `typeId` or `communications`):

```json
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Body field \"communications\" is required to create activity."
  }
}
```

403 — no scope:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `MISSING_REQUIRED_FIELDS` | One of the required fields is missing: `subject`, `typeId`, `communications` (checked before the Bitrix24 call) |
| 400 | `INVALID_REQUEST` | Invalid field values |
| 403 | `SCOPE_DENIED` | The API key lacks the `crm` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## See also

- [List activities](/docs/entities/activities/list) — retrieval with filters
- [Activity fields](/docs/entities/activities/fields) — full list of fields
- [Deals](/docs/entities/deals) — linking via `ownerTypeId=2`
- [Leads](/docs/entities/leads) — linking via `ownerTypeId=1`
- [Entity API](/docs/entity-api) — general principles
- [Limits and optimization](/docs/optimization) — rate limits