---
name: "import_csv"
area: "imports"
title: "Import contacts or companies from a CSV"
price: "$0.001 per record imported (created or updated)"
method: "POST"
url: "https://api.conecto.chat/v1/tools/import_csv"
mcp_server: "https://api.conecto.chat/mcp/imports"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/imports/import_csv"
---

# Import contacts or companies from a CSV (`import_csv`)

Imports contacts or companies from a CSV, as text or a link, matching columns by their names; importing it again updates instead of duplicating.

Import contacts or companies from a CSV file: send its text as csv, or an https link to it as url (a public Google Sheets CSV link works). Columns are matched by their header names in any case or spelling: email, name, first name, last name, phone or mobile, company or organization, domain, website, title or job title, notes, address, city or country (joined into location), lifecycle stage, timezone, language; for companies: name, domain, website, industry, employees, lifecycle stage, notes. The result lists the columns it mapped and the ones it ignored. Contacts match existing ones by email, companies by domain and then by name, so importing the same file again updates instead of duplicating. Up to 5,000 rows a call: a longer file returns next_cursor to continue. Unchanged records are free, and 1,000 imported records cost $1. max_records x $0.001 is reserved while it runs and only what was imported is charged; lower max_records if your balance is smaller.

Price: $0.001 per record imported (created or updated). A call that fails costs nothing.

## Use it when

People or companies arrive as a spreadsheet: a trade fair list, an export from another tool.

- For rows for a table of the business's own, use [tables_import](https://conecto.chat/tools/tables/tables_import.md).
- For a whole HubSpot account with deals and notes, use [import_from_hubspot](https://conecto.chat/tools/imports/import_from_hubspot.md).

## Say this to your agent

> Import the leads from the hospitality fair in Hamburg. Lena exported them from the badge scanner as a CSV.

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `kind` | string | no | What each row is. | `"contacts"`, `"companies"` | `"contacts"` |
| `csv` | string | no | The CSV text, column names in the first row (up to about 2 MB; use url for more). 1 to 2,000,000 characters. |  |  |
| `url` | string | no | An https link to the CSV file, instead of csv. At most 20 MB. 8 to 2,048 characters. |  |  |
| `max_records` | integer | no | The most rows to read in this call (5,000 at most). 1 to 5,000. |  | `5000` |
| `next_cursor` | string | no | The next_cursor a previous run of this import returned, to continue where it stopped. Up to 2,000 characters. |  |  |

## Example

Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff.

MCP: call `import_csv` on the MCP server `https://api.conecto.chat/mcp/imports` with these arguments:

```json
{
  "kind": "contacts",
  "csv": "Email,First name,Last name,Company,City\nmarie.koch@restaurant-koch.example,Marie,Koch,Restaurant Koch,Hamburg\nb.yilmaz@yilmaz-hotels.example,Berk,Yilmaz,Yilmaz Hotels,Kiel\n"
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/import_csv \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "contacts", "csv": "Email,First name,Last name,Company,City\nmarie.koch@restaurant-koch.example,Marie,Koch,Restaurant Koch,Hamburg\nb.yilmaz@yilmaz-hotels.example,Berk,Yilmaz,Yilmaz Hotels,Kiel\n"}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "import_csv",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.002",
  "balance_usd": "$19.75",
  "result": {
    "source": "csv",
    "done": true,
    "records_imported": 2,
    "imported": {
      "contacts": {
        "created": 2,
        "updated": 0,
        "unchanged": 0,
        "skipped": 0
      }
    },
    "kind": "contacts",
    "rows_in_file": 2,
    "rows_read": 2,
    "columns": {
      "mapped": {
        "Email": "email",
        "First name": "first_name",
        "Last name": "last_name",
        "Company": "company",
        "City": "location"
      },
      "ignored": []
    }
  }
}
```

`result`: source, done, records_imported, imported (created, updated, unchanged, skipped), kind, rows_in_file, rows_read and columns (mapped and ignored); next_cursor when rows remain.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `invalid_input` | 400 | Neither or both of csv and url were given, the CSV is empty or has no header row, or url is not a public https:// link. | Send one of them, with the column names in the first row. |
| `unmapped_columns` | 422 | No column looks like an email, name or phone (for companies: a name, domain or website). | Name the columns like Email, Name, Company and send it again. |
| `fetch_failed` | 422 | The link answered with an error or redirected too often. | Make sure anyone with the link can open the CSV itself. |
| `fetch_failed` | 502 | The link did not answer. | Check it and try again. |
| `too_large` | 413 | The file at the link is over 20 MB. | Split it and import the parts one by one. |
| `invalid_cursor` | 400 | next_cursor is not one this import returned. | Pass back exactly the next_cursor of the last run, or leave it out to start again (nothing is duplicated). |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [import_from_hubspot](https://conecto.chat/tools/imports/import_from_hubspot.md): Imports a HubSpot account in the background: companies, contacts, deals and notes, linked as they were. $0.001 per record imported (created or updated).
- [import_from_pipedrive](https://conecto.chat/tools/imports/import_from_pipedrive.md): Imports a Pipedrive account in the background: organizations, persons, deals, notes and activities, linked as they were. $0.001 per record imported (created or updated).
- [import_from_zendesk](https://conecto.chat/tools/imports/import_from_zendesk.md): Imports Zendesk Support tickets in the background, with their public replies, and each requester as a contact; nobody is emailed. $0.001 per record imported (created or updated).
- [import_status](https://conecto.chat/tools/imports/import_status.md): What imports brought in so far, per source, and the last 10 import runs with their status, cost and next_cursor. Free up to 1,000,000 reads a month.