---
title: "A collection of Audience Contacts"
method: GET
path: "/3.0/audiences/{audience_id}/contacts"
tags: ["audiences"]
---

# A collection of Audience Contacts

`GET /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/get.ts> (a function with typed inputs; its response is checked against the schema)

Get a list of omni-channel contacts for a given audience.

## Path parameters

- `audience_id` string, required

## Query parameters

- `fields` string[]
- `exclude_fields` string[]
- `count` integer
- `cursor` string
- `created_before` string, date-time
- `created_since` string, date-time
- `updated_before` string, date-time
- `updated_since` string, date-time
- `sort_field` 'created_at' | 'updated_at'
- `sort_dir` 'ASC' | 'DESC'

## Response `200`

- object: An array of objects, each representing a contact record.
  - `contacts` object[]: An array of objects, each representing a contact record.
    - `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.
  - `next_cursor` string: A cursor pointing to the last item on this page of the collection. Paginate through a collection of records by setting the `cursor` parameter on a subsequent request to this value.
  - `_links` object[]: A list of link types and descriptions for the API schema documents.
    - `href` string: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
    - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD': The HTTP method that should be used when accessing the URL defined in 'href'.
    - `rel` string: As with an HTML 'rel' attribute, this describes the type of link.
    - `schema` string: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
    - `targetSchema` string: For GETs, this is a URL representing the schema that the response should conform to.

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