---
title: "Add a new contact"
method: POST
path: "/api/ext/v3/contacts"
tags: ["Contacts"]
---

# Add a new contact

`POST /api/ext/v3/contacts`

## Request body

- AddContactRequest — Request model for adding a new contact.
  - `whatsapp_number` string, required — The WhatsApp number of the contact to be added.
  - `name` string, required — The name of the contact.
  - `custom_params` CustomParamDto[], nullable — Optional list of custom parameters associated with the contact.
    - `name` string, required — The name of the custom parameter.
    - `value` string, required — The value of the custom parameter.

## Response `200`

Returns the created contact.

- ContactDto — Represents a contact object.
  - `id` string, nullable — Unique identifier for the contact.
  - `wa_id` string, nullable — WhatsApp identifier for the contact.
  - `name` string, nullable — The contact's name.
  - `phone` string, nullable — The contact's phone number.
  - `photo` string, nullable — URL or path to the contact's photo.
  - `created` string, date-time — The date and time when the contact was created.
  - `last_updated` string, date-time — The date and time when the contact was last updated.
  - `contact_status` string, nullable — The current status of the contact.
  - `source` string, nullable — The source where the contact originated from.
  - `channel_id` string, nullable — The identifier of the channel associated with the contact.
  - `ig_phone_source` string, nullable — Instagram phone source information.
  - `mg_phone_source` string, nullable — Messenger phone source information.
  - `opted_in` boolean — Indicates whether the contact has opted in for communications.
  - `allow_broadcast` boolean — Indicates whether the contact allows broadcast messages.
  - `allow_sms` boolean — Indicates whether the contact allows SMS messages.
  - `teams` string[], nullable — List of team associated with the contact.
  - `segments` string[], nullable — List of segments the contact belongs to.
  - `custom_params` CustomParamDto[], nullable — List of custom parameters associated with the contact.
    - `name` string, required — The name of the custom parameter.
    - `value` string, required — The value of the custom parameter.
  - `channel_type` string, nullable — The type of channel (e.g., whatsapp, instagram, messenger).
  - `display_name` string, nullable — The display name for the contact.
  - `contact_link` ContactLinkDto — Represents linked contact information across different messaging platforms.
    - `whats_app_contact_id` string, nullable — The contact identifier for WhatsApp.
    - `instagram_contact_id` string, nullable — The contact identifier for Instagram.
    - `messenger_contact_id` string, nullable — The contact identifier for Messenger.
  - `is_broadcast_limit_reached` string, nullable — Indicates whether the broadcast limit has been reached for this contact.

## Other responses

- `400` — The request is invalid.
- `401` — The request is unauthorized.
- `403` — The request is forbidden.
- `429` — Too many requests. Either the rate limit has been exceeded or usage limits have been reached.
- `500` — Unexpected error occurred. Please try again.

---

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