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

# Upload Contacts to a List

> Upload contacts to a specific list



## OpenAPI

````yaml POST /lists/{listId}/contacts
openapi: 3.0.1
info:
  title: AI Phone Call Service API
  description: >-
    API for managing AI-based phone calls, including call initiation and result
    retrieval.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://my.cald.ai/client/api/v1
security:
  - apiKeyAuth: []
paths:
  /lists/{listId}/contacts:
    post:
      description: Upload contacts to a specific list
      parameters:
        - name: listId
          in: path
          description: The list ID of the list
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                contacts:
                  type: array
                  description: List of contacts to upload
                  items:
                    $ref: '#/components/schemas/Contact'
              required:
                - contacts
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: >-
                      Whether the contacts were successfully uploaded, can be
                      either `success` or `failed`
        '404':
          description: List not found
        '409':
          description: Contact with the same phone number already exists in the list
components:
  schemas:
    Contact:
      type: object
      properties:
        phoneNumber:
          type: string
          description: >-
            The phone number of the individual or business you're calling. - For
            international numbers, include the country code without extra
            formatting (such as parentheses or dashes), for example,
            '+441234567890'. - For U.S. numbers, although formatting is allowed,
            it's advisable to remove any additional characters for consistency.
        prospectName:
          type: string
          description: >-
            The prospectName is the default variable that is always present for
            all agents. It can be used in your agent scripts on the MyCald
            Dashboard by typing {prospectName}.
        email:
          type: string
          description: The email address of the contact, this is optional
        yourCustomVariable:
          type: string
          description: >-
            Feel free to add more custom variables to the list, depending on the
            use case. Once configured in the agent page of the MyCald Dashboard,
            they will automatically become available in the API
      required:
        - phoneNumber
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Your API key, e.g. `caldLiveDe39a3accb206dd615f30d118e519df0`

````