--- title: "Import CRM contacts in bulk" method: POST path: "/v2/crm/contacts/import" --- # Import CRM contacts in bulk `POST /v2/crm/contacts/import` ## Request - Base URL: `https://api.signnow.com` - URL: `https://api.signnow.com/v2/crm/contacts/import` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) This endpoint allows API users to import contacts from a CSV file into the authenticated user account. Users can map CSV columns to contact fields and configure how duplicate contacts are handled. **Notes:** * The CSV file must contain a header row. Data rows start from line 2. * Rows where the email value is missing or invalid are skipped and reported under `failed`. * Rows with invalid non-email fields (phone, address, etc.) are still created with those fields set to `null` and reported as `created_partial`. * CSV separator is auto-detected from the header row (supported: `,`, `;`, `\t`, `|`). * Phone country codes are auto-detected from the phone number format (e.g., `+1` → `US`, `+44` → `GB`). * If `duplicates` is not specified and duplicate contacts (by email) already exist, a `409 Conflict` is returned. **Sample CSV** ```csv First Name,Last Name,Email,Phone,Company Name,Job Title,Country,Street Address,Apartment,City,State,ZIP Code,Description John,Smith,john@example.com,5551234567,Sample Company,Manager,US,17 Station St,Suite 101,Brookline,Massachusetts,02445,This is a sample contact to demonstrate how the columns should be filled out. Don't forget to remove this contact before importing your contacts. ``` > Values in `mapping[...]` must exactly match the column headers in your CSV (case-sensitive, including spaces and punctuation). Set an optional `mapping[...]` to `null` to skip a field. ## Request body `multipart/form-data` - object - `file` string, binary, required: CSV file to import. Maximum size: 5 MB. Maximum rows: 3000 (excluding header). - `duplicates` string: Duplicate handling strategy. Allowed values: `skip`, `replace`. If omitted, the request returns `409 Conflict` when contacts with matching emails already exist. - `mapping[email]` string, required: Maps the contact email to a CSV column. The value is the column header name in your CSV. Required. Email values in the column must be valid and cannot end with `@no.reply`. Example value: `Email`. - `mapping[first_name]` string: Maps the contact first name to a CSV column. The value is the column header name. Maximum 128 characters. Example value: `First Name`. - `mapping[last_name]` string: Maps the contact last name to a CSV column. The value is the column header name. Maximum 128 characters. Example value: `Last Name`. - `mapping[description]` string: Maps the contact description to a CSV column. The value is the column header name. Maximum 408 characters. Example value: `Description`. - `mapping[phone]` string: Maps the contact phone number to a CSV column. The value is the column header name. Phone values must contain 10–15 digits; country code is auto-detected from the format. Example value: `Phone`. - `mapping[company][name]` string: Maps the company name to a CSV column. The value is the column header name. Maximum 128 characters. Example value: `Company Name`. - `mapping[company][job_title]` string: Maps the contact job title to a CSV column. The value is the column header name. Maximum 128 characters. Example value: `Job Title`. - `mapping[address][country]` string: Maps the contact country to a CSV column. The value is the column header name. Country values must use ISO 2-character codes. Required when `mapping[address][zip_code]` is provided. Example value: `Country`. - `mapping[address][street]` string: Maps the street address to a CSV column. The value is the column header name. Maximum 255 characters. Example value: `Street Address`. - `mapping[address][apartment]` string: Maps the apartment / unit to a CSV column. The value is the column header name. Maximum 255 characters. Example value: `Apartment`. - `mapping[address][city]` string: Maps the city to a CSV column. The value is the column header name. Maximum 128 characters. Example value: `City`. - `mapping[address][state]` string: Maps the state to a CSV column. The value is the column header name. United States only. Maximum 128 characters. Example value: `State`. - `mapping[address][zip_code]` string: Maps the zip code to a CSV column. The value is the column header name. Maximum 10 characters. Requires `mapping[address][country]` to be provided. Example value: `ZIP Code`. ## Response `201` Contacts imported successfully. - object - `data` object: Results of the import. - `failed` object: Rows that could not be created due to a missing or incorrect email. - `rows` integer[]: Row numbers (starting at 2) of failed rows. - `count` integer: Number of failed rows. - `created` integer: Number of contacts fully created (excludes partially created). - `created_partial` object: Contacts created with some non-email fields set to `null` due to validation errors. - `rows` integer[]: Row numbers of the contacts created without some invalid fields, starting from `2`. - `count` integer: Number of contacts created without some invalid fields. ## Other responses - `400`: * Missing or incorrect bearer token. * Incorrect `mapping` type. * The `mapping` is empty. * The `file` is missing or larger than 5 MB. * Incorrect `file` type. * Incorrect file extension. - `409`: Returned when the `duplicates` parameter is not set and contacts with matching emails already exist. - `422`: * Incorrect `mapping` value. * Incorrect `duplicates` value. * The `file` exceeds 5 MB. * The `file` exceeds 3000 lines. * The `file` is empty. * The email column is missing in the file. * Some mapping columns are missing in the file. * Unable to import contacts. --- [API](https://skmtc.dev/signnow/apis/signnow-api.md) - [All operations](https://skmtc.dev/signnow/apis/signnow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signnow/apis/signnow-api/revisions/1c9c30a6142b?raw)