Mailchimp Merge API

swagger: '2.0'
info:
  version: 3.0.55
  title: Mailchimp Marketing Abuse Merge API
  contact:
    name: Mailchimp API Support
    email: apihelp@mailchimp.com
  x-permalink: https://github.com/mailchimp/mailchimp-client-lib-codegen/blob/main/spec/marketing.json
  description: '

    The Mailchimp Marketing API provides programmatic access to Mailchimp data

    and functionality, allowing developers to build custom features to do

    things like sync email activity and campaign analytics with their

    database, manage audiences and campaigns, and more.'
host: server.api.mailchimp.com
basePath: /3.0
schemes:
- https
consumes:
- application/json
produces:
- application/json
- application/problem+json
security:
- basicAuth: []
tags:
- name: Merge
paths:
  /lists/{list_id}/merge-fields:
    get:
      summary: Mailchimp List Merge Fields
      description: Get a list of all merge fields for an audience.
      operationId: getListsIdMergeFields
      parameters:
      - name: list_id
        x-title: List ID
        in: path
        description: The unique ID for the list.
        required: true
        type: string
        example: '500123'
      - name: fields
        x-title: Fields
        in: query
        description: A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
        required: false
        type: array
        collectionFormat: csv
        items:
          type: string
        example: example_value
      - name: exclude_fields
        x-title: Exclude Fields
        in: query
        description: A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.
        required: false
        type: array
        collectionFormat: csv
        items:
          type: string
        example: example_value
      - name: count
        x-title: Count
        in: query
        description: The number of records to return. Default value is 10. Maximum value is 1000
        required: false
        default: 10
        maximum: 1000
        type: integer
        example: example_value
      - name: offset
        x-title: Offset
        in: query
        description: Used for [pagination](https://mailchimp.com/developer/marketing/docs/methods-parameters/#pagination), this it the number of records from a collection to skip. Default value is 0.
        required: false
        default: 0
        type: integer
        example: example_value
      - name: type
        x-title: Merge Type
        in: query
        required: false
        description: The merge field type.
        type: string
        example: example_value
      - name: required
        x-title: Required
        in: query
        required: false
        description: Whether it's a required merge field.
        type: boolean
        example: example_value
      responses:
        '200':
          description: ''
          schema:
            type: object
            title: Collection of Merge Fields
            description: The [merge fields](https://mailchimp.com/developer/marketing/docs/merge-fields/) for an audience.
            properties:
              merge_fields:
                type: array
                items:
                  type: object
                  title: Merge Field
                  description: A [merge field](https://mailchimp.com/developer/marketing/docs/merge-fields/) for an audience.
                  properties:
                    merge_id:
                      type: integer
                      title: Merge Field ID
                      description: An unchanging id for the merge field.
                      readOnly: true
                    tag:
                      type: string
                      title: Merge Tag
                      description: The merge tag used for Mailchimp campaigns and [adding contact information](https://mailchimp.com/developer/marketing/docs/merge-fields/#add-merge-data-to-contacts).
                    name:
                      type: string
                      title: Merge Field Name
                      description: The name of the merge field (audience field).
                    type:
                      type: string
                      title: Merge Field Type
                      description: The [type](https://mailchimp.com/developer/marketing/docs/merge-fields/#structure) for the merge field.
                      enum:
                      - text
                      - number
                      - address
                      - phone
                      - date
                      - url
                      - imageurl
                      - radio
                      - dropdown
                      - birthday
                      - zip
                      readOnly: true
                    required:
                      type: boolean
                      title: Required
                      description: The boolean value if the merge field is required.
                    default_value:
                      type: string
                      title: Default Value
                      description: The default value for the merge field if `null`.
                    public:
                      type: boolean
                      title: Merge Field Public Status
                      description: Whether the merge field is displayed on the signup form.
                    display_order:
                      type: integer
                      title: Display Order
                      description: The order that the merge field displays on the list signup form.
                    options:
                      type: object
                      title: Merge Field Options
                      description: Extra options for some merge field types.
                      properties:
                        default_country:
                          type: integer
                          title: Default Country
                          description: In an address field, the default country code if none supplied.
                        phone_format:
                          type: string
                          title: Phone Type
                          description: 'In a phone field, the phone number type: US or International.'
                        date_format:
                          type: string
                          title: Date Type
                          description: In a date or birthday field, the format of the date.
                        choices:
                          type: array
                          title: Choices
                          description: In a radio or dropdown non-group field, the available options for contacts to pick from.
                          items:
                            type: string
                          example:
                          - First Choice
                          - Second Choice
                          - Third Choice
                        size:
                          type: integer
                          title: Text Field Size
                          description: In a text field, the default length of the text field.
                          readOnly: true
                    help_text:
                      type: string
                      title: Merge Field Help Text
                      description: Extra text to help the subscriber fill out the form.
                    list_id:
                      type: string
                      title: List ID
                      description: The ID that identifies this merge field's audience'.
                      readOnly: true
                    _links:
                      title: Links
                      description: A list of link types and descriptions for the API schema documents.
                      type: array
                      items:
                        type: object
                        title: Resource Link
                        description: This object represents a link from the resource where it is found to another resource or action that may be performed.
                        properties:
                          rel:
                            type: string
                            title: Rel
                            description: As with an HTML 'rel' attribute, this describes the type of link.
                            readOnly: true
                          href:
                            type: string
                            title: Href
                            description: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
                            readOnly: true
                          method:
                            type: string
                            title: Method
                            description: The HTTP method that should be used when accessing the URL defined in 'href'.
                            enum:
                            - GET
                            - POST
                            - PUT
                            - PATCH
                            - DELETE
                            - OPTIONS
                            - HEAD
                            readOnly: true
                          targetSchema:
                            type: string
                            title: Target Schema
                            description: For GETs, this is a URL representing the schema that the response should conform to.
                            readOnly: true
                          schema:
                            type: string
                            title: Schema
                            description: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
                            readOnly: true
                      readOnly: true
                title: Merge Fields
                description: An array of objects, each representing a merge field resource.
              list_id:
                type: string
                title: List ID
                description: The list id.
                readOnly: true
              total_items:
                type: integer
                title: Item Count
                description: The total number of items matching the query regardless of pagination.
                readOnly: true
              _links:
                title: Links
                description: A list of link types and descriptions for the API schema documents.
                type: array
                items:
                  type: object
                  title: Resource Link
                  description: This object represents a link from the resource where it is found to another resource or action that may be performed.
                  properties:
                    rel:
                      type: string
                      title: Rel
                      description: As with an HTML 'rel' attribute, this describes the type of link.
                      readOnly: true
                    href:
                      type: string
                      title: Href
                      description: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
                      readOnly: true
                    method:
                      type: string
                      title: Method
                      description: The HTTP method that should be used when accessing the URL defined in 'href'.
                      enum:
                      - GET
                      - POST
                      - PUT
                      - PATCH
                      - DELETE
                      - OPTIONS
                      - HEAD
                      readOnly: true
                    targetSchema:
                      type: string
                      title: Target Schema
                      description: For GETs, this is a URL representing the schema that the response should conform to.
                      readOnly: true
                    schema:
                      type: string
                      title: Schema
                      description: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
                      readOnly: true
                readOnly: true
        default:
          description: An error generated by the Mailchimp API.
          schema:
            type: object
            title: Problem Detail Document
            description: An error generated by the Mailchimp API. Conforms to IETF draft 'draft-nottingham-http-problem-06'.
            required:
            - type
            - title
            - status
            - detail
            - instance
            properties:
              type:
                type: string
                title: Problem Type
                description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                example: https://mailchimp.com/developer/marketing/docs/errors/
              title:
                type: string
                title: Error Title
                description: 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.
                example: Resource Not Found
              status:
                type: integer
                title: HTTP Status Code
                description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                example: 404
              detail:
                type: string
                title: Error Message
                description: A human-readable explanation specific to this occurrence of the problem. [Learn more about errors](/developer/guides/get-started-with-mailchimp-api-3/#Errors).
                example: The requested resource could not be found.
              instance:
                type: string
                title: Instance ID
                description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                example: 995c5cb0-3280-4a6e-808b-3b096d0bb219
      deprecated: false
      tags:
      - Merge
      x-custom-config:
        methodNameSnake: get_list_merge_fields
        methodNameCamel: getListMergeFields
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: Mailchimp Add Merge Field
      description: Add a new merge field for a specific audience.
      operationId: postListsIdMergeFields
      parameters:
      - name: list_id
        x-title: List ID
        in: path
        description: The unique ID for the list.
        required: true
        type: string
        example: '500123'
      - name: body
        in: body
        description: ''
        required: true
        schema:
          type: object
          title: Merge Field
          description: A [merge field](https://mailchimp.com/developer/marketing/docs/merge-fields/) for an audience.
          required:
          - name
          - type
          properties:
            tag:
              type: string
              title: Merge Tag
              description: The merge tag used for Mailchimp campaigns and [adding contact information](https://mailchimp.com/developer/marketing/docs/merge-fields/#add-merge-data-to-contacts).
            name:
              type: string
              title: Merge Field Name
              description: The name of the merge field (audience field).
            type:
              type: string
              title: Merge Field Type
              description: The [type](https://mailchimp.com/developer/marketing/docs/merge-fields/#structure) for the merge field.
              enum:
              - text
              - number
              - address
              - phone
              - date
              - url
              - imageurl
              - radio
              - dropdown
              - birthday
              - zip
            required:
              type: boolean
              title: Required
              description: Whether the merge field is required to import a contact.
            default_value:
              type: string
              title: Default Value
              description: The default value for the merge field if `null`.
            public:
              type: boolean
              title: Merge Field Public Status
              description: Whether the merge field is displayed on the signup form.
            display_order:
              type: integer
              title: Display Order
              description: The order that the merge field displays on the list signup form.
            options:
              type: object
              title: Merge Field Options
              description: Extra options for some merge field types.
              properties:
                default_country:
                  type: integer
                  title: Default Country
                  description: In an address field, the default country code if none supplied.
                  items:
                    type: string
                phone_format:
                  type: string
                  title: Phone Type
                  description: 'In a phone field, the phone number type: US or International.'
                date_format:
                  type: string
                  title: Date Type
                  description: In a date or birthday field, the format of the date.
                choices:
                  type: array
                  title: Choices
                  description: In a radio or dropdown non-group field, the available options for contacts to pick from.
                  items:
                    type: string
                  example:
                  - First Choice
                  - Second Choice
                  - Third Choice
                size:
                  type: integer
                  title: Text Field Size
                  description: In a text field, the default length of the text field.
            help_text:
              type: string
              title: Merge Field Help Text
              description: Extra text to help the subscriber fill out the form.
        example: example_value
      responses:
        '200':
          description: ''
          schema:
            type: object
            title: Merge Field
            description: A [merge field](https://mailchimp.com/developer/marketing/docs/merge-fields/) for an audience.
            properties:
              merge_id:
                type: integer
                title: Merge Field ID
                description: An unchanging id for the merge field.
                readOnly: true
              tag:
                type: string
                title: Merge Tag
                description: The merge tag used for Mailchimp campaigns and [adding contact information](https://mailchimp.com/developer/marketing/docs/merge-fields/#add-merge-data-to-contacts).
              name:
                type: string
                title: Merge Field Name
                description: The name of the merge field (audience field).
              type:
                type: string
                title: Merge Field Type
                description: The [type](https://mailchimp.com/developer/marketing/docs/merge-fields/#structure) for the merge field.
                enum:
                - text
                - number
                - address
                - phone
                - date
                - url
                - imageurl
                - radio
                - dropdown
                - birthday
                - zip
                readOnly: true
              required:
                type: boolean
                title: Required
                description: The boolean value if the merge field is required.
              default_value:
                type: string
                title: Default Value
                description: The default value for the merge field if `null`.
              public:
                type: boolean
                title: Merge Field Public Status
                description: Whether the merge field is displayed on the signup form.
              display_order:
                type: integer
                title: Display Order
                description: The order that the merge field displays on the list signup form.
              options:
                type: object
                title: Merge Field Options
                description: Extra options for some merge field types.
                properties:
                  default_country:
                    type: integer
                    title: Default Country
                    description: In an address field, the default country code if none supplied.
                  phone_format:
                    type: string
                    title: Phone Type
                    description: 'In a phone field, the phone number type: US or International.'
                  date_format:
                    type: string
                    title: Date Type
                    description: In a date or birthday field, the format of the date.
                  choices:
                    type: array
                    title: Choices
                    description: In a radio or dropdown non-group field, the available options for contacts to pick from.
                    items:
                      type: string
                    example:
                    - First Choice
                    - Second Choice
                    - Third Choice
                  size:
                    type: integer
                    title: Text Field Size
                    description: In a text field, the default length of the text field.
                    readOnly: true
              help_text:
                type: string
                title: Merge Field Help Text
                description: Extra text to help the subscriber fill out the form.
              list_id:
                type: string
                title: List ID
                description: The ID that identifies this merge field's audience'.
                readOnly: true
              _links:
                title: Links
                description: A list of link types and descriptions for the API schema documents.
                type: array
                items:
                  type: object
                  title: Resource Link
                  description: This object represents a link from the resource where it is found to another resource or action that may be performed.
                  properties:
                    rel:
                      type: string
                      title: Rel
                      description: As with an HTML 'rel' attribute, this describes the type of link.
                      readOnly: true
                    href:
                      type: string
                      title: Href
                      description: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
                      readOnly: true
                    method:
                      type: string
                      title: Method
                      description: The HTTP method that should be used when accessing the URL defined in 'href'.
                      enum:
                      - GET
                      - POST
                      - PUT
                      - PATCH
                      - DELETE
                      - OPTIONS
                      - HEAD
                      readOnly: true
                    targetSchema:
                      type: string
                      title: Target Schema
                      description: For GETs, this is a URL representing the schema that the response should conform to.
                      readOnly: true
                    schema:
                      type: string
                      title: Schema
                      description: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
                      readOnly: true
                readOnly: true
        default:
          description: An error generated by the Mailchimp API.
          schema:
            type: object
            title: Problem Detail Document
            description: An error generated by the Mailchimp API. Conforms to IETF draft 'draft-nottingham-http-problem-06'.
            required:
            - type
            - title
            - status
            - detail
            - instance
            properties:
              type:
                type: string
                title: Problem Type
                description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                example: https://mailchimp.com/developer/marketing/docs/errors/
              title:
                type: string
                title: Error Title
                description: 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.
                example: Resource Not Found
              status:
                type: integer
                title: HTTP Status Code
                description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                example: 404
              detail:
                type: string
                title: Error Message
                description: A human-readable explanation specific to this occurrence of the problem. [Learn more about errors](/developer/guides/get-started-with-mailchimp-api-3/#Errors).
                example: The requested resource could not be found.
              instance:
                type: string
                title: Instance ID
                description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                example: 995c5cb0-3280-4a6e-808b-3b096d0bb219
      deprecated: false
      tags:
      - Merge
      x-custom-config:
        methodNameSnake: add_list_merge_field
        methodNameCamel: addListMergeField
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /lists/{list_id}/merge-fields/{merge_id}:
    get:
      summary: Mailchimp Get Merge Field
      description: Get information about a specific merge field.
      operationId: getListsIdMergeFieldsId
      parameters:
      - name: list_id
        x-title: List ID
        in: path
        description: The unique ID for the list.
        required: true
        type: string
        example: '500123'
      - name: merge_id
        x-title: Merge ID
        description: The id for the merge field.
        in: path
        required: true
        type: string
        example: '500123'
      - name: exclude_fields
        x-title: Exclude Fields
        in: query
        description: A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.
        required: false
        type: array
        collectionFormat: csv
        items:
          type: string
        example: example_value
      - name: fields
        x-title: Fields
        in: query
        description: A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
        required: false
        type: array
        collectionFormat: csv
        items:
          type: string
        example: example_value
      responses:
        '200':
          description: ''
          schema:
            type: object
            title: Merge Field
            description: A [merge field](https://mailchimp.com/developer/marketing/docs/merge-fields/) for an audience.
            properties:
              merge_id:
                type: integer
                title: Merge Field ID
                description: An unchanging id for the merge field.
                readOnly: true
              tag:
                type: string
                title: Merge Tag
                description: The merge tag used for Mailchimp campaigns and [adding contact information](https://mailchimp.com/developer/marketing/docs/merge-fields/#add-merge-data-to-contacts).
              name:
                type: string
                title: Merge Field Name
                description: The name of the merge field (audience field).
              type:
                type: string
                title: Merge Field Type
                description: The [type](https://mailchimp.com/developer/marketing/docs/merge-fields/#structure) for the merge field.
                enum:
                - text
                - number
                - address
                - phone
                - date
                - url
                - imageurl
                - radio
                - dropdown
                - birthday
                - zip
                readOnly: true
              required:
                type: boolean
                title: Required
                description: The boolean value if the merge field is required.
              default_value:
                type: string
                title: Default Value
                description: The default value for the merge field if `null`.
              public:
                type: boolean
                title: Merge Field Public Status
                description: Whether the merge field is displayed on the signup form.
              display_order:
                type: integer
                title: Display Order
                description: The order that the merge field displays on the list signup form.
              options:
                type: object
                title: Merge Field Options
                description: Extra options for some merge field types.
                properties:
                  default_country:
                    type: integer
                    title: Default Country
                    description: In an address field, the default country code if none supplied.
                  phone_format:
                    type: string
                    title: Phone Type
                    description: 'In a phone field, the phone number type: US or International.'
                  date_format:
                    type: string
                    title: Date Type
                    description: In a date or birthday field, the format of the date.
                  choices:
                    type: array
                    title: Choices
                    description: In a radio or dropdown non-group field, the available options for contacts to pick from.
                    items:
                      type: string
                    example:
                    - First Choice
                    - Second Choice
                    - Third Choice
                  size:
                    type: integer
                    title: Text Field Size
                    description: In a text field, the default length of the text field.
                    readOnly: true
              help_text:
                type: string
                title: Merge Field Help Text
                description: Extra text to help the subscriber fill out the form.
              list_id:
                type: string
                title: List ID
                description: The ID that identifies this merge field's audience'.
                readOnly: true
              _links:
                title: Links
                description: A list of link types and descriptions for the API schema documents.
                type: array
                items:
                  type: object
                  title: Resource Link
                  description: This object represents a link from the resource where it is found to another resource or action that may be performed.
                  properties:
                    rel:
                      type: string
                      title: Rel
                      description: As with an HTML 'rel' attribute, this describes the type of link.
        

# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mailchimp/refs/heads/main/openapi/mailchimp-merge-api-openapi.yml