Import leads (single or bulk)

Creates CRM leads in the API key owner's organization. Send either one lead (fields) or many (leads[]): a body with leads is always treated as bulk.

Fields

field_name is matched to the organization's lead fields by name, not case-sensitive (email = Email).

An unknown field_name is created automatically as a String, not-required field (shown in created_fields).

Name is a required system field. Every field marked required in CRM Settings must be sent with a valid value, or the lead is rejected (9609 / 9610).

A value that doesn't fit a non-required field's type is still saved and reported in warnings.

Type rules: Number = any finite number; Flag = true / false; Email = valid email; Phone = with country code (+919876543210); Date with timestamp = ISO 8601 with zone (2026-10-23T10:30:00+05:30 or ...Z); String = anything.

value may be a string, number or boolean (stored as text). null or "" means not set.

The same field_name twice in one lead → 9603.

Contacts (optional)

{ "contact_id": 1234 } links a contact that already exists in the Master Contact List (9608 if not found).

{ "phone": "+91...", "first_name", "last_name" } links the Master Contact List contact with that phone, or creates it. Phone must include the country code (9607).

The same phone twice is one contact (first names win). Existing contact names are only filled in when empty.

Other rules

source_type (case-insensitive, 1–50 characters, else 9600) is one of the organization's lead sources, e.g. API, Website. A name the organization doesn't have yet is created as a new source (up to 100 per organization, 9641). Defaults to API.

The lead's origin is always API (lead_origin_type in the response). The system sets it; it can't be sent or changed.

Every imported lead starts in the organization's default status (e.g. New), with no agents assigned.

There is no duplicate detection: the same phone or email always creates a new lead.

History shows one "Lead created" event per lead.

Bulk only

1–500 leads per request (9637); at most 1,000 contacts across all leads (9638).

A lead's own source_type overrides the top-level one. An invalid top-level source_type fails the whole request (9600).

Each lead follows the single-lead rules. Failed leads are listed in errors with index (0-based position in leads), code and message; the request itself still returns status: true.

New fields are shared across the request (first spelling wins) and count once towards the 200-field limit.

Limits

Item	Limit
fields per lead	≤ 50
field_name	1–100 characters
value	≤ 5,000 characters
contacts per lead	≤ 20
first_name / last_name	≤ 100 characters
custom lead fields per organization	≤ 200
leads per bulk request	1–500
contacts per bulk request	≤ 1,000
requests	30 per minute per API key (default `API_KEY_RATE_LIMIT`)

Access

The key must belong to an active user; the route crm-lead/import POST must be in api_allowed_routes (else 9020); the user's role needs the crm-lead.manage permission (else -403).

Errors: validation and business errors return HTTP 200 with status: false (see 200 examples). Auth and rate-limit errors use HTTP 401 / 403 / 429.

Code	Meaning
9001	Invalid body (wrong type for source_type / value, lead not an object)
9600	source_type longer than 50 characters
9601	fields is not an array, or more than 50
9602	field_name missing or longer than 100
9603	Same field_name more than once
9604	value longer than 5,000
9605	contacts is not an array, or more than 20
9606	Contact without contact_id or phone
9607	Phone without a valid country code
9608	contact_id not in the Master Contact List
9609	Required field missing (message names the field)
9610	Required field has an invalid value (message names the field)
9612	Organization would exceed 200 lead fields
9622	first_name / last_name longer than 100
9623	No default lead status in the organization
9641	Organization would exceed 100 lead sources
9637	Bulk: leads is not an array of 1 to 500
9638	Bulk: more than 1,000 contacts
9020	Route not allowed for API keys (HTTP 403)
9243	Invalid or expired API key (HTTP 401)
-403	Role lacks crm-lead.manage (HTTP 403)
9999	Rate limit exceeded (HTTP 429)
9000	Server error

Responses

🟢200

application/json

Application envelope. Single: data is the created lead (same shape as GET /crm-lead/detail) plus created_fields and warnings. Bulk: data is the import summary. Validation errors also return HTTP 200 with status: false and error: { code, message }.

Bodyapplication/json

🟠401

🟠403

🟠429

curl --location 'https://api.chronox.ai/api/crm-lead/import' \ --header 'Authorization: {{Authorization}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "source_type": "API", "fields": [ { "field_name": "Name", "value": "Ravi Patel" }, { "field_name": "Email", "value": "ravi.patel@example.com" }, { "field_name": "Campaign", "value": "Diwali Offer 2026" }, { "field_name": "Budget", "value": 250000 } ], "contacts": [ { "first_name": "Ravi", "last_name": "Patel", "phone": "+919876543210" } ] }'

{ "status": true, "data": { "lead_id": "3f6c2a8e-1b4d-4c1e-9a7b-2d5e8f0a1c34", "lead_source_type": { "lead_source_type_id": "b1e2c3d4-0000-4000-8000-000000000001", "lead_source_type_name": "API" }, "lead_origin_type": { "lead_origin_type_id": "d4e5f6a7-0000-4000-8000-000000000003", "lead_origin_type_name": "API" }, "lead_status": { "lead_status_id": "c2d3e4f5-0000-4000-8000-000000000002", "lead_status_name": "New", "lead_status_color": "#2F80ED" }, "fields": [ { "lead_field_id": "d3e4f5a6-0000-4000-8000-000000000003", "lead_field_name": "Name", "lead_field_type_name": "String", "flag_required": true, "flag_system": true, "value": "Ravi Patel", "flag_valid": true }, { "lead_field_id": "e4f5a6b7-0000-4000-8000-000000000004", "lead_field_name": "Email", "lead_field_type_name": "Email", "flag_required": false, "flag_system": false, "value": "ravi.patel@example.com", "flag_valid": true }, { "lead_field_id": "f5a6b7c8-0000-4000-8000-000000000005", "lead_field_name": "Campaign", "lead_field_type_name": "String", "flag_required": false, "flag_system": false, "value": "Diwali Offer 2026", "flag_valid": true } ], "contacts": [ { "contact_id": 5678, "first_name": "Ravi", "last_name": "Patel", "phone": "919876543210" } ], "agents": [], "threads": [], "latest_notes": [], "note_count": 0, "created_by_user_assignment_id": 101, "created_at_timestamp": "2026-10-23T05:00:00.000Z", "timestamp": "2026-10-23T05:00:00.000Z", "created_fields": [ "Campaign" ], "warnings": [] } }

Request

Responses