---
title: "Create survey"
method: POST
path: "/3.0/lists/{list_id}/surveys"
tags: ["lists"]
---

# Create survey

`POST /3.0/lists/{list_id}/surveys`

## Request

- Base URL: `https://api.mailchimp.com`
- URL: `https://api.mailchimp.com/3.0/lists/{list_id}/surveys`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://login.mailchimp.com/oauth2/authorize`
    - Token URL: `https://login.mailchimp.com/oauth2/token`
- TypeScript: <https://skmtc.dev/mailchimp/apis/mailchimp-api/docs/3.0/lists/:list_id/surveys/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a draft survey for an audience.

## Path parameters

- `list_id` string, required

## Request body

- object: Create a draft survey for an audience.
  - `title` string: The title of the survey.
  - `sections` object[]: Initial survey sections.
    - `id` string: The section ID. On PATCH, include to update an existing section; omit to add a new section.
    - `type` 'introduction' | 'context' | 'question', required: The section type.
    - `text` string: Rich text content for introduction or context sections.
    - `options` object: Additional section options.
    - `question` object: A survey question. On PATCH, include the question id to update it. Omitting question id creates a new question; it does not delete an existing one. To delete a question, omit its section from the sections array.
      - `id` string: The question ID. On PATCH, include to update an existing question; omit to add a new question.
      - `query` string, required: The question text.
      - `type` 'pickOne' | 'pickMany' | 'range' | 'text' | 'email' | 'contactInformation' | 'dropdown', required: The response type of the survey question.
      - `is_required` boolean: Whether this question is required.
      - `has_other` boolean: Whether this question has an 'other' option.
      - `other_label` string: Label for the 'other' option.
      - `range_low_label` string: Label for the low end of a range question.
      - `range_high_label` string: Label for the high end of a range question.
      - `range_low_value` integer: Low value for a range question.
      - `range_high_value` integer: High value for a range question.
      - `range_presentation` string: How a range question is presented.
      - `placeholder_label` string: Placeholder text for text or email questions.
      - `subscribe_checkbox_enabled` boolean: Whether the subscribe checkbox is enabled.
      - `subscribe_checkbox_label` string: Label for the subscribe checkbox.
      - `should_auto_tag` boolean: Whether responses should automatically apply tags.
      - `options` object[]: Answer options for pickOne, pickMany, or dropdown questions.
        - `label` string, required
        - `value` string, required
      - `merge_field` object: Merge field mapping for contact information questions.

## Response `200`

Survey created.

## Other responses

- `default`: An error generated by the Mailchimp API.

---

[API](https://skmtc.dev/mailchimp/apis/mailchimp-api.md) - [All operations](https://skmtc.dev/mailchimp/apis/mailchimp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mailchimp/apis/mailchimp-api/revisions/53bf4b156855?raw)