---
title: "Create a contact list, optionally importing rows in the same request"
method: POST
path: "/v1/contact-lists"
---

# Create a contact list, optionally importing rows in the same request

`POST /v1/contact-lists`

## Request

- Base URL: `https://api.skysay.ai`
- URL: `https://api.skysay.ai/v1/contact-lists`
- Auth: none declared

Rows carry phone_e164 plus optional name, language, time_zone (an IANA time zone, matched ignoring case and stored by its zone name; empty takes the number's zone when it has only one), external_reference, consent_basis and flat template variables (the attempt's whole call context: at most 32 keys and 4 KB, lists of at most 16 items; never secrets). Invalid rows are reported per row; duplicates within the list are skipped. At most 10,000 rows per request.

## Request body

- ContactListCreate
  - `contacts` ContactRow[]
    - `consent_basis` 'existing_customer' | 'explicit_consent'
    - `external_reference` string
    - `first_name` string: The contact's first name, as supplied (never derived from `name`); no `{` or `}`. Empty clears it. A custom value named `first_name` in `variables` is a separate value.
    - `language` string
    - `name` string
    - `phone_e164` string, required
    - `time_zone` string: IANA time zone such as America/New_York, matched ignoring case. Another spelling of a zone (US/Eastern, Europe/Kiev, EST) is stored as the zone it names; an offset such as UTC-5 is refused. Empty: the number's zone, when the number has only one
    - `variables` object: Flat template variables: the attempt's whole call context, at most 32 keys and 4 KB, lists of at most 16 items; never secrets
  - `name` string, required
  - `organization_id` string, required
  - `project_id` string, required
  - `source` 'api' | 'csv' | 'xlsx' | 'mcp': How the rows were collected, recorded on the list. `xlsx` means the workspace read an Excel workbook in the browser and sent these rows; the API itself never parses a spreadsheet.

## Response `201`

Contact list with an import report when rows were supplied

---

[API](https://skmtc.dev/skysay/apis/skysay-api.md) · [All operations](https://skmtc.dev/skysay/apis/skysay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skysay/apis/skysay-api/revisions/148c7e111260?raw)