---
title: "Create contact lists"
method: POST
path: "/contacts/lists"
tags: ["contacts"]
---

# Create contact lists

`POST /contacts/lists`

Creates a contact list for use with campaigns using 1 of 3 inputs. A List of Contact objects, a list of String E.164 numbers, or a list of CallFire contactIds can be used as the data source for the created contact list. After contact list is added into the CallFire system, contact lists goes through seven system safeguards that check the accuracy and consistency of the data. For example, our system checks that contact number is formatted correctly, is valid, is not duplicated in another contact list, or is not added on a specific DNC list. You can configure to keep/merge or remove contacts which do not complies these rules. If contacts were not added to a contact list after the validation, this means the data needs to be properly formatted and corrected before calling this API

## Query parameters

- `fields` string

## Request body

- CreateContactListRequest — A request object is used to create a contact list from one of available contact sources
  - `contacts` Contact[] — A list of new contact objects to be added
    - `id` integer — An id of a contact
    - `firstName` string — A first name of a contact
    - `lastName` string — A last name of a contact
    - `zipcode` string — A Zip code of a contact
    - `homePhone` string — Phone number in E.164 format (11-digit). Example: 12132000384
    - `workPhone` string — Phone number in E.164 format (11-digit). Example: 12132000384
    - `mobilePhone` string — Phone number in E.164 format (11-digit). Example: 12132000384
    - `extraPhone1` string — Phone number in E.164 format (11-digit). Example: 12132000384
    - `extraPhone2` string — Phone number in E.164 format (11-digit). Example: 12132000384
    - `extraPhone3` string — Phone number in E.164 format (11-digit). Example: 12132000384
    - `externalId` string — An external id of a contact for syncing with external sources
    - `externalSystem` string — External system that external id refers to
    - `properties` object — Map of user-defined string properties for contact
    - `deleted` boolean — A deleted contact, deleted contacts are hidden from search results
  - `contactIds` integer[] — A list of ids of existing contacts in CallFire system
  - `contactNumbers` string[] — List of numbers in E.164 format (11-digit). Example: 12132000384
  - `contactNumbersField` string — A type of a phone number (homePhone, workPhone, mobilePhone). This parameter is used with contactNumbers and specifies which types of phone numbers are included to a contact list
  - `useCustomFields` boolean — A flag to indicate how to define property names for contacts. If true, uses the field and property names exactly as defined. If false will assign custom properties and fields to A, B, C, etc
  - `name` string — A name of a contact list

## Response `200`

successful operation

- ContactList — Represents a contact list in CallFire system
  - `id` integer — An Id of a contact list
  - `name` string — A name of a contact list
  - `size` integer — A number of contacts in a contact list
  - `created` integer — A time when a given resource was created, formatted in unix time milliseconds (read only). Example: 1473781817000 for Sat, 05 Jan 1985 14:03:37 GMT
  - `status` 'ACTIVE' | 'VALIDATING' | 'IMPORTING' | 'IMPORT_FAILED' | 'ERRORS' | 'DELETED' | 'PARSE_FAILED' | 'COLUMN_TOO_LARGE' — A current status of a contact list, available values: ACTIVE - contact list is ready, VALIDATING - contact list validation is in progress, IMPORTING - importing is in progress, IMPORT_FAILED - in case of errors occurred during the importing, ERRORS - contact list has validation errors, DELETED - contact list was deleted, PARSE_FAILED - contacts cannot be parsed, COLUMN_TOO_LARGE - if size of phone number or any other column exceeds 255 characters

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `500` — Internal Server Error

---

[API](https://skmtc.dev/callfire/apis/callfire-api-documentation.md) · [All operations](https://skmtc.dev/callfire/apis/callfire-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/callfire/callfire-api-documentation/revisions/9f6fb501bc03/schema)