> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theomnibot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Import Contacts: Bulk Import from an Uploaded File

> Bulk import contacts into ChatbotX from a previously uploaded file, mapping CSV columns to contact fields and assigning a channel, inbox, and optional tag.

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`.

<Info>
  **POST** `/api/v1/contacts/import`
</Info>

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

## Request Body

<ParamField body="fileId" type="string" required>
  The ID of the previously uploaded file. Must be a numeric string matching the pattern `\d+`.
</ParamField>

<ParamField body="channel" type="string" required>
  The channel type to associate contacts with. One of: `omnichannel`, `webchat`, `messenger`, `whatsapp`, `zalo`, `smtp`, `telegram`, `instagram`, `tiktok`.
</ParamField>

<ParamField body="inboxId" type="string" required>
  The inbox to import contacts into. Must be a numeric string matching the pattern `\d+`.
</ParamField>

<ParamField body="countryCode" type="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).
</ParamField>

<ParamField body="phoneNumber" type="string">
  The column name in your file that maps to the contact's phone number. Maximum 255 characters.
</ParamField>

<ParamField body="contactId" type="string">
  The column name in your file that maps to the contact's external identifier. Maximum 255 characters.
</ParamField>

<ParamField body="email" type="string">
  The column name in your file that maps to the contact's email address. Maximum 255 characters.
</ParamField>

<ParamField body="firstName" type="string">
  The column name in your file that maps to the contact's first name. Maximum 255 characters.
</ParamField>

<ParamField body="lastName" type="string">
  The column name in your file that maps to the contact's last name. Maximum 255 characters.
</ParamField>

<ParamField body="tagId" type="string">
  A tag ID to apply to every imported contact. Must be a numeric string matching the pattern `\d+`.
</ParamField>

<ParamField body="fieldMapping" type="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 |
</ParamField>

## Code Examples

<CodeGroup>
  ```bash curl theme={null}
  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" }
      ]
    }'
  ```

  ```python Python theme={null}
  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
  ```

  ```javascript JavaScript theme={null}
  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));
  ```
</CodeGroup>

## 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
```