> ## Documentation Index > Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Import contacts from file > Starts an asynchronous bulk import of contacts from a previously uploaded file (`fileId`) into the given inbox. Returns an `importId` immediately; the import itself runs in the background, so newly imported contacts may not appear in `contacts.list` right away. ## OpenAPI ````yaml /api-reference/platform-api.json post /v1/contacts/import openapi: 3.1.1 info: title: ChatbotX version: 0.0.1 servers: - url: https://app.chatbotx.io/api security: - bearerAuth: [] - developerAccessToken: [] - tokenInSearchParams: [] paths: /v1/contacts/import: post: tags: - Contacts summary: Import contacts from file description: >- Starts an asynchronous bulk import of contacts from a previously uploaded file (`fileId`) into the given inbox. Returns an `importId` immediately; the import itself runs in the background, so newly imported contacts may not appear in `contacts.list` right away. operationId: contacts.import requestBody: required: true content: application/json: schema: type: object properties: fileId: type: string pattern: ^\d+$ description: >- Id (numeric string) of a previously uploaded CSV/XLSX file to import. channel: enum: - omnichannel - webchat - messenger - whatsapp - zalo - smtp - telegram - instagram - threads - tiktok - api type: string description: Channel to attach imported contacts to. inboxId: type: string pattern: ^\d+$ description: >- Inbox id (numeric string) to import contacts into. Get it from `inboxes.list`. timezone: type: string minLength: 1 maxLength: 255 description: >- IANA timezone applied to imported contacts, e.g. `America/New_York`. countryCode: type: string pattern: ^\+\d{1,4}$ description: >- Default country code used to normalize imported phone numbers. phoneNumber: type: string maxLength: 255 description: >- Column name in the file that holds the contact's phone number. contactId: type: string maxLength: 255 description: >- Column name in the file that holds a channel-specific user id. sourceUserId: type: string maxLength: 255 description: >- Column name in the file that holds the WhatsApp Business-Scoped User ID. Only used for whatsapp imports. email: type: string maxLength: 255 description: Column name in the file that holds the contact's email. firstName: type: string maxLength: 255 description: Column name in the file that holds the contact's first name. lastName: type: string maxLength: 255 description: Column name in the file that holds the contact's last name. tagId: type: string pattern: ^\d+$ description: Tag id (numeric string) to apply to every imported contact. fieldMapping: type: array maxItems: 10 items: type: object properties: column: type: string minLength: 1 maxLength: 255 description: Column name in the file to map. customFieldId: anyOf: - type: string pattern: ^\d+$ - type: string pattern: ^bot_field:\d+$ description: >- Custom field id (numeric string), or `bot_field:` to apply a bot-field mapping once after import. required: - column - customFieldId description: Column-to-custom-field mappings, up to 10. required: - fileId - channel - inboxId responses: '201': description: OK content: application/json: schema: type: object properties: importId: type: string description: >- Id of the background import job. The import runs asynchronously; imported contacts appear in `contacts.list` once it finishes. required: - importId '400': description: '400' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: businessError status: const: 400 message: type: string default: An error occurred while processing your request data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '401': description: '401' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: UNAUTHORIZED status: const: 401 message: type: string default: Authentication required data: {} required: - defined - code - status - message - type: object properties: defined: const: true code: const: INVALID_CHATBOT_TOKEN status: const: 401 message: type: string default: Invalid or missing workspace API token data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '403': description: '403' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: FORBIDDEN status: const: 403 message: type: string default: You do not have permission to perform this action data: {} required: - defined - code - status - message - type: object properties: defined: const: true code: const: trialExpired status: const: 403 message: type: string default: Trial expired data: {} required: - defined - code - status - message - type: object properties: defined: const: true code: const: macLimitReached status: const: 403 message: type: string default: Monthly active contact limit reached data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '422': description: '422' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: invalidRequestData status: const: 422 message: type: string default: Input validation failed data: type: object properties: issues: type: array items: type: object properties: message: type: string path: type: array items: anyOf: - type: string - type: number - type: object properties: key: anyOf: - type: string - type: number required: - key additionalProperties: {} required: - message additionalProperties: {} required: - issues additionalProperties: {} required: - defined - code - status - message - data - type: object properties: defined: const: true code: const: validation status: const: 422 message: type: string default: Validation error data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '429': description: '429' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: tooManyRequests status: const: 429 message: type: string default: Too many requests data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '500': description: '500' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: INTERNAL_SERVER_ERROR status: const: 500 message: type: string default: An unexpected error occurred data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' components: schemas: UndefinedError: type: object properties: defined: const: false code: type: string status: type: number message: type: string data: {} required: - defined - code - status - message securitySchemes: bearerAuth: type: http scheme: bearer developerAccessToken: type: http scheme: bearer tokenInSearchParams: type: apiKey in: query name: token ````