Skip to navigation
API Referencesegments

Add Segment

Create an advanced segment from a segment definition. The account's plan must include advanced segmentation. If it does not, the API returns a 403 error.

Authentication

AuthorizationBearer

Authorization using a Mailchimp API key (a.k.a. Bearer token)

OR
AuthorizationBearer
Authorization using OAuth

Request

The advanced segment to create.
definitionobjectRequired

A node in a segment definition. A node is a group or a condition. A group contains the match property and combines the nodes in its conditions array. A condition contains the field property and tests one contact attribute. A node cannot contain both match and field. The root node of a definition is always a group. In a request, the root group must contain match and conditions. This schema shows the properties of both node types together. Limits: A definition can contain a maximum of 100 conditions, including the conditions in filters. A definition can contain a maximum of 2 levels of groups. The root group is level 1. The Mailchimp segment builder uses the same group limit. If a definition is more than a limit, the API returns a 400 error. In this API version, Mailchimp does not change or remove existing fields, but Mailchimp can add new fields. Make sure that your client ignores fields that it does not know.

list_idstringRequired
The unique ID of the list that contains the segment.
namestringRequired
The name of the segment.

Response

created_atdatetimeOptionalRead-only
The date and time when Mailchimp created the segment, in ISO 8601 format.
definitionmap from strings to anyOptional

The segment definition. Read-only segments do not have a definition, so the response does not include this property for them. It contains the match and conditions that you sent, the current schema_version, and the contacts object. In the contacts object, each entry selects exactly one subscription status. The request body of Add Segment shows all properties of a definition.

idstringOptionalRead-onlyformat: "uuid"
The unique ID of the segment. Do not parse or change this value. Use it exactly as you received it.
list_idstringOptionalRead-only
The unique ID of the list that contains the segment.
read_onlybooleanOptionalRead-only

If true, you can read, count, and snapshot the segment, but you cannot update or delete it. Segments that other Mailchimp tools made, for example Google Analytics segments, are read-only. A read-only segment does not have a definition.

namestringOptional
The name of the segment.