---
title: "Add contacts to a contact list"
method: POST
path: "/contact-lists/{contact_list_id}/contacts"
tags: ["Contact Lists"]
---

# Add contacts to a contact list

`POST /contact-lists/{contact_list_id}/contacts`

Add contacts to a contact list by contact ID and/or phone number.

    At least one of ``contact_ids`` or ``phone_numbers`` is required.

    **Phone number resolution:**
    Each phone number is matched to an existing contact in your organisation.
    - ``auto_create=false`` (default): unrecognised numbers are reported in
      ``not_found_phone_numbers`` and no error is raised.
    - ``auto_create=true``: unrecognised numbers are used to create new contacts
      automatically. The new contact's ``first_name`` is set to the phone number string.
      The newly created contact IDs are reported in ``created_contact_ids``.

    Contacts already in the list are counted silently (idempotent operation).
    ``added_count`` reflects only newly added contacts.

    Authentication:
    - API key with READ_WRITE permission

## Path parameters

- `contact_list_id` string, uuid, required

## Request body

- object — Request schema for adding contacts to a contact list. Specify at least one of ``contact_ids`` or ``phone_numbers``. When ``auto_create`` is ``True``, phone numbers that do not match any existing contact in the organization are automatically created as new contacts. The new contact's ``first_name`` is set to the phone number string. When ``auto_create`` is ``False`` (the default), unrecognised phone numbers are reported in the ``not_found_phone_numbers`` field of the response and no error is raised.
  - `contact_ids` string[], nullable — List of contact UUIDs to add to the list (max 500 per request)
  - `phone_numbers` string[], nullable — List of phone numbers in E.164 format to add to the list (max 500 per request). Each number is resolved to an existing contact in your organisation.
  - `auto_create` boolean — When True, phone numbers that do not match any existing contact are automatically created as new contacts (first_name set to the phone number). When False, unrecognised phone numbers are reported in not_found_phone_numbers without raising an error.

## Response `200`

Contacts added successfully

- unknown

## Other responses

- `400` — Invalid request data
- `401` — Invalid or missing API key
- `403` — Insufficient permissions
- `404` — Resource not found

---

[API](https://skmtc.net/yourang/apis/yourang-ai-external-api-v1.md) · [All operations](https://skmtc.net/yourang/apis/yourang-ai-external-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yourang/yourang-ai-external-api-v1/revisions/49680ee64400/schema)