MailChimp API v3.0 is now live!
Prior versions will no longer be supported after 2016, so all API users should begin transitioning to v3.0.
Check out the API v3.0 Documentation for more details.
« Back to Documentation Overview

/lists/merge-vars.format - v2.0

This method is available for API Keys belonging to users with the following roles: manager, admin, owner
Take a look at this article to learn more about the different access levels for a MailChimp account.

merge-vars(string apikey, array id)
When using a wrapper or XML-RPC, this is generally the parameter order. When building JSON objects or serialized HTTP requests parameter order does not matter

Get the list of merge tags for a given list, including their name, tag, and required setting

apikey string a valid API Key for your user account. Get by visiting your API dashboard
id array the list ids to retrieve merge vars for. Get by calling lists/list() - max of 100
Return Value
struct of data and success/error counts
int success_count the number of subscribers successfully found on the list
int error_count the number of subscribers who were not found on the list
array data of structs for the merge tags on each list
string id the list id
string name the list name
array merge_vars of structs for each merge var
string name Name of the merge field
bool req Denotes whether the field is required (true) or not (false)
string field_type The "data type" of this merge var. One of the options accepted by field_type in lists/merge-var-add
bool public Whether or not this field is visible to list subscribers
bool show Whether the list owner has this field displayed on their list dashboard
string order The order the list owner has set this field to display in
string default The default value the list owner has set for this field
string helptext The helptext for this field
string size The width of the field to be used
string tag The merge tag that's used for forms and lists/subscribe() and listUpdateMember()
array choices For radio and dropdown field types, an array of the options available
int id an unchanging id for the merge var
array errors of error structs
string id the passed list id that failed
int code the resulting error code
string msg the resulting error message

Example Request JSON

{"apikey": "example apikey", "id":["..."]}

Example Response JSON

{"success_count":42,"error_count":42,"data":[{"id": "example id", "name": "example name", "merge_vars":[{"name": "example name", "req":true,"field_type": "example field_type", "public":true,"show":true,"order": "example order", "default": "example default", "helptext": "example helptext", "size": "example size", "tag": "example tag", "choices":["..."],"id":42}]}],"errors":[{"id": "example id", "code":42,"msg": "example msg"}]}

Example Error Response JSON

{"status": "error", "code":-99,"name": "Unknown_Exception", "error": "An unknown error occurred processing your request. Please try again later."}
Method-specific Errors
API-wide Errors
Invalid_ApiKey The API Key provided is invalid, revoked, you're in the wrong data center, or whatever the error message says.
User_Disabled The account being accessed has been disabled - more detail in the actual message returned.
User_InvalidRole The account being accessed does not have permission to access the API method
Too_Many_Connections You didn't pay attention to this
User_UnderMaintenance The account being access is currently under temporary maintenance
User_InvalidAction The account being accessed has not been approved for some action - more detail in the actual message returned.
ValidationError The parameters passed to the API call are invalid or not provided when required