Mailchimp Snapshots API

openapi: 3.2.0
info:
  contact:
    email: apihelp@mailchimp.com
    name: Mailchimp API Support
  description: 'Whether you’re managing your own campaigns, providing Mailchimp services to your customers or clients, or writing a mobile app, the Mailchimp API has features to manage and sync your contact data.


    Audiences are at the core of sending campaigns with Mailchimp. You can use the API to set up an audience and add contacts to that audience; you can then organize those contacts with tags or segment them by activity with events.


    The API can also be a source of data for your application. Webhooks collect and transmit information about your audience to you in near real time. And if you’re selling products on an external store, you can integrate your audience behavior using Mailchimp’s E-commerce features.


    You can also use the API to handle data in different ways for different purposes. If you are syncing a large amount of data with Mailchimp, you can use batches to avoid hitting the API request limits. For building integrations that let other users access data from their own Mailchimp accounts, you should authenticate with OAuth 2. And if you’re developing an app for iOS or Android, the Mobile SDK provides an easy way to work with a mobile-focused subset of the API’s functionality.'
  summary: Manage audiences, integrate your data, and send timely, relevant email campaigns.
  termsOfService: https://mailchimp.com/legal/api_use/
  title: Mailchimp Snapshots API
  version: 0.1.0-dev
servers:
- description: Mailchimp API
  url: https://api.mailchimp.com
security:
- bearerToken: []
- oauth2: []
tags:
- name: Snapshots
paths:
  /3.0/segments/{segment_id}/snapshots:
    post:
      description: Start a snapshot of the members of a segment. The API makes the snapshot in the background. Use Get Segment Snapshot to see its status. To snapshot an advanced segment, the account's plan must include advanced segmentation. If it does not, the API returns a 403 error. Other types of segment do not need advanced segmentation.
      operationId: createSegmentSnapshot
      parameters:
      - description: The unique id for the segment.
        in: path
        name: segment_id
        required: true
        schema:
          type: string
          x-title: Segment ID
        x-title: Segment ID
      responses:
        '200':
          content:
            application/json:
              schema:
                description: A segment snapshot.
                properties:
                  id:
                    description: The unique ID of the snapshot.
                    example: b1b49562-5a44-4ebd-822c-5e215f66f679
                    readOnly: true
                    title: Snapshot ID
                    type: string
                  status:
                    description: The status of the snapshot.
                    enum:
                    - pending
                    - running
                    - completed
                    - failed
                    - canceled
                    example: pending
                    readOnly: true
                    title: Snapshot status
                    type: string
                type: object
          description: The snapshot request that the API accepted.
        '202':
          content:
            application/json:
              schema:
                description: A segment snapshot.
                properties:
                  id:
                    description: The unique ID of the snapshot.
                    example: b1b49562-5a44-4ebd-822c-5e215f66f679
                    readOnly: true
                    title: Snapshot ID
                    type: string
                  status:
                    description: The status of the snapshot.
                    enum:
                    - pending
                    - running
                    - completed
                    - failed
                    - canceled
                    example: pending
                    readOnly: true
                    title: Snapshot status
                    type: string
                type: object
          description: The API accepted the snapshot request.
        default:
          content:
            application/problem+json:
              schema:
                description: 'An error generated by the Mailchimp API. The response conforms to [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457).'
                properties:
                  detail:
                    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).
                    examples:
                    - The requested resource could not be found.
                    title: Error Message
                    type: string
                  instance:
                    description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                    examples:
                    - 995c5cb0-3280-4a6e-808b-3b096d0bb219
                    title: Instance ID
                    type: string
                  status:
                    description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                    examples:
                    - 404
                    title: HTTP Status Code
                    type: integer
                  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.
                    examples:
                    - Resource Not Found
                    title: Error Title
                    type: string
                  type:
                    description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                    examples:
                    - https://mailchimp.com/developer/marketing/docs/errors/
                    title: Problem Type
                    type: string
                required:
                - detail
                - instance
                - status
                - title
                - type
                title: Problem Detail Document
                type: object
          description: An error generated by the Mailchimp API.
      summary: Snapshot a Segment
      tags:
      - Snapshots
      x-custom-config:
        methodNameCamel: createSegmentSnapshot
        methodNameSnake: create_segment_snapshot
  /3.0/segments/{segment_id}/snapshots/{snapshot_id}:
    get:
      description: Get the status of a segment snapshot.
      operationId: getSegmentSnapshot
      parameters:
      - description: The unique id for the segment.
        in: path
        name: segment_id
        required: true
        schema:
          type: string
          x-title: Segment ID
        x-title: Segment ID
      - description: The unique id for the snapshot.
        in: path
        name: snapshot_id
        required: true
        schema:
          type: string
          x-title: Snapshot ID
        x-title: Snapshot ID
      responses:
        '200':
          content:
            application/json:
              schema:
                description: A segment snapshot.
                properties:
                  id:
                    description: The unique ID of the snapshot.
                    example: b1b49562-5a44-4ebd-822c-5e215f66f679
                    readOnly: true
                    title: Snapshot ID
                    type: string
                  status:
                    description: The status of the snapshot.
                    enum:
                    - pending
                    - running
                    - completed
                    - failed
                    - canceled
                    example: pending
                    readOnly: true
                    title: Snapshot status
                    type: string
                type: object
          description: ''
        default:
          content:
            application/problem+json:
              schema:
                description: 'An error generated by the Mailchimp API. The response conforms to [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457).'
                properties:
                  detail:
                    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).
                    examples:
                    - The requested resource could not be found.
                    title: Error Message
                    type: string
                  instance:
                    description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                    examples:
                    - 995c5cb0-3280-4a6e-808b-3b096d0bb219
                    title: Instance ID
                    type: string
                  status:
                    description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                    examples:
                    - 404
                    title: HTTP Status Code
                    type: integer
                  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.
                    examples:
                    - Resource Not Found
                    title: Error Title
                    type: string
                  type:
                    description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                    examples:
                    - https://mailchimp.com/developer/marketing/docs/errors/
                    title: Problem Type
                    type: string
                required:
                - detail
                - instance
                - status
                - title
                - type
                title: Problem Detail Document
                type: object
          description: An error generated by the Mailchimp API.
      summary: Get Segment Snapshot
      tags:
      - Snapshots
      x-custom-config:
        methodNameCamel: getSegmentSnapshot
        methodNameSnake: get_segment_snapshot
  /3.0/segments/{segment_id}/snapshots/{snapshot_id}/members:
    get:
      deprecated: false
      description: Get the contact IDs of the members in a segment snapshot, one page at a time.
      operationId: getSegmentSnapshotContactIdList
      parameters:
      - description: A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
        explode: false
        in: query
        name: fields
        schema:
          items:
            type: string
          type: array
          x-title: Fields
        style: form
        x-title: Fields
      - description: A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.
        explode: false
        in: query
        name: exclude_fields
        schema:
          items:
            type: string
          type: array
          x-title: Exclude Fields
        style: form
        x-title: Exclude Fields
      - description: The number of records to return. Default value is 10. Maximum value is 1000
        in: query
        name: count
        schema:
          default: 10
          maximum: 1000
          type: integer
          x-title: Count
        x-title: Count
      - description: The number of members to return in one page. The default is 100000. The maximum is 500000.
        in: query
        name: limit
        required: false
        schema:
          default: 100000
          maximum: 500000
          type: integer
          x-title: Limit
        x-title: Limit
      - description: Paginate through a collection of records by setting the `cursor` parameter to a `next_cursor` attribute returned by a previous request. Default value fetches the first "page" of results.
        in: query
        name: cursor
        schema:
          type: string
          x-title: cursor
        x-title: cursor
      - description: The unique id for the segment.
        in: path
        name: segment_id
        required: true
        schema:
          type: string
          x-title: Segment ID
        x-title: Segment ID
      - description: The unique id for the snapshot.
        in: path
        name: snapshot_id
        required: true
        schema:
          type: string
          x-title: Snapshot ID
        x-title: Snapshot ID
      responses:
        '200':
          content:
            application/json:
              schema:
                description: A list of the members in a segment snapshot.
                properties:
                  _links:
                    description: A list of link types and descriptions for the API schema documents.
                    items:
                      description: This object represents a link from the resource where it is found to another resource or action that may be performed.
                      properties:
                        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
                          title: Href
                          type: string
                        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
                          title: Method
                          type: string
                        rel:
                          description: As with an HTML 'rel' attribute, this describes the type of link.
                          readOnly: true
                          title: Rel
                          type: string
                        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
                          title: Schema
                          type: string
                        targetSchema:
                          description: For GETs, this is a URL representing the schema that the response should conform to.
                          readOnly: true
                          title: Target Schema
                          type: string
                      title: Resource Link
                      type: object
                    readOnly: true
                    title: Links
                    type: array
                  members:
                    description: A list of the members in a segment snapshot.
                    items:
                      description: A member of a segment snapshot. The contact ID identifies the member.
                      properties:
                        contact_id:
                          description: The contact ID of the segment member.
                          example: abc123def456
                          title: Contact ID
                          type: string
                      title: Segment Member
                      type: object
                    title: Segment Members
                    type: array
                  next_cursor:
                    description: A cursor pointing to the last item on this page of the collection. Paginate through a collection of records by setting the `cursor` parameter on a subsequent request to this value.
                    readOnly: true
                    title: Next Cursor
                    type: string
                type: object
          description: The API returns this when the snapshot is complete.
        '202':
          description: The API returns this when the snapshot is not complete.
        default:
          content:
            application/problem+json:
              schema:
                description: 'An error generated by the Mailchimp API. The response conforms to [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457).'
                properties:
                  detail:
                    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).
                    examples:
                    - The requested resource could not be found.
                    title: Error Message
                    type: string
                  instance:
                    description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                    examples:
                    - 995c5cb0-3280-4a6e-808b-3b096d0bb219
                    title: Instance ID
                    type: string
                  status:
                    description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                    examples:
                    - 404
                    title: HTTP Status Code
                    type: integer
                  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.
                    examples:
                    - Resource Not Found
                    title: Error Title
                    type: string
                  type:
                    description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                    examples:
                    - https://mailchimp.com/developer/marketing/docs/errors/
                    title: Problem Type
                    type: string
                required:
                - detail
                - instance
                - status
                - title
                - type
                title: Problem Detail Document
                type: object
          description: An error generated by the Mailchimp API.
      summary: Get Snapshot Member Contact IDs
      tags:
      - Snapshots
      x-custom-config:
        methodNameCamel: listSegmentSnapshotContactIdList
        methodNameSnake: list_segment_snapshot_contact_id_list
components:
  securitySchemes:
    bearerToken:
      description: Authorization using a Mailchimp API key (a.k.a. Bearer token)
      scheme: Bearer
      type: http
    oauth2:
      description: Authorization using OAuth
      flows:
        authorizationCode:
          authorizationUrl: https://login.mailchimp.com/oauth2/authorize
          scopes: {}
          tokenUrl: https://login.mailchimp.com/oauth2/token
      type: oauth2