Import Contacts: Bulk Import from an Uploaded File

The Import Contacts endpoint triggers a bulk import job that reads contact records from a previously uploaded file. You specify which file to import, which channel and inbox to associate the contacts with, and how your file’s columns map to ChatbotX contact fields. You can also auto-apply a tag to every imported contact and provide a default country code for phone number normalization. A successful request returns HTTP 201 Created.

POST /api/v1/contacts/import

Before calling this endpoint, upload your CSV or spreadsheet file through the ChatbotX Workspace UI or file upload API to obtain a fileId.

Request Body

string

required

The ID of the previously uploaded file. Must be a numeric string matching the pattern \d+.

string

required

The channel type to associate contacts with. One of: omnichannel, webchat, messenger, whatsapp, zalo, smtp, telegram, instagram, tiktok.

string

required

The inbox to import contacts into. Must be a numeric string matching the pattern \d+.

string

Default country calling code to prepend to phone numbers that lack one. Must match the pattern ^\+\d{1,4}$ (e.g., +84 for Vietnam, +1 for the US).

string

The column name in your file that maps to the contact’s phone number. Maximum 255 characters.

string

The column name in your file that maps to the contact’s external identifier. Maximum 255 characters.

string

The column name in your file that maps to the contact’s email address. Maximum 255 characters.

string

The column name in your file that maps to the contact’s first name. Maximum 255 characters.

string

The column name in your file that maps to the contact’s last name. Maximum 255 characters.

string

A tag ID to apply to every imported contact. Must be a numeric string matching the pattern \d+.

array of objects

Array of up to 10 mapping objects that connect file columns to ChatbotX custom fields.

Field	Type	Description
`column`	string	The column header name in your file
`customFieldId`	string	The ChatbotX custom field ID to map this column to

Code Examples

curl --request POST \
  --url https://app.chatbotx.io/api/v1/contacts/import \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "fileId": "789",
    "channel": "whatsapp",
    "inboxId": "42",
    "countryCode": "+84",
    "phoneNumber": "Phone",
    "email": "Email",
    "firstName": "First Name",
    "lastName": "Last Name",
    "tagId": "15",
    "fieldMapping": [
      { "column": "Plan", "customFieldId": "101" },
      { "column": "Region", "customFieldId": "102" }
    ]
  }'

import requests

url = "https://app.chatbotx.io/api/v1/contacts/import"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "fileId": "789",
    "channel": "whatsapp",
    "inboxId": "42",
    "countryCode": "+84",
    "phoneNumber": "Phone",
    "email": "Email",
    "firstName": "First Name",
    "lastName": "Last Name",
    "tagId": "15",
    "fieldMapping": [
        {"column": "Plan", "customFieldId": "101"},
        {"column": "Region", "customFieldId": "102"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code)  # 201 on success

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fileId: '789',
    channel: 'whatsapp',
    inboxId: '42',
    countryCode: '+84',
    phoneNumber: 'Phone',
    email: 'Email',
    firstName: 'First Name',
    lastName: 'Last Name',
    tagId: '15',
    fieldMapping: [
      { column: 'Plan', customFieldId: '101' },
      { column: 'Region', customFieldId: '102' }
    ]
  })
};

fetch('https://app.chatbotx.io/api/v1/contacts/import', options)
  .then(res => {
    if (res.status === 201) console.log('Import job started');
  })
  .catch(err => console.error(err));

Response

A successful request returns HTTP 201 Created with no structured response body, confirming that the import job has been queued. The import runs asynchronously — check the Workspace UI or error logs for completion status.

HTTP/1.1 201 Created

Overview

Contacts

Custom Fields

Tags

Flows & Sequences

Broadcasts & Channels

Workspace

AI Agents

Import Contacts: Bulk Import from an Uploaded File

Request Body

Code Examples

Response

​Request Body

​Code Examples

​Response

Request Body

Code Examples

Response