Interest Categories
Manage interest categories for a specific list. Interest categories organize interests, which are used to group subscribers based on their preferences. These correspond to ‘group titles’ in the Mailchimp application. Learn more about groups in Mailchimp .
Available methods
Create a new interest category
POST /lists/{list_id}/interest-categories
Create a new interest category.
Path parameters
list_id
The unique id for the list.
Request body parameters
title
Type: String
Title: Name
Read only: false
The text description of this category. This field appears on signup forms and is often phrased as a question.
display_order
Type: Integer
Title: Display Order
Read only: false
The order that the categories are displayed in the list. Lower numbers display first.
type
Type: String
Title: Display Type
Read only: false
Determines how this category’s interests appear on signup forms.
Possible Values:
checkboxes
dropdown
radio
hidden
Response body parameters
list_id
Type: String
Title: List ID
Read only: true
The unique list id for the category.
id
Type: String
Title: Category ID
Read only: true
The id for the interest category.
title
Type: String
Title: Name
Read only: false
The text description of this category. This field appears on signup forms and is often phrased as a question.
display_order
Type: Integer
Title: Display Order
Read only: false
The order that the categories are displayed in the list. Lower numbers display first.
type
Type: String
Title: Display Type
Read only: false
Determines how this category’s interests appear on signup forms.
Possible Values:
checkboxes
dropdown
radio
hidden
_links
Type: Array
Title: Links
Read only: true
A list of link types and descriptions for the API schema documents.
Show properties
rel
Type: String
Title: Rel
Read only: true
As with an HTML ‘rel’ attribute, this describes the type of link.
href
Type: String
Title: Href
Read only: true
This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
method
Type: String
Title: Method
Read only: true
The HTTP method that should be used when accessing the URL defined in ‘href’.
Possible Values:
GET
POST
PUT
PATCH
DELETE
OPTIONS
HEAD
targetSchema
Type: String
Title: Target Schema
Read only: true
For GETs, this is a URL representing the schema that the response should conform to.
schema
Type: String
Title: Schema
Read only: true
For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
Example request
curl --request POST \
--url 'https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories' \
--user 'anystring:apikey' \
--header 'content-type: application/json' \
--data '{"title":"Favorite Freddie Joke","type":"checkboxes"}' \
--include
Example response
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8
Content-Length: 1409
Vary: Accept-Encoding
X-Request-Id: 790ee453-2f90-4257-a7bb-38fd680bc42e
Link: <https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json>; rel="describedBy"
Date: Wed, 16 Sep 2015 18:34:17 GMT
Connection: keep-alive
{
"list_id": "57afe96172",
"id": "64cec7560f",
"title": "Favorite Freddie Joke",
"display_order": 2,
"type": "checkboxes",
"_links": [
{
"rel": "self",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories/64cec7560f",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json"
},
{
"rel": "parent",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/InterestCategories.json"
},
{
"rel": "update",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories/64cec7560f",
"method": "PATCH",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json",
"schema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json"
},
{
"rel": "delete",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories/64cec7560f",
"method": "DELETE"
},
{
"rel": "interests",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories/64cec7560f/interests",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Interests/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/Interests.json"
}
]
}
Error response
type
Type: String
Title: Problem Type
Read only: false
An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
title
Type: String
Title: Error Title
Read only: false
A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
status
Type: Integer
Title: HTTP Status Code
Read only: false
The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
detail
Type: String
Title: Error Message
Read only: false
A human-readable explanation specific to this occurrence of the problem. Learn more about errors .
instance
Type: String
Title: Instance ID
Read only: false
A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
Get information about a list's interest categories
GET /lists/{list_id}/interest-categories
Get information about a list’s interest categories.
Path parameters
list_id
The unique id for the list.
Query string parameters
fields
Type: Array
Title: Fields
Read only: false
A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
exclude_fields
Type: Array
Title: Exclude Fields
Read only: false
A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.
count
Type: Integer
Title: Count
Read only: true
The number of records to return. Default value is 10 .
offset
Type: Integer
Title: Offset
Read only: false
The number of records from a collection to skip. Iterating over large collections with this parameter can be slow. Default value is 0 .
type
Type: String
Title: Interest Group Type
Read only: false
Restrict results a type of interest group
Response body parameters
list_id
Type: String
Title: List ID
Read only: true
The ID for the list that this category belongs to.
categories
Type: Array
Title: Interest Categories
Read only: false
This array contains individual interest categories.
Show properties
list_id
Type: String
Title: List ID
Read only: true
The unique list id for the category.
id
Type: String
Title: Category ID
Read only: true
The id for the interest category.
title
Type: String
Title: Name
Read only: false
The text description of this category. This field appears on signup forms and is often phrased as a question.
display_order
Type: Integer
Title: Display Order
Read only: false
The order that the categories are displayed in the list. Lower numbers display first.
type
Type: String
Title: Display Type
Read only: false
Determines how this category’s interests appear on signup forms.
Possible Values:
checkboxes
dropdown
radio
hidden
_links
Type: Array
Title: Links
Read only: true
A list of link types and descriptions for the API schema documents.
Show properties
rel
Type: String
Title: Rel
Read only: true
As with an HTML ‘rel’ attribute, this describes the type of link.
href
Type: String
Title: Href
Read only: true
This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
method
Type: String
Title: Method
Read only: true
The HTTP method that should be used when accessing the URL defined in ‘href’.
Possible Values:
GET
POST
PUT
PATCH
DELETE
OPTIONS
HEAD
targetSchema
Type: String
Title: Target Schema
Read only: true
For GETs, this is a URL representing the schema that the response should conform to.
schema
Type: String
Title: Schema
Read only: true
For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
total_items
Type: Integer
Title: Item Count
Read only: false
The total number of items matching the query regardless of pagination.
_links
Type: Array
Title: Links
Read only: true
A list of link types and descriptions for the API schema documents.
Show properties
rel
Type: String
Title: Rel
Read only: true
As with an HTML ‘rel’ attribute, this describes the type of link.
href
Type: String
Title: Href
Read only: true
This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
method
Type: String
Title: Method
Read only: true
The HTTP method that should be used when accessing the URL defined in ‘href’.
Possible Values:
GET
POST
PUT
PATCH
DELETE
OPTIONS
HEAD
targetSchema
Type: String
Title: Target Schema
Read only: true
For GETs, this is a URL representing the schema that the response should conform to.
schema
Type: String
Title: Schema
Read only: true
For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
Example request
curl --request GET \
--url 'https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories' \
--user 'anystring:apikey' \
--include
Example response
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8
Content-Length: 2250
Vary: Accept-Encoding
X-Request-Id: cc3b5f2b-a26b-4077-84ac-259299d2c234
Link: <https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Collection.json>; rel="describedBy"
Date: Wed, 16 Sep 2015 18:03:46 GMT
Connection: keep-alive
{
"list_id": "57afe96172",
"categories": [
{
"list_id": "57afe96172",
"id": "a1e9f4b7f6",
"title": "Favorite Freddie Joke",
"display_order": 0,
"type": "checkboxes",
"_links": [
{
"rel": "self",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories/a1e9f4b7f6",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json"
},
{
"rel": "parent",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/InterestCategories.json"
},
{
"rel": "update",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories/a1e9f4b7f6",
"method": "PATCH",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json",
"schema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json"
},
{
"rel": "delete",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories/a1e9f4b7f6",
"method": "DELETE"
},
{
"rel": "interests",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories/a1e9f4b7f6/interests",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Interests/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/Interests.json"
}
]
}
],
"_links": [
{
"rel": "self",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/InterestCategories.json"
},
{
"rel": "parent",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Instance.json"
},
{
"rel": "create",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories",
"method": "POST",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json",
"schema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json"
}
],
"total_items": 1
}
Error response
type
Type: String
Title: Problem Type
Read only: false
An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
title
Type: String
Title: Error Title
Read only: false
A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
status
Type: Integer
Title: HTTP Status Code
Read only: false
The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
detail
Type: String
Title: Error Message
Read only: false
A human-readable explanation specific to this occurrence of the problem. Learn more about errors .
instance
Type: String
Title: Instance ID
Read only: false
A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
Get information about a specific interest category
GET /lists/{list_id}/interest-categories/{interest_category_id}
Get information about a specific interest category.
Path parameters
list_id
The unique id for the list.
interest_category_id
A unique id/comma-separated list of ids for the interest category.
Query string parameters
fields
Type: Array
Title: Fields
Read only: false
A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
exclude_fields
Type: Array
Title: Exclude Fields
Read only: false
A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.
Response body parameters
list_id
Type: String
Title: List ID
Read only: true
The unique list id for the category.
id
Type: String
Title: Category ID
Read only: true
The id for the interest category.
title
Type: String
Title: Name
Read only: false
The text description of this category. This field appears on signup forms and is often phrased as a question.
display_order
Type: Integer
Title: Display Order
Read only: false
The order that the categories are displayed in the list. Lower numbers display first.
type
Type: String
Title: Display Type
Read only: false
Determines how this category’s interests appear on signup forms.
Possible Values:
checkboxes
dropdown
radio
hidden
_links
Type: Array
Title: Links
Read only: true
A list of link types and descriptions for the API schema documents.
Show properties
rel
Type: String
Title: Rel
Read only: true
As with an HTML ‘rel’ attribute, this describes the type of link.
href
Type: String
Title: Href
Read only: true
This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
method
Type: String
Title: Method
Read only: true
The HTTP method that should be used when accessing the URL defined in ‘href’.
Possible Values:
GET
POST
PUT
PATCH
DELETE
OPTIONS
HEAD
targetSchema
Type: String
Title: Target Schema
Read only: true
For GETs, this is a URL representing the schema that the response should conform to.
schema
Type: String
Title: Schema
Read only: true
For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
Example request
curl --request GET \
--url 'https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories/a1e9f4b7f6' \
--user 'anystring:apikey' \
--include
Example response
HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8
Content-Length: 1404
Vary: Accept-Encoding
X-Request-Id: 735a64d7-6f48-41db-95d5-fd821a15b745
Link: <https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json>; rel="describedBy"
Date: Wed, 16 Sep 2015 18:05:38 GMT
Connection: keep-alive
{
"list_id": "57afe96172",
"id": "a1e9f4b7f6",
"title": "Favorite Freddie Joke",
"display_order": 0,
"type": "checkboxes",
"_links": [
{
"rel": "self",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories/a1e9f4b7f6",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json"
},
{
"rel": "parent",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/InterestCategories.json"
},
{
"rel": "update",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories/a1e9f4b7f6",
"method": "PATCH",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json",
"schema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json"
},
{
"rel": "delete",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories/a1e9f4b7f6",
"method": "DELETE"
},
{
"rel": "interests",
"href": "https://usX.api.mailchimp.com/3.0/lists/57afe96172/interest-categories/a1e9f4b7f6/interests",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Interests/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/Interests.json"
}
]
}
Error response
type
Type: String
Title: Problem Type
Read only: false
An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
title
Type: String
Title: Error Title
Read only: false
A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
status
Type: Integer
Title: HTTP Status Code
Read only: false
The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
detail
Type: String
Title: Error Message
Read only: false
A human-readable explanation specific to this occurrence of the problem. Learn more about errors .
instance
Type: String
Title: Instance ID
Read only: false
A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
Update a specific interest category
PATCH /lists/{list_id}/interest-categories/{interest_category_id}
Update a specific interest category.
Path parameters
list_id
The unique id for the list.
interest_category_id
A unique id/comma-separated list of ids for the interest category.
Request body parameters
title
Type: String
Title: Name
Read only: false
The text description of this category. This field appears on signup forms and is often phrased as a question.
display_order
Type: Integer
Title: Display Order
Read only: false
The order that the categories are displayed in the list. Lower numbers display first.
type
Type: String
Title: Display Type
Read only: false
Determines how this category’s interests appear on signup forms.
Possible Values:
checkboxes
dropdown
radio
hidden
Response body parameters
list_id
Type: String
Title: List ID
Read only: true
The unique list id for the category.
id
Type: String
Title: Category ID
Read only: true
The id for the interest category.
title
Type: String
Title: Name
Read only: false
The text description of this category. This field appears on signup forms and is often phrased as a question.
display_order
Type: Integer
Title: Display Order
Read only: false
The order that the categories are displayed in the list. Lower numbers display first.
type
Type: String
Title: Display Type
Read only: false
Determines how this category’s interests appear on signup forms.
Possible Values:
checkboxes
dropdown
radio
hidden
_links
Type: Array
Title: Links
Read only: true
A list of link types and descriptions for the API schema documents.
Show properties
rel
Type: String
Title: Rel
Read only: true
As with an HTML ‘rel’ attribute, this describes the type of link.
href
Type: String
Title: Href
Read only: true
This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
method
Type: String
Title: Method
Read only: true
The HTTP method that should be used when accessing the URL defined in ‘href’.
Possible Values:
GET
POST
PUT
PATCH
DELETE
OPTIONS
HEAD
targetSchema
Type: String
Title: Target Schema
Read only: true
For GETs, this is a URL representing the schema that the response should conform to.
schema
Type: String
Title: Schema
Read only: true
For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
Example request
curl --request PATCH \
--url 'https://usX.api.mailchimp.com/3.0/lists/205d96e6b4/interest-categories/f7c1aa50d1' \
--user 'anystring:apikey' \
--header 'content-type: application/json' \
--data '{"title":"Joke Subjects", "display_order":1, "type":"checkboxes"}' \
--include
Example response
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 12 May 2016 14:45:53 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1396
Connection: keep-alive
Vary: Accept-Encoding
X-Request-Id: 5195cd10-490e-4bc3-8f12-208dbfc13151
Link: <https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json>; rel="describedBy"
{
"list_id": "205d96e6b4",
"id": "f7c1aa50d1",
"title": "Joke Subjects",
"display_order": 1,
"type": "checkboxes",
"_links": [
{
"rel": "self",
"href": "https://usX.api.mailchimp.com/3.0/lists/205d96e6b4/interest-categories/f7c1aa50d1",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json"
},
{
"rel": "parent",
"href": "https://usX.api.mailchimp.com/3.0/lists/205d96e6b4/interest-categories",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/InterestCategories.json"
},
{
"rel": "update",
"href": "https://usX.api.mailchimp.com/3.0/lists/205d96e6b4/interest-categories/f7c1aa50d1",
"method": "PATCH",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json",
"schema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Instance.json"
},
{
"rel": "delete",
"href": "https://usX.api.mailchimp.com/3.0/lists/205d96e6b4/interest-categories/f7c1aa50d1",
"method": "DELETE"
},
{
"rel": "interests",
"href": "https://usX.api.mailchimp.com/3.0/lists/205d96e6b4/interest-categories/f7c1aa50d1/interests",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Interests/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/Interests.json"
}
]
}
Error response
type
Type: String
Title: Problem Type
Read only: false
An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
title
Type: String
Title: Error Title
Read only: false
A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
status
Type: Integer
Title: HTTP Status Code
Read only: false
The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
detail
Type: String
Title: Error Message
Read only: false
A human-readable explanation specific to this occurrence of the problem. Learn more about errors .
instance
Type: String
Title: Instance ID
Read only: false
A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
Delete a specific interest category
DELETE /lists/{list_id}/interest-categories/{interest_category_id}
Delete a specific interest category.
Path parameters
list_id
The unique id for the list.
interest_category_id
A unique id/comma-separated list of ids for the interest category.
Example request
curl --request DELETE \
--url 'https://usX.api.mailchimp.com/3.0/lists/205d96e6b4/interest-categories/f7c1aa50d1' \
--user 'anystring:apikey' \
--include
Example response
HTTP/1.1 204 No Content
Server: nginx
Date: Thu, 12 May 2016 14:46:33 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: keep-alive
X-Request-Id: 0e63df01-5711-4c56-aa1e-9085a30a54b5
Error response
type
Type: String
Title: Problem Type
Read only: false
An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
title
Type: String
Title: Error Title
Read only: false
A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
status
Type: Integer
Title: HTTP Status Code
Read only: false
The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
detail
Type: String
Title: Error Message
Read only: false
A human-readable explanation specific to this occurrence of the problem. Learn more about errors .
instance
Type: String
Title: Instance ID
Read only: false
A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.