> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesfinity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a List

> Creates a new contact list

Creates a new contact list for the team. Contacts are optional and can be added later via the [Add Contact](/api-reference/endpoint/add-contact) endpoint.

### Limits

| Resource                  | Limit            |
| ------------------------- | ---------------- |
| Contacts per list         | 2,000            |
| List name                 | 1–100 characters |
| Notes per contact         | 2,000 characters |
| Phone numbers per contact | 10               |
| Custom fields per contact | 10               |
| Request payload size      | 10MB             |

### Request Body

| Field      | Type   | Required | Description                                                                                                                               |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `name`     | string | Yes      | Name of the contact list (1–100 characters)                                                                                               |
| `user_id`  | string | Yes      | ID of the team member who owns this list. Must be a valid member of the team. Get this from [Get Team](/api-reference/endpoint/get-team). |
| `contacts` | array  | No       | Array of contact objects (max 2,000). See [Add Contact](/api-reference/endpoint/add-contact) for the contact object schema.               |

### Example Request

```json theme={null}
{
  "name": "Q2 Outbound Prospects",
  "user_id": "680edc0d1504192884a148e0",
  "contacts": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@acme.com",
      "company": "Acme Corp",
      "title": "VP of Sales",
      "phone_numbers": [
        {
          "type": "direct",
          "number": "+14155552671"
        }
      ]
    }
  ]
}
```

### Example Request (empty list)

```json theme={null}
{
  "name": "Q2 Outbound Prospects",
  "user_id": "680edc0d1504192884a148e0"
}
```

### Response (201)

Returns the created contact list object with its `_id`. Use this ID for all subsequent operations (adding contacts, merging, deleting, etc.).


## OpenAPI

````yaml POST /v1/contact-lists
openapi: 3.0.1
info:
  title: Salesfinity API
  description: API documentation for Salesfinity platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://client-api.salesfinity.co
security:
  - ApiKeyAuth: []
paths:
  /v1/contact-lists:
    post:
      tags:
        - Contact Lists
      description: Creates a new contact list
      operationId: create-list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactListDTO'
      responses:
        '201':
          description: Contact list created successfully
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreateContactListDTO:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name of the contact list
        user_id:
          type: string
          description: ID of the team member who owns this list
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/ContactListContactDTO'
          maxItems: 2000
          description: Array of contacts (optional, max 2,000)
      required:
        - name
        - user_id
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    ContactListContactDTO:
      type: object
      properties:
        account:
          type: string
          maxLength: 500
          description: Account or organization identifier
        first_name:
          type: string
          maxLength: 200
          description: Contact first name
        last_name:
          type: string
          maxLength: 200
          description: Contact last name
        linkedin:
          type: string
          maxLength: 500
          description: LinkedIn profile URL
        email:
          type: string
          maxLength: 320
          description: Contact email address
        website:
          type: string
          maxLength: 500
          description: Website URL
        notes:
          type: string
          maxLength: 2000
          description: Free-text notes about the contact
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/NumbersDTO'
          maxItems: 10
          description: Phone numbers (max 10 per contact)
        company:
          type: string
          maxLength: 300
          description: Company name
        title:
          type: string
          maxLength: 300
          description: Job title
        priority:
          type: number
          description: Contact priority (lower is higher priority)
        timezone:
          type: string
          maxLength: 100
          description: IANA timezone identifier (e.g. America/New_York)
        external_relations:
          type: object
          description: External system references (e.g. CRM IDs)
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldInputDTO'
          maxItems: 10
          description: Custom fields (max 10 per contact)
    NumbersDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - mobile
            - direct
            - office
        number:
          type: string
        country_code:
          type: string
        extension:
          type: string
      required:
        - type
        - number
    CustomFieldInputDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - string
            - number
            - boolean
          description: Field data type
        label:
          type: string
          maxLength: 100
          description: Display label for the field
        value:
          description: Field value (string, number, boolean, or string array)
      required:
        - type
        - label
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````