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)

Which objects support it

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

How import differs from create

Request fields (body)

curl -X POST 'https://vibecode.bitrix24.com/v1/leads/import' \
  -H 'X-Api-Key: YOUR_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
      }
    ]
  }'

Service fields

Six fields that Bitrix24 normally fills in itself are accepted on import only:

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.

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.

Response

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.

{
  "success": true,
  "data": {
    "results": [
      { "index": 0, "success": true, "id": 147 },
      {
        "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 }
  }
}

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 chunks the platform re-reads the created records — once per 50, a list page — 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 a robot. 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.

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 (see above).

Full list of common API errors — Errors.

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 as usual ("phone": "+15551234567" or an array of objects) — the platform converts them into the format that import accepts.

Related pages

• Creating a record — the ordinary path, with automation
• Batch calls — up to 50 operations across different entities in one request
• Lead fields — which fields exist and which of them are service fields