crm.item.add

What crm.item.add does

Creates items of any CRM entity type through one interface — the primary API for Smart Process Automations (SPAs) and Bitrix24's strategic direction for all CRM objects.

Business use cases

• Creating SPA items: property units, insurance policies, vehicles, shipments, applications
• Importers writing thousands of custom-entity records
• One code path serving multiple entity types in middleware
• New integrations future-proofed on the universal API

Typical fields and parameters

• entityTypeId — The entity type: standard objects have fixed IDs (1 lead, 2 deal, 3 contact, 4 company); SPAs get IDs at creation — find them via crm.type.list
• fields — camelCase for system fields (title, stageId, assignedById, opportunity); custom fields keep ufCrm-style names returned by crm.item.fields
• categoryId / stageId — Pipeline and stage for staged SPAs
• parentId{typeId} — Relation fields binding SPA items to deals/contacts (e.g. parentId2 = deal ID)

Example workflow

1. Property inventory system publishes a new unit
2. crm.type.list (cached) gives the 'Units' SPA entityTypeId = 187
3. crm.item.list checks for existing item by external reference
4. crm.item.add creates the unit with fields and deal relation
5. Portal leads matching that reference now link to the unit's history

Example request

POST .../crm.item.add.json

{
  "entityTypeId": 187,
  "fields": {
    "title": "Marina Vista — Unit 2104",
    "categoryId": 14,
    "stageId": "DT187_14:NEW",
    "assignedById": 7,
    "ufCrm12PropertyRef": "REF-4521",
    "ufCrm12Bedrooms": 2,
    "parentId2": 3120
  }
}

Example response

{
  "result": {
    "item": { "id": 981, "title": "Marina Vista — Unit 2104", ... }
  },
  "time": { ... }
}
// Note: returns the full item object, not a bare ID like classic methods.

Field mapping notes

• The #1 confusion: classic methods use UPPER_CASE (TITLE, UF_CRM_X); crm.item.* uses camelCase (title, ufCrm12X). Get exact names from crm.item.fields for your entityTypeId
• The response shape differs too — result.item.id, not result
• SPA stage IDs look like DT{typeId}_{categoryId}:{code}
• Relations via parentId{entityTypeId} fields are how SPA items bind to deals/contacts

Security notes

• SPA permissions are configured per type — a webhook with crm scope sees what its user sees; test with the service account, not your admin login

Common errors

• 'Entity type not found' — Wrong entityTypeId — list types with crm.type.list; IDs differ between portals, never hardcode across environments
• Fields ignored on create — UPPER_CASE names sent to a camelCase API — check crm.item.fields output
• Item created in wrong stage — stageId format DT{type}_{category}:{code} mismatched with categoryId

Production implementation tips

• Cache crm.type.list and crm.item.fields per portal at startup; resolve IDs by SPA symbolic code, not numeric ID, across environments
• For importers: validate the whole file first, then batch crm.item.add in 50s, then reconcile counts — the SPA Importer pattern
• Prefer crm.item.* for all new integration work; the classic per-entity methods are the legacy path

Webhook or OAuth app?

Same decision as elsewhere; importers run fine on service-account webhooks, long-lived syncs deserve apps.

Full decision guide: webhook vs OAuth app in Bitrix24.

When to use a queue worker

Bulk SPA imports are the canonical queue-worker use case: thousands of records, 50-per-batch, controlled concurrency, resumable progress.

How Tech Titan can help

Tech Titan builds production Bitrix24 integrations around crm.item.add and its siblings — with authentication, field mapping, queue workers, retry logic, duplicate handling, and structured logs as standard. If this method is on your critical path, bring the requirement to a free audit call and leave with an architecture sketch.