> ## Documentation Index > Fetch the complete documentation index at: https://docs.talqui.chat/llms.txt > Use this file to discover all available pages before exploring further. # Create contact import > Registers an already-uploaded CSV as a pending import and returns at once. Only the first bytes are read in the request, to settle the file's encoding and check the mapped columns against its header row: a 200.000-row file cannot be walked inside an HTTP round-trip, so the response is an acknowledgement and a background scheduler picks the job up within seconds. Poll `GET /contacts/imports/:importID` (or listen for the socket event) for progress. ## OpenAPI ````yaml /api/services-api.yaml post /v1/tenants/{tenantID}/contacts/imports openapi: 3.0.3 info: description: >- Talqui is an omnichannel customer service platform that unifies conversations from WhatsApp, Instagram, Telegram, and many other channels into a single attendant panel, alongside a broader ecosystem of plugins and integrations. This API gives developers programmatic access to Talqui's services layer, exposing the operations needed to read and manage tenants, conversations, plugins, and related resources that power that platform. Authentication is available on behalf of an Operator (the default for this API), a Plugin Connection, or a Plugin — see the [Talqui authentication guide](https://docs.talqui.chat/guides/introduction/authentication/) for how each token is obtained and when to use it. Need help or have questions not covered here? Reach out to support@talqui.com. license: name: ISC url: https://opensource.org/license/isc-license-txt title: Talqui - Services API version: 0.69.1 servers: - description: Production url: https://services-api.talqui.chat security: [] tags: - name: Tenants - name: Settings - name: Analytics/Reports - name: Analytics - name: Campaigns - name: Campaigns/Models - name: Contacts - name: Contacts/Imports - name: Handoff links - name: Inboxes - name: Messages - name: Notifications - name: Sessions - name: Operators/Shortcuts - name: Operators - name: Plugins - name: Setup - name: Uploads paths: /v1/tenants/{tenantID}/contacts/imports: post: tags: - Contacts/Imports summary: Create contact import description: >- Registers an already-uploaded CSV as a pending import and returns at once. Only the first bytes are read in the request, to settle the file's encoding and check the mapped columns against its header row: a 200.000-row file cannot be walked inside an HTTP round-trip, so the response is an acknowledgement and a background scheduler picks the job up within seconds. Poll `GET /contacts/imports/:importID` (or listen for the socket event) for progress. operationId: CreateContactImportController parameters: - in: path name: tenantID required: true schema: description: The tenant the contacts are imported into. format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ type: string requestBody: content: application/json: schema: properties: contactTags: default: [] description: >- Tags applied to every imported contact, on top of the generated import tag. items: maxLength: 64 minLength: 1 type: string maxItems: 20 type: array country: default: BR description: >- ISO country used to normalise phones typed without an international prefix. maxLength: 2 minLength: 2 type: string delimiter: default: ; description: >- Column separator of the uploaded file: any single character except `"`, CR, LF and NUL. maxLength: 1 minLength: 1 type: string encoding: description: >- Text encoding of the uploaded file. Detected from its bytes when absent; a byte-order mark or a UTF-16 NUL pattern overrides a conflicting value. enum: - utf-8 - utf-16le - utf-16be - windows-1252 - macintosh - ibm850 type: string fileID: description: >- fileID of the CSV the browser uploaded to talqui-services-storage (namespace "contact-imports", private, this tenant). maxLength: 128 minLength: 1 type: string fileMapping: additionalProperties: type: string description: >- CSV header → contact field. Targets: contactFullName, contactFirstname, contactLastname, contactPhone, contactEmail, or contactMeta.. type: object fileName: description: Original file name, shown back to the operator. maxLength: 255 minLength: 1 type: string recordDelimiter: default: auto description: >- Line ending of the uploaded file. `auto` lets the parser detect it. enum: - auto - lf - crlf - cr type: string required: - fileID - fileName - fileMapping type: object required: true responses: '200': content: application/json: schema: additionalProperties: false properties: importID: description: >- Identifier of the created import job; poll it for progress. type: string importStatus: description: Lifecycle status. Always "pending" on creation. type: string importTag: description: >- Tag stamped on every contact this import creates or updates, so they can be found again later. type: string required: - importID - importStatus - importTag type: object description: Response for status 200. '400': content: application/json: schema: properties: errors: items: oneOf: - $ref: '#/components/schemas/MissingTenantIDError' - $ref: '#/components/schemas/MissingOrganizationIDError' - $ref: '#/components/schemas/RequestValidationError' - $ref: '#/components/schemas/InvalidImportFileError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- MissingTenantIDError (error_code 1001): tenantID absent from the URL. | MissingOrganizationIDError (error_code 1743): operator token carries no organizationID. | RequestValidationError (error_code 1002): request body or params fail schema validation — including a mapping whose headers carry control characters (wrong file encoding), or whose targets are unknown or repeated. | InvalidImportFileError (error_code 1800): fileID unknown to the storage service, or not a ready contact-import file of this tenant. '401': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/UnauthorizedError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: 'UnauthorizedError (error_code 1003): missing/invalid operator token.' '403': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/ForbiddenError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: 'ForbiddenError (error_code 1004): operator token rejected upstream.' '422': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/InvalidImportMappingError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- InvalidImportMappingError (error_code 1801): mapping has neither a phone nor an e-mail column, or names a column the file's header row does not have. '500': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/UnknownError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- UnknownError (error_code 5999): Unexpected internal error not otherwise documented for this endpoint. '502': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/StorageReadError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- StorageReadError (error_code 5009): the storage service could not be reached, or the file could not be read. security: - operatorAuth: [] components: schemas: MissingTenantIDError: additionalProperties: false properties: error: enum: - MissingTenantIDError type: string error_code: enum: - 1001 type: number message: example: tenantID is required. type: string statusCode: enum: - 400 type: number required: - statusCode - error - error_code - message type: object MissingOrganizationIDError: additionalProperties: false properties: error: enum: - MissingOrganizationIDError type: string error_code: enum: - 1743 type: number message: example: >- organizationID could not be resolved from the authenticated operator. type: string statusCode: enum: - 400 type: number required: - statusCode - error - error_code - message type: object RequestValidationError: additionalProperties: false properties: error: enum: - RequestValidationError type: string error_code: enum: - 1002 type: number fields: items: additionalProperties: false properties: allowed: type: string field: type: string received: type: string required: - field - received - allowed type: object type: array message: example: Invalid request data. type: string statusCode: enum: - 400 type: number required: - statusCode - error - error_code - message - fields type: object InvalidImportFileError: additionalProperties: false properties: error: enum: - InvalidImportFileError type: string error_code: enum: - 1800 type: number message: example: The import file is missing or does not belong to this tenant. type: string statusCode: enum: - 400 type: number required: - statusCode - error - error_code - message type: object UnauthorizedError: additionalProperties: false properties: error: enum: - UnauthorizedError type: string error_code: enum: - 1003 type: number message: example: You are not authorized to perform this request. type: string statusCode: enum: - 401 type: number required: - statusCode - error - error_code - message type: object ForbiddenError: additionalProperties: false properties: error: enum: - ForbiddenError type: string error_code: enum: - 1004 type: number message: example: You do not have access to this resource. type: string statusCode: enum: - 403 type: number required: - statusCode - error - error_code - message type: object InvalidImportMappingError: additionalProperties: false properties: error: enum: - InvalidImportMappingError type: string error_code: enum: - 1801 type: number message: example: The mapping must include a phone or an e-mail column. type: string statusCode: enum: - 422 type: number required: - statusCode - error - error_code - message type: object UnknownError: additionalProperties: false properties: error: enum: - UnknownError type: string error_code: enum: - 5999 type: number message: example: For some unknown reason your request has not succeeded. type: string statusCode: enum: - 500 type: number required: - statusCode - error - error_code - message type: object StorageReadError: additionalProperties: false properties: error: enum: - StorageReadError type: string error_code: enum: - 5009 type: number message: example: Failed to read file from storage. type: string statusCode: enum: - 502 type: number required: - statusCode - error - error_code - message type: object securitySchemes: operatorAuth: bearerFormat: JWT description: >- Behalf of an Operator (default). A JWT issued by Talqui Core when an operator signs in, scoped to every tenant that operator belongs to. Send as `Authorization: Bearer `. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.