> ## 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.

# Add a Contact to a List

> Add a contact to an existing list

Adds a new contact to an existing contact list. The contact is added to both the source list and the dialing queue immediately.

### Path Parameters

* **id** (*required*, string): Contact list ID returned from [Create a List](/api-reference/endpoint/create-list) or [Get All Contact Lists](/api-reference/endpoint/get-contact-lists).

### Request Body

| Field                | Type   | Required | Max Length | Description                                                                                                                                   |
| -------------------- | ------ | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `first_name`         | string | No       | 200        | Contact's first name                                                                                                                          |
| `last_name`          | string | No       | 200        | Contact's last name                                                                                                                           |
| `email`              | string | No       | 320        | Contact's email address                                                                                                                       |
| `phone_numbers`      | array  | No       | 10 items   | Array of phone number objects                                                                                                                 |
| `company`            | string | No       | 300        | Company name                                                                                                                                  |
| `title`              | string | No       | 300        | Job title                                                                                                                                     |
| `linkedin`           | string | No       | 500        | LinkedIn profile URL                                                                                                                          |
| `website`            | string | No       | 500        | Website URL                                                                                                                                   |
| `account`            | string | No       | 500        | Account or organization identifier                                                                                                            |
| `notes`              | string | No       | 2,000      | Free-text notes about the contact                                                                                                             |
| `priority`           | number | No       | —          | Contact priority (lower is higher priority)                                                                                                   |
| `timezone`           | string | No       | 100        | IANA timezone identifier (e.g. `America/New_York`)                                                                                            |
| `external_relations` | object | No       | —          | External system references (e.g. CRM IDs)                                                                                                     |
| `custom_fields`      | array  | No       | 10 items   | Array of custom field objects. See [Get Custom Fields](/api-reference/endpoint/get-custom-fields) to retrieve available fields for your team. |

#### Phone Number Object

| Field          | Type   | Required | Description                                        |
| -------------- | ------ | -------- | -------------------------------------------------- |
| `type`         | string | Yes      | Phone number type: `mobile`, `direct`, or `office` |
| `number`       | string | Yes      | Phone number in E.164 format (e.g. `+14155552671`) |
| `country_code` | string | No       | ISO 3166-1 alpha-2 country code (e.g. `US`)        |
| `extension`    | string | No       | Phone extension                                    |

#### Custom Field Object

| Field   | Type   | Required | Max Length | Description                                            |
| ------- | ------ | -------- | ---------- | ------------------------------------------------------ |
| `type`  | string | Yes      | —          | Field data type: `string`, `number`, or `boolean`      |
| `label` | string | Yes      | 100        | Display label for the field                            |
| `value` | any    | No       | —          | Field value (string, number, boolean, or string array) |

### Example Request

```json theme={null}
{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@acme.com",
  "company": "Acme Corp",
  "title": "VP of Sales",
  "phone_numbers": [
    {
      "type": "direct",
      "number": "+14155552671"
    }
  ],
  "notes": "Interested in enterprise plan. Follow up after Q2.",
  "custom_fields": [
    {
      "type": "string",
      "label": "Industry",
      "value": "SaaS"
    },
    {
      "type": "number",
      "label": "Employee Count",
      "value": 250
    },
    {
      "type": "boolean",
      "label": "Decision Maker",
      "value": true
    }
  ]
}
```

### Response (201)

Returns the contact list ID.


## OpenAPI

````yaml POST /v1/contact-lists/{id}
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/{id}:
    post:
      tags:
        - Contact Lists
      description: Add a contact to an existing list
      operationId: add-contact
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactListContactDTO'
      responses:
        '201':
          description: Contact added successfully
          content:
            application/json:
              schema:
                $ref: a8f6f688-4195-49a3-9bf4-27d2debfec3a
components:
  schemas:
    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

````