---
title: "Bulk import contacts"
method: POST
path: "/contacts/import"
tags: ["Contacts"]
---

# Bulk import contacts

`POST /contacts/import`

## Request

- Base URL: `https://api.supersendtx.com`
- URL: `https://api.supersendtx.com/contacts/import`
- Auth: HTTP bearer

Accepts a JSON array of contacts, `{ "contacts": [...] }`, `{ "csv": "…" }`,
or a raw CSV body. CSV columns other than `email`, `external_id`,
`first_name`, and `last_name` are stored as attributes. Malformed
addresses are counted in `invalid` rather than failing the batch.

At most 5,000 contacts per request — split larger lists across several
requests. More rows returns 400; a JSON body over 8 MB returns 413.

## Request body

- union
  - ContactImportRow[]
    - `email` string, email, required
    - `external_id` string, nullable
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `attributes` object
  - object
    - `contacts` ContactImportRow[]
      - `email` string, email, required
      - `external_id` string, nullable
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `attributes` object
    - `csv` string: CSV text with a header row containing an `email` column
    - `source` 'api' | 'import' | 'dashboard' | 'agent' | 'on_site': Where the contact was first created. `on_site` means an on-site message on your website captured the address.

## Response `200`

Import summary

- ImportContactsResponse
  - `created` integer, required
  - `updated` integer, required
  - `invalid` integer, required: Rows whose email address was malformed. They are skipped, not fatal.

## Other responses

- `400`: Unreadable body, a CSV with no `email` column, or more than 5,000 contacts in one request
- `401`: Missing or invalid API key
- `413`: Request body too large (a JSON body over 8 MB, or a CSV body over 64 MB)

---

[API](https://skmtc.dev/ranla/apis/supersend-tx-api.md) · [All operations](https://skmtc.dev/ranla/apis/supersend-tx-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ranla/apis/supersend-tx-api/revisions/e3e782652f50?raw)