---
title: "POST /create-contact-import"
method: POST
path: "/create-contact-import"
---

# POST /create-contact-import

`POST /create-contact-import`

## Request

- Base URL: `https://api.retellai.com`
- URL: `https://api.retellai.com/create-contact-import`
- Auth: HTTP bearer

Start an incremental contact import from an uploaded CSV: creates new contacts and updates existing ones matched by phone number. Mapped columns overwrite the matched contact's fields; unmapped columns are ignored. Runs asynchronously — poll get-contact-import for progress.

## Request body

- object
  - `upload_id` string, required: Id returned by upload-contact-import-file.
  - `column_mapping` CRMSyncMapping[], required: CSV headers mapped to contact fields. field_name is the contact field and external_field_name is the CSV header. Exactly one mapping must target phone_number. Unmapped columns are ignored.
    - `field_name` string, required: Retell contact field, built-in or custom, to map. Types must be compatible with the CRM field on both sides of the sync.
    - `external_field_name` string, required: Field on the CRM's contact object to map to. A name that does not exist there surfaces as an error on the sync job rather than at configuration time.
  - `default_country` string: Country for parsing phone numbers without a country code. Defaults to US.
  - `contact_tags` string[]: Tag labels added to every contact in this import. Labels are trimmed and deduplicated. New labels are added to the org's CRM config with generated tag IDs.

## Response `202`

Import queued.

- JobStatus
  - `status` 'queued' | 'running' | 'idle', required
  - `start_timestamp` number: Epoch milliseconds when the job started.
  - `succeeded` number: Number of items processed successfully so far.
  - `failed` number: Number of items that errored so far.
  - `triggered_by` 'manual' | 'cron': Whether the job was started by an explicit API call (`manual`) or by the scheduled sync (`cron`).

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `409`: Conflict
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

- **2026-10-16** `ca41f0dbb297`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/retellai/apis/retell-sdk/changes/create-contact-import/post.md)

---

[API](https://skmtc.dev/retellai/apis/retell-sdk.md) - [All operations](https://skmtc.dev/retellai/apis/retell-sdk/llms.txt) - [OpenAPI document](https://skmtc.dev/retellai/apis/retell-sdk/revisions/e482acaa292c?raw)