Alternative Schemas
The basics
The Mailchimp Marketing API has several endpoints that are capable of accepting or returning multiple types of data. The API specifies alternative schemas for these endpoints, with additional parameters for requesting a particular type of data.
This documentation covers the Marketing API’s implementation of alternative schemas, including tables of the supported alternative schemas and their parameters. For further details on other aspects of these endpoints, consult the full API reference.
Structure
To specify alternate schemas, the Marketing API uses x-oneOf, a variation on the Open API Specification’s oneOf keyword. The value of x-oneOf is an array of objects, each representing a possible schema for the endpoint.
To choose among alternative schemas, you need to know the name of the schema and the field where you provide that name. The name of each schema is the x-value inside the schema object. The field name for a particular endpoint is specified as the propertyName of its x-discriminator object. Your code should be able to handle any type of data based on its x-value, or you should limit your API calls to the data types you want to handle.
For example, say you want to add a segment using a conditions parameter to determine who is included in the segment. This parameter’s specification indicates that it uses alternative schemas with the x-discriminator named condition_type. Find the x-value of the type of segment you want to create and pass that within conditions.
For some endpoints, specifying a particular schema affects not only the type of data returned, but also the other values you can pass in your request. Operators for comparing data are given in the op field, and valid comparisons are given in the value field.
Activity schemas
The Member Activity Feed endpoint can return a range of activity types. Although the x-discriminator for these activity schemas is activity_type, the relevant request parameter is activity_filters, which accepts an array of x-values instead of a single string. If you pass activity_filters, activity matching one of the provided types will be returned; if you omit it, any type of activity that matches your query will be returned.
Activity feed item representing opening an email.
Activity feed item representing having a link clicked by a contact.
Activity feed item representing an email to this contact bouncing.
Activity feed item representing this contact unsubscribing from a list.
Activity feed item representing having an email sent to the contact.
Activity feed item representing an individual reply in a conversation.
Activity feed item representing a note on the contact record.
Activity feed item indicating if a marketing permission was added or updated.
Activity feed item representing a time when a contact was sent a particular postcard.
Activity feed item to representing a contact signing up for the audience from a squatter page.
Activity feed item to representing a contact signing up for the contact through a website page.
Activity feed item to representing a contact signing up for the list via a landing page.
Activity feed item to representing a contact signing up for the list via a ecommerce store.
Activity feed item that represents a contact signing up for the audience via a generic some generic method (specifically, one we can't link to).
Activity feed item that represents an order.
Activity feed item that represents a generic event.
Represents when a contact completes and submits a survey
Segment condition schemas
A variety of endpoints accept or return segment condition data, from the Segments endpoints themselves to others like automation, list, and campaign endpoints. Because there are many ways to define a segment, there are many alternative schemas for segment conditions.
The x-discriminator for segment conditions is condition_type. The request parameter conditions accepts an array of objects that indicate the desired segment condition (field), operator, value, and optional extra information. Multiple segment conditions can be combined like so:
Multiple segment conditions
{
"name": "Gmail users who subscribed in 2021 or later",
"options": {
"match": "all",
"conditions": [
{
"field": "timestamp_opt",
"op": "greater",
"value": "date",
"extra": "2021-01-01"
},
{
"field": "EMAIL",
"op": "contains",
"value": "gmail.com"
}
]
}
}Segment by interaction with a specific campaign.
Segment by interaction with an Automation workflow.
Segment by poll activity.
Segment by interaction with a campaign via Conversations.
Segment by a specific date field.
Segment by use of a particular email client.
Segment by language.
Segment by member rating.
Segment by signup source.
Segment by interaction with a SurveyMonkey survey.
Segment by VIP status.
Segment by an interest group merge field.
Segment by purchases in specific items or categories.
Segment by average spent total, number of orders, total number of products purchased, or average number of products per order.
Segment by whether someone has purchased anything.
Segment by amount spent on a single order or across all orders.
Segment by purchases from a specific store.
Segment by Goal activity.
Segment by most recent interaction with a website.
Segment by similar subscribers.
Segment by a given static segment.
Segment by a specific country or US state.
Segment by a specific geographic region.
Segment by a specific US ZIP code.
Segment members whose location information is unknown.
Segment by a specific US ZIP code.
Segment by age ranges in Social Profiles data.
Segment by listed gender in Social Profiles data.
Segment by influence rating in Social Profiles data.
Segment by social network in Social Profiles data.
Segment by social network in Social Profiles data.
Segment by an address-type merge field.
Segment by an address-type merge field within a given distance.
Segment by a contact's birthday.
Segment by a given date merge field.
Segment by a given dropdown or radio button merge field.
Segment by a given text or number merge field.
Segment by email address.
Segment by predicted gender.
Segment by predicted age.
Segment by when people subscribed.