---
title: "Add Contact"
method: POST
path: "/3.0/audiences/{audience_id}/contacts"
tags: ["audiences"]
---

# Add Contact

`POST /3.0/audiences/{audience_id}/contacts`

## Request

- Base URL: `https://api.mailchimp.com`
- URL: `https://api.mailchimp.com/3.0/audiences/{audience_id}/contacts`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://login.mailchimp.com/oauth2/authorize`
    - Token URL: `https://login.mailchimp.com/oauth2/token`
- TypeScript: <https://skmtc.dev/mailchimp/apis/mailchimp-api/docs/3.0/audiences/:audience_id/contacts/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new omni-channel contact for an audience.

## Path parameters

- `audience_id` string, required

## Query parameters

- `merge_field_validation_mode` 'ignore_required_checks' | 'strict'
- `data_mode` 'historical' | 'live'

## Request body

- object: An instance of a contact.
  - `email_channel` object
    - `email` string: Email address
    - `marketing_consent` object: A contact's current consent status for email marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values.
      - `status` 'confirmed' | 'consented' | 'denied' | 'unknown': Status of a contacts Marketing Consent
  - `language` string: The contact's detected language.
  - `merge_fields` object, nullable: A dictionary of merge fields where the keys are the merge tags. See the [Merge Fields documentation](https://mailchimp.com/developer/marketing/docs/merge-fields/#structure) for more about the structure.
  - `sms_channel` object
    - `marketing_consent` object: A contact's current consent status for SMS marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values.
      - `source` object: The source from which the parent's entity was created.
        - `name` string: The name of the entity's source
      - `status` 'consented' | 'confirmed' | 'unknown': The contact's SMS marketing consent status. Use `confirmed` for double opt-in audiences, `consented` for single opt-in audiences.
      - `captured_at` string, date-time: The timestamp when SMS marketing consent was captured (ISO 8601). Only accepted and returned when status is `confirmed`. The timestamp of the consent state change being recorded. Defaults to the current time if not provided. If the contact already has a consent timestamp on record that is equal to or newer than the supplied value, the supplied value is ignored (staleness guard); to update the consent timestamp supply a value strictly newer than the stored one.
    - `sms_phone` string: SMS Phone Number
  - `tags` union[]: An array of tags to add to the contact. Accepts tag name strings or objects with name and status. This operation is append-only; existing tags will be preserved, and only new tags from this array will be added.
    - union
      - string
      - object
        - `name` string, required
        - `status` 'active' | 'inactive', required
  - `update_existing` boolean: If a contact already exists, update them instead of returning a conflict error. When `true` and a matching contact is found (by email or phone), the existing contact is updated with the provided channel data. Defaults to `false`.

## Response `200`

- object: An instance of a contact.
  - `audience_id` string: The unique ID for the audience.
  - `created_at` string, date-time: The date that the contact was created.
  - `email_channel` object
    - `effective_subscription_status` object: A computation performed by the Mailchimp platform, triggered whenever any of its inputs change. Some inputs are controlled by API users, while others are tracked internally by the platform. Computation is based on: audience opt-in configuration (single vs. double opt-in), marketing consent status, and deliverability status (an internal state for a contact, maintained by Mailchimp for a specific marketing channel instance). This new API field is distinct from how contacts are displayed in the UI. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values.
      - `value` 'subscribed' | 'unsubscribed' | 'nonsubscribed' | 'pending'
    - `email` string: Email address
    - `hashed_email` string: MD5 hash of the email address
    - `marketing_consent` object: A contact's current consent status for email marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values.
      - `source` object: The source from which the parent's entity was created.
        - `name` string: The name of the entity's source
      - `status` 'consented' | 'denied' | 'confirmed' | 'unknown'
      - `captured_at` string, date-time: The ISO 8601 timestamp when the email marketing consent state was recorded; accepted and returned only when status is `confirmed` or `consented`; defaults to the current time if omitted; ignored if older than an existing stored timestamp (staleness guard).
    - `source` object: The source from which the parent's entity was created.
      - `name` string: The name of the entity's source
  - `id` string: The unique ID for the contact.
  - `language` '' | 'en' | 'ar' | 'af' | 'be' | 'bg' | 'ca' | 'zh' | 'zh_CN' | 'hr' | 'cs' | 'da' | 'nl' | 'et' | 'fa' | 'fi' | 'fr' | 'fr_CA' | 'de' | 'el' | 'he' | 'hi' | 'hu' | 'is' | 'id' | 'ga' | 'it' | 'ja' | 'km' | 'ko' | 'lv' | 'lt' | 'mt' | 'ms' | 'mk' | 'no' | 'pl' | 'pt' | 'pt_PT' | 'ro' | 'ru' | 'sr' | 'sk' | 'sl' | 'es' | 'es_ES' | 'sw' | 'sv' | 'ta' | 'th' | 'tr' | 'uk' | 'vi': The contact's detected language. Empty string when no language has been detected or set.
  - `last_updated_at` string, date-time: The date that the contact was last updated.
  - `merge_fields` object, nullable: A dictionary of merge fields where the keys are the merge tags. See the [Merge Fields documentation](https://mailchimp.com/developer/marketing/docs/merge-fields/#structure) for more about the structure.
  - `sms_channel` object
    - `effective_subscription_status` object: A computation performed by the Mailchimp platform, triggered whenever any of its inputs change. Some inputs are controlled by API users, while others are tracked internally by the platform. Computation is based on: audience opt-in configuration (single vs. double opt-in), marketing consent status, and deliverability status (an internal state for a contact, maintained by Mailchimp for a specific marketing channel instance). This new API field is distinct from how contacts are displayed in the UI. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values.
      - `value` 'subscribed' | 'unsubscribed' | 'nonsubscribed' | 'pending'
    - `marketing_consent` object: A contact's current consent status for SMS marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values.
      - `source` object: The source from which the parent's entity was created.
        - `name` string: The name of the entity's source
      - `status` 'consented' | 'confirmed' | 'denied' | 'unknown': The contact's SMS marketing consent status. Use `confirmed` for double opt-in audiences, `consented` for single opt-in audiences. `denied` is accepted on PATCH/PUT only (not POST) and drives an API-initiated unsubscribe; it cannot be used when creating a new contact.
      - `captured_at` string, date-time: The timestamp when SMS marketing consent was captured (ISO 8601). Only accepted and returned when status is `confirmed`. The timestamp of the consent state change being recorded. Defaults to the current time if not provided. If the contact already has a consent timestamp on record that is equal to or newer than the supplied value, the supplied value is ignored (staleness guard); to update the consent timestamp supply a value strictly newer than the stored one.
    - `sms_phone` string: SMS Phone Number
    - `source` object: The source from which the parent's entity was created.
      - `name` string: The name of the entity's source
    - `hashed_sms_phone` string: SHA256 hash of the SMS phone number
  - `source` object: The source from which the parent's entity was created.
    - `name` string: The name of the entity's source
  - `status` 'active' | 'archived': The status of a contact.
  - `tags` string[]: The tags assigned to this contact.

## Other responses

- `default`: An error generated by the Mailchimp API.

---

[API](https://skmtc.dev/mailchimp/apis/mailchimp-api.md) - [All operations](https://skmtc.dev/mailchimp/apis/mailchimp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mailchimp/apis/mailchimp-api/revisions/53bf4b156855?raw)