bitrix

---
name: bitrix
description: Bitrix24 CRM API. Use when user mentions "Bitrix", "CRM", "Bitrix24 contacts",
  or asks about CRM management.
---

## 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
curl -s -X GET "$BITRIX_WEBHOOK_URL/user.current.json"
```

**Response:**
```json
{
  "result": {
  "ID": "1",
  "NAME": "John",
  "LAST_NAME": "Doe",
  "EMAIL": "john@example.com"
  }
}
```

### 2. List Users

Get a list of users in the workspace:

```bash
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": "john@example.com", "VALUE_TYPE": "WORK"}]
  }
}
```

Then run:

```bash
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
curl -s -X GET "$BITRIX_WEBHOOK_URL/crm.lead.get.json?id=<your-lead-id>"
```

### 5. List Leads

```bash
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
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
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
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": "jane@example.com", "VALUE_TYPE": "WORK"}]
  }
}
```

Then run:

```bash
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
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
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
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
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
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
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
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
curl -s -X GET "$BITRIX_WEBHOOK_URL/crm.lead.fields.json"

# Contact fields
curl -s -X GET "$BITRIX_WEBHOOK_URL/crm.contact.fields.json"

# Deal fields
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