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

Log in to your Bitrix24 workspace
Go to Applications → Developer Resources → Ready-made scenarios → Other → Incoming webhook
Create a new webhook and select the required permissions (CRM, Tasks, Users)
Copy the webhook URL
Store it in the environment variable

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 -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

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 -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/user.current.json"' | jq .

Response:

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

2. List Users

Get a list of users in the workspace:

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

bash -c 'curl -s -X POST "${BITRIX_WEBHOOK_URL}/crm.lead.add.json" --header "Content-Type: application/json" -d '"'"'{
  "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"}]
  }
  }'"'"' | jq .'

Response:

{
  "result": 123
}

4. Get a Lead

LEAD_ID="123"

bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/crm.lead.get.json?id=${LEAD_ID}"' | jq .

5. List Leads

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

With filter:

bash -c 'curl -s -X POST "${BITRIX_WEBHOOK_URL}/crm.lead.list.json" --header "Content-Type: application/json" -d '"'"'{
  "filter": {"STATUS_ID": "NEW"},
  "select": ["ID", "TITLE", "NAME", "PHONE"]
  }'"'"' | jq .'

6. Update a Lead

LEAD_ID="123"

curl -s -X POST "${BITRIX_WEBHOOK_URL}/crm.lead.update.json" --header "Content-Type: application/json" -d "{
  \"id\": ${LEAD_ID},
  \"fields\": {
  \"STATUS_ID\": \"IN_PROCESS\",
  \"COMMENTS\": \"Updated via API\"
  }
  }" | jq .

7. Delete a Lead

LEAD_ID="123"

bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/crm.lead.delete.json?id=${LEAD_ID}"' | jq .

CRM - Contacts

8. Create a Contact

bash -c 'curl -s -X POST "${BITRIX_WEBHOOK_URL}/crm.contact.add.json" --header "Content-Type: application/json" -d '"'"'{
  "fields": {
  "NAME": "Jane",
  "LAST_NAME": "Smith",
  "PHONE": [{"VALUE": "+1987654321", "VALUE_TYPE": "MOBILE"}],
  "EMAIL": [{"VALUE": "jane@example.com", "VALUE_TYPE": "WORK"}]
  }
  }'"'"' | jq .'

9. List Contacts

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

bash -c 'curl -s -X POST "${BITRIX_WEBHOOK_URL}/crm.deal.add.json" --header "Content-Type: application/json" -d '"'"'{
  "fields": {
  "TITLE": "New Deal from API",
  "STAGE_ID": "NEW",
  "OPPORTUNITY": 5000,
  "CURRENCY_ID": "USD"
  }
  }'"'"' | jq .'

11. List Deals

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

12. Update Deal Stage

DEAL_ID="456"

curl -s -X POST "${BITRIX_WEBHOOK_URL}/crm.deal.update.json" --header "Content-Type: application/json" -d "{
  \"id\": ${DEAL_ID},
  \"fields\": {
  \"STAGE_ID\": \"WON\"
  }
  }" | jq .

Tasks

13. Create a Task

bash -c 'curl -s -X POST "${BITRIX_WEBHOOK_URL}/tasks.task.add.json" --header "Content-Type: application/json" -d '"'"'{
  "fields": {
  "TITLE": "New Task from API",
  "DESCRIPTION": "Task description here",
  "RESPONSIBLE_ID": 1,
  "DEADLINE": "2025-12-31"
  }
  }'"'"' | jq .'

14. List Tasks

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

15. Complete a Task

TASK_ID="789"

bash -c 'curl -s -X GET "${BITRIX_WEBHOOK_URL}/tasks.task.complete.json?taskId=${TASK_ID}"' | jq .

Get Field Definitions

Get available fields for any entity:

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

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

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

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

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

bitrix