> ## Documentation Index > Fetch the complete documentation index at: https://docs.coldsend.pro/llms.txt > Use this file to discover all available pages before exploring further. # Import contacts from CSV > **Import contacts into the directory from a CSV file** Upserts contacts team-wide (decision 10): an email already present updates the existing contact rather than creating a duplicate, and no campaign membership is created. Pair with `POST /contacts/bulk/campaigns` to enrol imported contacts into a campaign. The `mapping` form field is JSON with the same direction the campaign upload uses -- **lead field name to CSV column header**: `{"email": "email_address", "first_name": "fname", "custom_city": "City"}`. Keys prefixed `custom_` land in the contact's free-form `custom_fields`. ## Example Usage ```python import requests response = requests.post( "https://api.coldsend.pro/api/public/v1/contacts/import", headers={"X-API-Key": "your-api-key"}, files={"file": open("contacts.csv", "rb")}, data={"mapping": '{"email": "email_address", "first_name": "fname"}'} ) print(response.json()) ``` ## OpenAPI ````yaml /public_openapi.json post /api/public/v1/contacts/import openapi: 3.0.3 info: title: ColdSend Public API description: >- Programmatic access to ColdSend for managing cold email campaigns and sender accounts. version: 1.0.0 contact: name: ColdSend Support email: support@coldsend.pro url: https://coldsend.pro servers: - url: https://api.coldsend.pro description: Production security: - ApiKeyAuth: [] paths: /api/public/v1/contacts/import: post: tags: - Contacts summary: Import contacts from CSV description: >- **Import contacts into the directory from a CSV file** Upserts contacts team-wide (decision 10): an email already present updates the existing contact rather than creating a duplicate, and no campaign membership is created. Pair with `POST /contacts/bulk/campaigns` to enrol imported contacts into a campaign. The `mapping` form field is JSON with the same direction the campaign upload uses -- **lead field name to CSV column header**: `{"email": "email_address", "first_name": "fname", "custom_city": "City"}`. Keys prefixed `custom_` land in the contact's free-form `custom_fields`. ## Example Usage ```python import requests response = requests.post( "https://api.coldsend.pro/api/public/v1/contacts/import", headers={"X-API-Key": "your-api-key"}, files={"file": open("contacts.csv", "rb")}, data={"mapping": '{"email": "email_address", "first_name": "fname"}'} ) print(response.json()) ``` operationId: import_contacts_api_public_v1_contacts_import_post requestBody: content: multipart/form-data: schema: $ref: >- #/components/schemas/Body_import_contacts_api_public_v1_contacts_import_post required: true responses: '200': description: Import completed content: application/json: schema: $ref: '#/components/schemas/ContactImportResponse' '400': description: Invalid file or mapping '401': description: Missing or invalid API key '403': description: Insufficient permissions - requires 'contacts:create' scope '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: Body_import_contacts_api_public_v1_contacts_import_post: properties: file: type: string format: binary title: File description: CSV file containing contacts mapping: type: string title: Mapping description: >- JSON object mapping lead field names to CSV column headers, e.g. {"email": "email_address", "custom_city": "City"} list_id: type: string format: uuid nullable: true title: List Id description: Add imported contacts to this static list filename: type: string nullable: true title: Filename description: Origin name to record as source_name type: object required: - file - mapping title: Body_import_contacts_api_public_v1_contacts_import_post ContactImportResponse: properties: batch_id: type: string format: uuid title: Batch Id total_rows: type: integer title: Total Rows description: Data rows found in the file imported_rows: type: integer title: Imported Rows description: Rows with a usable address skipped_rows: type: integer title: Skipped Rows description: Rows dropped as unusable (missing or invalid email) contacts_created: type: integer title: Contacts Created contacts_matched: type: integer title: Contacts Matched description: Rows that updated a contact the team already had added_to_list: type: integer title: Added To List default: 0 list_id: type: string format: uuid nullable: true title: List Id blocked_count: type: integer title: Blocked Count default: 0 blocked_entries: items: additionalProperties: true type: object type: array title: Blocked Entries type: object required: - batch_id - total_rows - imported_rows - skipped_rows - contacts_created - contacts_matched title: ContactImportResponse description: >- Outcome of a directory-level CSV import. `contacts_created` and `contacts_matched` split the imported rows into new people and people the team already had, which is the distinction decision 10 turns on: a team-wide upsert means re-importing the same file enriches the directory instead of duplicating it. Blocked addresses are **reported, not withheld**. Nothing created here can send; the blocklist is enforced at the point a campaign membership is created. Surfacing the count lets the UI warn that part of a freshly imported list will not be mailable. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key with format cs_live_xxx ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.