Importing CRM records

Move existing data into the CRM: up to 100 records per request, keeping the author and the dates from the external system.

Import does not run automation. Automation rules, triggers and business processes configured to fire on record creation do not run on imported records — that is a property of the Bitrix24 operation itself, not a parameter of ours. If you want automation to run, create the records the usual way with POST /v1/{entity}.

POST /v1/{entity}/import

Scope: crm | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key (APP key)

Parameters

No other entity has this route — Bitrix24 can only import CRM objects.

Request fields (body)

The six service fields are accepted on import only — on an ordinary create Bitrix24 fills them in itself.

Only a Bitrix24 account administrator may set them. For any other user, Bitrix24 rejects that record with CRM_FIELD_ERROR_VALUE_NOT_VALID — the remaining records of the batch are still created.

Pass the ID of an existing employee. Bitrix24 does not check whether the identifier exists and will store any number, leaving a phantom author on the card. You can still work with the record as usual.

The set of available fields varies by object: deals and invoices have all six, leads have the author plus the creation and update dates. The exact list for a given entity comes from GET /v1/{entity}/fields — service fields are marked there with "importable": true next to "readonly": true. The same flag is available without a session from GET /v1/guide, in data.entities[].fieldsDetailed.

Examples

curl — personal key

curl -X POST 'https://vibecode.bitrix24.com/v1/leads/import' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {
        "title": "Website request",
        "name": "Jane",
        "lastName": "Doe",
        "phone": "+15551234567",
        "email": "jane@example.com",
        "assignedById": 31,
        "createdBy": 11
      }
    ]
  }'

curl — OAuth application

curl -X POST 'https://vibecode.bitrix24.com/v1/leads/import' \
  -H 'X-Api-Key: YOUR_APP_KEY' \
  -H 'Authorization: Bearer USER_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {
        "title": "Website request",
        "name": "Jane",
        "lastName": "Doe",
        "phone": "+15551234567",
        "email": "jane@example.com",
        "assignedById": 31,
        "createdBy": 11
      }
    ]
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/leads/import', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      {
        title: 'Website request',
        name: 'Jane',
        lastName: 'Doe',
        phone: '+15551234567',
        email: 'jane@example.com',
        assignedById: 31,
        createdBy: 11,
      },
    ],
  }),
})

const { data } = await res.json()
console.log('Not created:', data.summary.failed)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/leads/import', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      {
        title: 'Website request',
        name: 'Jane',
        lastName: 'Doe',
        phone: '+15551234567',
        email: 'jane@example.com',
        assignedById: 31,
        createdBy: 11,
      },
    ],
  }),
})

const { data } = await res.json()
console.log('Not created:', data.summary.failed)

Response fields

The response comes back with status 200 even when some records failed — import is not transactional, and the outcome has to be read per record.

Response example

The first record is created, the second one is rejected by Bitrix24 — its creation date is in the future:

{
  "success": true,
  "data": {
    "results": [
      { "index": 0, "success": true, "id": 1001349 },
      {
        "index": 1,
        "success": false,
        "error": "CRM_FIELD_ERROR_VALUE_NOT_VALID",
        "message": "The value of the \"Created on\" field cannot be in the future"
      }
    ],
    "summary": { "total": 2, "succeeded": 1, "failed": 1 }
  }
}

Error response example

400 — the items array is missing:

{
  "success": false,
  "error": {
    "code": "IMPORT_ITEM_VALIDATION",
    "message": "items must be a non-empty array of lead objects"
  }
}

Errors

Per-record errors arrive inside the 200, in results[] — those codes come from Bitrix24 itself, plus the two platform verdict codes, STAGE_NOT_APPLIED and AMOUNT_NOT_APPLIED.

Full list of common API errors — Errors.

Known specifics

How import differs from create

The date window

createdTime has a window set by Bitrix24, and it cannot be worked around:

• the date may not be later than the current moment.
• the date may not be earlier than that of the newest existing record of this object.

So you can transfer the full history into an empty CRM, or into one whose records are all older than the ones you are moving. Bitrix24 will not let you backdate records into a populated CRM — it answers CRM_FIELD_ERROR_VALUE_NOT_VALID with an explanation. Every successfully imported record raises the lower bound of the window, so move your batches oldest-first.

updatedTime must be no earlier than createdTime, and movedTime must fall between the two.

If you do not need the history, simply omit the dates — the author can be set without them.

Checking the import outcome

Always check summary.failed. Status 200 means "the request was processed", not "every record was created".

The stage and the manual amount are verified after the import. Bitrix24 accepts an import with a nonexistent stage and silently places the record on the default stage. A manual amount mode on a type without product rows is lost just as silently. So after all batches the platform re-reads the created records — one list page per 50 records — and marks those whose stage, pipeline or explicitly requested isManualOpportunity: true did not apply with STAGE_NOT_APPLIED / AMOUNT_NOT_APPLIED — keeping the id: the record exists, do not repeat it, correct the value with PATCH or /move. Only records that carried a stage, a pipeline or an explicit manual amount mode are re-read. An import without them costs exactly what it did before. Import runs no automation rules, so the re-read record is the outcome of the import itself, not of an automation rule. If the re-read fails, the rows stay as Bitrix24 reported them. An empty stage (null, "") is not verified — the record lands on the default stage. An amount without an explicit isManualOpportunity: true is not checked. A lead Bitrix24 itself converted in simple CRM mode is not counted as an unapplied stage.

A repeated import creates duplicates — the operation is not idempotent. If repeats are possible, write the record identifier from the external system into originatorId and originId: they let you find what has already been transferred.

Things to plan for when moving a database

• One stream at a time. Order is guaranteed within a single request but not between parallel requests, and Bitrix24 requires non-decreasing creation dates. Import sequentially.
• Throughput. A request with a hundred records takes roughly 12–15 seconds. The rate limit allows about a thousand records per minute per Bitrix24 account. Budget time for a database of tens of thousands of records.
• A failure mid-batch. If the connection to Bitrix24 drops after some records were already created, the response still comes back with status 200: the created ones carry identifiers, the rest are marked as failed. That response is your only evidence of what went through — check it before retrying.
• Phone and email. Pass them in the same form as on create ("phone": "+15551234567" or an array of objects) — the platform converts them into the format that import accepts.

See also

• Create lead
• Lead fields
• Batch calls