> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://mailchimp.com/developer/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mailchimp.com/developer/_mcp/server. # A collection of Audience Contacts GET https://api.mailchimp.com/3.0/audiences/{audience_id}/contacts Get a list of omni-channel contacts for a given audience. Reference: https://mailchimp.com/developer/marketing/api/audiences/get-audience-contact-list ## Authentication - `Authorization` header (bearer token, required) — Authorization using a Mailchimp API key (a.k.a. Bearer token) - `Authorization` header (bearer token, required) — Authorization using OAuth ## Request ### Path parameters - `audience_id` (string, required) — The unique ID for the audience. ### Query parameters - `fields` (list of string, optional) — A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation. - `exclude_fields` (list of string, optional) — A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation. - `count` (integer, optional, default: 10) — The number of records to return. Default value is 10. Maximum value is 1000 - `cursor` (string, optional) — Paginate through a collection of records by setting the `cursor` parameter to a `next_cursor` attribute returned by a previous request. Default value fetches the first "page" of results. - `created_before` (datetime, optional) — Restricts the response to contacts created at or before the specified time (inclusive). Uses ISO 8601 format: 2025-04-23T15:41:36+00:00. - `created_since` (datetime, optional) — Restricts the response to contacts created after the specified time (exclusive). Uses ISO 8601 format: 2025-04-23T15:41:36+00:00. - `updated_before` (datetime, optional) — Restricts the response to contacts updated at or before the specified time (inclusive). Uses ISO 8601 format: 2025-04-23T15:41:36+00:00. - `updated_since` (datetime, optional) — Restricts the response to contacts updated after the specified time (exclusive). Uses ISO 8601 format: 2025-04-23T15:41:36+00:00. - `sort_field` (enum, optional) — Specifies the field to sort the returned contacts by. - Allowed values: `created_at`, `updated_at` - `sort_dir` (enum, optional) — Determines the order direction for sorted results. - Allowed values: `ASC`, `DESC` ## Response ### 200 - `contacts` (list of AudiencesContact, optional) — An array of objects, each representing a contact record. - `next_cursor` (string, optional) — 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` (list of 30AudiencesAudienceIdContactsGetResponsesContentApplicationJsonSchemaLinksItems, optional) — A list of link types and descriptions for the API schema documents. ## Types ### AudiencesContact An instance of a contact. - `audience_id` (string, optional) — The unique ID for the audience. - `created_at` (datetime, optional) — The date that the contact was created. - `email_channel` (AudiencesContactEmailChannel, optional) - `id` (string, optional) — The unique ID for the contact. - `language` (enum, optional) — The contact's detected language. Empty string when no language has been detected or set. - Allowed values: ``, `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` - `last_updated_at` (datetime, optional) — The date that the contact was last updated. - `merge_fields` (map from string to AudiencesContactMergeFields, optional, 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` (AudiencesContactSmsChannel, optional) - `source` (AudiencesContactSource, optional) — The source from which the parent's entity was created. - `status` (enum, optional) — The status of a contact. - Allowed values: `active`, `archived` - `tags` (list of string, optional) — The tags assigned to this contact. ### 30AudiencesAudienceIdContactsGetResponsesContentApplicationJsonSchemaLinksItems This object represents a link from the resource where it is found to another resource or action that may be performed. - `href` (string, optional) — This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` (enum, optional) — The HTTP method that should be used when accessing the URL defined in 'href'. - Allowed values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `HEAD` - `rel` (string, optional) — As with an HTML 'rel' attribute, this describes the type of link. - `schema` (string, optional) — 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, optional) — For GETs, this is a URL representing the schema that the response should conform to. ### AudiencesContactEmailChannel - `effective_subscription_status` (AudiencesContactEmailChannelEffectiveSubscriptionStatus, optional) — 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. - `email` (string, optional) — Email address - `hashed_email` (string, optional) — MD5 hash of the email address - `marketing_consent` (AudiencesContactEmailChannelMarketingConsent, optional) — 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` (AudiencesContactEmailChannelSource, optional) — The source from which the parent's entity was created. ### AudiencesContactMergeFields This object's keys are merge tags (like FNAME). It's values are the values to be added to the merge field. ### AudiencesContactSmsChannel - `effective_subscription_status` (AudiencesContactSmsChannelEffectiveSubscriptionStatus, optional) — 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. - `marketing_consent` (AudiencesContactSmsChannelMarketingConsent, optional) — 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. - `sms_phone` (string, optional) — SMS Phone Number - `source` (AudiencesContactSmsChannelSource, optional) — The source from which the parent's entity was created. - `hashed_sms_phone` (string, optional) — SHA256 hash of the SMS phone number ### AudiencesContactSource The source from which the parent's entity was created. - `name` (string, optional) — The name of the entity's source ### AudiencesContactEmailChannelEffectiveSubscriptionStatus 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` (enum, optional) - Allowed values: `subscribed`, `unsubscribed`, `nonsubscribed`, `pending` ### AudiencesContactEmailChannelMarketingConsent 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` (AudiencesContactEmailChannelMarketingConsentSource, optional) — The source from which the parent's entity was created. - `status` (enum, optional) - Allowed values: `consented`, `denied`, `confirmed`, `unknown` - `captured_at` (datetime, optional) — 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). ### AudiencesContactEmailChannelSource The source from which the parent's entity was created. - `name` (string, optional) — The name of the entity's source ### AudiencesContactMergeFields0 - `addr1` (string, required) - `city` (string, required) - `state` (string, required) - `zip` (string, required) - `addr2` (string, optional) - `country` (string, optional) ### AudiencesContactSmsChannelEffectiveSubscriptionStatus 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` (enum, optional) - Allowed values: `subscribed`, `unsubscribed`, `nonsubscribed`, `pending` ### AudiencesContactSmsChannelMarketingConsent 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` (AudiencesContactSmsChannelMarketingConsentSource, optional) — The source from which the parent's entity was created. - `status` (enum, optional) — 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. - Allowed values: `consented`, `confirmed`, `denied`, `unknown` - `captured_at` (datetime, optional) — 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. ### AudiencesContactSmsChannelSource The source from which the parent's entity was created. - `name` (string, optional) — The name of the entity's source ### AudiencesContactEmailChannelMarketingConsentSource The source from which the parent's entity was created. - `name` (string, optional) — The name of the entity's source ### AudiencesContactSmsChannelMarketingConsentSource The source from which the parent's entity was created. - `name` (string, optional) — The name of the entity's source ## Examples **Response** ```json { "contacts": [ { "audience_id": "773280e405", "created_at": "2024-01-15T09:30:00Z", "email_channel": { "effective_subscription_status": { "value": "subscribed" }, "email": "example@freddiemail.com", "hashed_email": "9115d71ba28088047d342e3bcedacd0f", "marketing_consent": { "source": { "name": "string" }, "status": "consented", "captured_at": "2024-01-15T10:30:00Z" }, "source": { "name": "string" } }, "id": "7CCF816ADF6CE1B11AE09BB024A02B9B", "language": "en", "last_updated_at": "2024-01-15T09:30:00Z", "merge_fields": {}, "sms_channel": { "effective_subscription_status": { "value": "subscribed" }, "marketing_consent": { "source": { "name": "string" }, "status": "consented", "captured_at": "2024-01-15T10:30:00Z" }, "sms_phone": "+14045550102", "source": { "name": "string" }, "hashed_sms_phone": "0572084e1f8288816f02cdb7bd930c62400bc8aef510adfaa9eec2b995fa7609" }, "source": { "name": "string" }, "status": "active", "tags": [ "string" ] } ], "next_cursor": "string", "_links": [ { "href": "string", "method": "GET", "rel": "string", "schema": "string", "targetSchema": "string" } ] } ``` **SDK Code** ```python import requests url = "https://api.mailchimp.com/3.0/audiences/audience_id/contacts" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.mailchimp.com/3.0/audiences/audience_id/contacts'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.mailchimp.com/3.0/audiences/audience_id/contacts" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.mailchimp.com/3.0/audiences/audience_id/contacts") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.mailchimp.com/3.0/audiences/audience_id/contacts") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.mailchimp.com/3.0/audiences/audience_id/contacts', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.mailchimp.com/3.0/audiences/audience_id/contacts"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.mailchimp.com/3.0/audiences/audience_id/contacts")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```