home / skills / vm0-ai / vm0-skills / bitrix

bitrix skill

safe

This skill enables managing Bitrix24 CRM, tasks, and users via curl, simplifying leads, deals, contacts, and workflow automation.

npx playbooks add skill vm0-ai/vm0-skills --skill bitrix

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

7.0 KB

---
name: bitrix
description: Bitrix24 REST API via curl. Use this skill to manage CRM (leads, deals, contacts), tasks, and users.
vm0_secrets:
  - BITRIX_WEBHOOK_URL
---

# Bitrix24 API

Use the Bitrix24 REST API via direct `curl` calls to **manage CRM, tasks, and users** in your Bitrix24 workspace.

> Official docs: `https://apidocs.bitrix24.com/`

---

## When to Use

Use this skill when you need to:

- **Manage CRM leads** (create, update, list, delete)
- **Manage CRM deals** and sales funnels
- **Manage CRM contacts** and companies
- **Create and manage tasks**
- **Get user information**
- **Automate business workflows**

---

## Prerequisites

1. Log in to your [Bitrix24](https://www.bitrix24.com/) workspace
2. Go to Applications → Developer Resources → Ready-made scenarios → Other → Incoming webhook
3. Create a new webhook and select the required permissions (CRM, Tasks, Users)
4. Copy the webhook URL
5. Store it in the environment variable

```bash
export BITRIX_WEBHOOK_URL="https://your-domain.bitrix24.com/rest/1/your-secret-code"
```

### Webhook URL Format

```
https://[domain]/rest/[user-id]/[secret-code]/[method].json
```

- `domain`: Your Bitrix24 address
- `user-id`: Webhook creator's ID
- `secret-code`: Authentication token (keep secure)
- `method`: API method name

---


> **Important:** When using `$VAR` in a command that pipes to another command, wrap the command containing `$VAR` in `bash -c '...'`. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
> ```bash
> bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'
> ```

## How to Use

All examples assume `BITRIX_WEBHOOK_URL` is set to your webhook base URL.

---

### 1. Get Current User

Get information about the authenticated user:

```bash
bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/user.current.json"'
```

**Response:**
```json
{
  "result": {
  "ID": "1",
  "NAME": "John",
  "LAST_NAME": "Doe",
  "EMAIL": "[email protected]"
  }
}
```

---

### 2. List Users

Get a list of users in the workspace:

```bash
bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/user.get.json"' | jq '.result[] | {ID, NAME, LAST_NAME, EMAIL}'
```

---

## CRM - Leads

### 3. Create a Lead

Write to `/tmp/bitrix_request.json`:

```json
{
  "fields": {
    "TITLE": "New Lead from API",
    "NAME": "John",
    "LAST_NAME": "Doe",
    "PHONE": [{"VALUE": "+1234567890", "VALUE_TYPE": "WORK"}],
    "EMAIL": [{"VALUE": "[email protected]", "VALUE_TYPE": "WORK"}]
  }
}
```

Then run:

```bash
bash -c 'curl -s -X POST "${BITRIX_WEBHOOK_URL}/crm.lead.add.json" --header "Content-Type: application/json" -d @/tmp/bitrix_request.json'
```

**Response:**
```json
{
  "result": 123
}
```

---

### 4. Get a Lead

Replace `<your-lead-id>` with the actual lead ID:

```bash
bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/crm.lead.get.json?id=<your-lead-id>"'
```

---

### 5. List Leads

```bash
bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/crm.lead.list.json"' | jq '.result[] | {ID, TITLE, STATUS_ID}'
```

With filter:

Write to `/tmp/bitrix_request.json`:

```json
{
  "filter": {"STATUS_ID": "NEW"},
  "select": ["ID", "TITLE", "NAME", "PHONE"]
}
```

Then run:

```bash
bash -c 'curl -s -X POST "${BITRIX_WEBHOOK_URL}/crm.lead.list.json" --header "Content-Type: application/json" -d @/tmp/bitrix_request.json'
```

---

### 6. Update a Lead

Write to `/tmp/bitrix_request.json`:

```json
{
  "id": 123,
  "fields": {
    "STATUS_ID": "IN_PROCESS",
    "COMMENTS": "Updated via API"
  }
}
```

Then run:

```bash
bash -c 'curl -s -X POST "${BITRIX_WEBHOOK_URL}/crm.lead.update.json" --header "Content-Type: application/json" -d @/tmp/bitrix_request.json'
```

---

### 7. Delete a Lead

Replace `<your-lead-id>` with the actual lead ID:

```bash
bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/crm.lead.delete.json?id=<your-lead-id>"'
```

---

## CRM - Contacts

### 8. Create a Contact

Write to `/tmp/bitrix_request.json`:

```json
{
  "fields": {
    "NAME": "Jane",
    "LAST_NAME": "Smith",
    "PHONE": [{"VALUE": "+1987654321", "VALUE_TYPE": "MOBILE"}],
    "EMAIL": [{"VALUE": "[email protected]", "VALUE_TYPE": "WORK"}]
  }
}
```

Then run:

```bash
bash -c 'curl -s -X POST "${BITRIX_WEBHOOK_URL}/crm.contact.add.json" --header "Content-Type: application/json" -d @/tmp/bitrix_request.json'
```

---

### 9. List Contacts

```bash
bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/crm.contact.list.json"' | jq '.result[] | {ID, NAME, LAST_NAME}'
```

---

## CRM - Deals

### 10. Create a Deal

Write to `/tmp/bitrix_request.json`:

```json
{
  "fields": {
    "TITLE": "New Deal from API",
    "STAGE_ID": "NEW",
    "OPPORTUNITY": 5000,
    "CURRENCY_ID": "USD"
  }
}
```

Then run:

```bash
bash -c 'curl -s -X POST "${BITRIX_WEBHOOK_URL}/crm.deal.add.json" --header "Content-Type: application/json" -d @/tmp/bitrix_request.json'
```

---

### 11. List Deals

```bash
bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/crm.deal.list.json"' | jq '.result[] | {ID, TITLE, STAGE_ID, OPPORTUNITY}'
```

---

### 12. Update Deal Stage

Write to `/tmp/bitrix_request.json`:

```json
{
  "id": 456,
  "fields": {
    "STAGE_ID": "WON"
  }
}
```

Then run:

```bash
bash -c 'curl -s -X POST "${BITRIX_WEBHOOK_URL}/crm.deal.update.json" --header "Content-Type: application/json" -d @/tmp/bitrix_request.json'
```

---

## Tasks

### 13. Create a Task

Write to `/tmp/bitrix_request.json`:

```json
{
  "fields": {
    "TITLE": "New Task from API",
    "DESCRIPTION": "Task description here",
    "RESPONSIBLE_ID": 1,
    "DEADLINE": "2025-12-31"
  }
}
```

Then run:

```bash
bash -c 'curl -s -X POST "${BITRIX_WEBHOOK_URL}/tasks.task.add.json" --header "Content-Type: application/json" -d @/tmp/bitrix_request.json'
```

---

### 14. List Tasks

```bash
bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/tasks.task.list.json"' | jq '.result.tasks[] | {id, title, status}'
```

---

### 15. Complete a Task

Replace `<your-task-id>` with the actual task ID:

```bash
bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/tasks.task.complete.json?taskId=<your-task-id>"'
```

---

## Get Field Definitions

Get available fields for any entity:

```bash
# Lead fields
bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/crm.lead.fields.json"'

# Contact fields
bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/crm.contact.fields.json"'

# Deal fields
bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/crm.deal.fields.json"'
```

---

## Common Parameters

| Parameter | Description |
|-----------|-------------|
| `filter` | Filter results (e.g., `{"STATUS_ID": "NEW"}`) |
| `select` | Fields to return (e.g., `["ID", "TITLE"]`) |
| `order` | Sort order (e.g., `{"ID": "DESC"}`) |
| `start` | Pagination offset |

---

## Guidelines

1. **Keep webhook secret**: Never expose your webhook URL publicly
2. **Use POST for complex queries**: Filters and field selections work better with POST
3. **Check field names**: Use `*.fields.json` methods to get valid field names
4. **Rate limits**: Bitrix24 has rate limits; add delays for bulk operations
5. **Pagination**: Results are paginated; use `start` parameter for large datasets

Overview

This skill provides direct access to the Bitrix24 REST API via curl to manage CRM records, tasks, and users from a shell environment. It uses an incoming webhook URL for authentication so you can create, update, list, and delete leads, contacts, deals, tasks, and query user data. Examples and patterns are included for safe, repeatable automation in scripts.

How this skill works

Set your incoming webhook URL in an environment variable and call Bitrix24 methods by issuing HTTP GET or POST requests with curl. Complex queries (filters, select, order) are sent as JSON payloads to the method endpoints, and responses return JSON objects you can parse with jq or other tools. Use provided endpoints to retrieve field definitions, respect pagination, and handle rate limits for bulk operations.

When to use it

Automating lead intake and syncing external form submissions into Bitrix24 CRM
Updating deal stages and opportunities from sales systems or scripts
Creating and assigning tasks programmatically from external workflows
Exporting or auditing user and contact lists for reporting
Running bulk updates or filtered queries against CRM entities

Best practices

Store the webhook URL in an environment variable and never commit it to source control
Use POST with a JSON body for filters, select, and complex queries to avoid URL length limits
Call *.fields.json methods to discover valid field names before sending updates
Respect Bitrix24 rate limits: add small delays or batching for bulk operations
Handle pagination with the start parameter when expecting large result sets

Example use cases

Create a new lead from a contact form and attach phone/email fields in one API call
List active deals and update their stage to WON after external payment confirmation
Generate tasks for onboarding new clients and assign responsible users automatically
Fetch current user info and user lists to build internal dashboards or sync directories
Retrieve CRM field definitions to validate payloads before sending updates

FAQ

How do I authenticate requests?

Use an incoming webhook URL created in Bitrix24 and store it in an environment variable like BITRIX_WEBHOOK_URL; include it in each curl request.

Should I use GET or POST?

Use GET for simple parameter calls and POST with JSON bodies for filters, select, and updates; POST avoids URL encoding issues and supports complex payloads.

How do I find valid field names for leads, contacts, or deals?

Call the corresponding *.fields.json method (e.g., crm.lead.fields.json) to retrieve field definitions before constructing requests.