---
title: "Customize signup form"
method: POST
path: "/3.0/lists/{list_id}/signup-forms"
tags: ["lists"]
---

# Customize signup form

`POST /3.0/lists/{list_id}/signup-forms`

## Request

- Base URL: `https://api.mailchimp.com`
- URL: `https://api.mailchimp.com/3.0/lists/{list_id}/signup-forms`
- 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/signup-forms/post.ts> (a function with typed inputs; its response is checked against the schema)

Customize a list's default signup form.

## Path parameters

- `list_id` string, required

## Request body

- object: List signup form.
  - `contents` object[]: The signup form body content.
    - `section` 'signup_message' | 'unsub_message' | 'signup_thank_you_title': The content section name.
    - `value` string: The content section text.
  - `header` object: Options for customizing your signup form header.
    - `image_align` 'none' | 'left' | 'center' | 'right': Image alignment.
    - `image_alt` string: Alt text for the image.
    - `image_border_color` string: Image border color.
    - `image_border_style` 'none' | 'solid' | 'dotted' | 'dashed' | 'double' | 'groove' | 'outset' | 'inset' | 'ridge': Image border style.
    - `image_border_width` string: Image border width.
    - `image_height` string: Image height, in pixels.
    - `image_link` string: The URL that the header image will link to.
    - `image_target` '_blank' | 'null': Image link target.
    - `image_url` string: Header image URL.
    - `image_width` string: Image width, in pixels.
    - `text` string: Header text.
  - `styles` object[]: An array of objects, each representing an element style for the signup form.
    - `options` object[]: A collection of options for a selector.
      - `property` string: A string that identifies the property.
      - `value` string: A string that identifies value of the property.
    - `selector` 'page_background' | 'page_header' | 'page_outer_wrapper' | 'body_background' | 'body_link_style' | 'forms_buttons' | 'forms_buttons_hovered' | 'forms_field_label' | 'forms_field_text' | 'forms_required' | 'forms_required_legend' | 'forms_help_text' | 'forms_errors' | 'monkey_rewards_badge': A string that identifies the element selector.

## Response `200`

- object: List signup form.
  - `_links` object[]: A list of link types and descriptions for the API schema documents.
    - `href` string: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
    - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD': The HTTP method that should be used when accessing the URL defined in 'href'.
    - `rel` string: As with an HTML 'rel' attribute, this describes the type of link.
    - `schema` string: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
    - `targetSchema` string: For GETs, this is a URL representing the schema that the response should conform to.
  - `contents` object[]: The signup form body content.
    - `section` 'signup_message' | 'unsub_message' | 'signup_thank_you_title': The content section name.
    - `value` string: The content section text.
  - `header` object: Options for customizing your signup form header.
    - `image_align` 'none' | 'left' | 'center' | 'right': Image alignment.
    - `image_alt` string: Alt text for the image.
    - `image_border_color` string: Image border color.
    - `image_border_style` 'none' | 'solid' | 'dotted' | 'dashed' | 'double' | 'groove' | 'outset' | 'inset' | 'ridge': Image border style.
    - `image_border_width` string: Image border width.
    - `image_height` string: Image height, in pixels.
    - `image_link` string: The URL that the header image will link to.
    - `image_target` '_blank' | 'null': Image link target.
    - `image_url` string: Header image URL.
    - `image_width` string: Image width, in pixels.
    - `text` string: Header text.
  - `list_id` string: The signup form's list id.
  - `signup_form_url` string: Signup form URL.
  - `styles` object[]: An array of objects, each representing an element style for the signup form.
    - `options` object[]: A collection of options for a selector.
      - `property` string: A string that identifies the property.
      - `value` string: A string that identifies value of the property.
    - `selector` 'page_background' | 'page_header' | 'page_outer_wrapper' | 'body_background' | 'body_link_style' | 'forms_buttons' | 'forms_buttons_hovered' | 'forms_field_label' | 'forms_field_text' | 'forms_required' | 'forms_required_legend' | 'forms_help_text' | 'forms_errors' | 'monkey_rewards_badge': A string that identifies the element selector.

## 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)