Constant Contact Contact Lists API

openapi: 3.2.0
info:
  description: The Constant Contact, Inc. V3 public API, for building integrations with Constant Contact, the leading small-business email marketing platform.
  version: 3.0.178
  title: AppConnect V3 Contact Lists API
  contact:
    name: webservices@constantcontact.com
  license:
    name: Private
    url: https://www.constantcontact.com/legal/terms-of-use
servers:
- url: https://api.cc.email/v3
tags:
- name: Contact Lists
  description: Endpoints and methods to get, create, delete, and update one or more contact lists.
paths:
  /contact_lists/{list_id}:
    get:
      tags:
      - Contact Lists
      summary: GET a List
      description: Use this method to get details about a specific contact list (`list_id`).
      operationId: getList
      parameters:
      - name: list_id
        in: path
        description: The system generated ID that uniquely identifies a contact list.
        required: true
        x-example: cbc05bac-6a41-46fa-a063-79961763bf4b
        schema:
          type: string
          format: uuid
      - name: include_membership_count
        in: query
        description: Returns the total number of contacts per list that meet your selection criteria. Set the `include_membership_count` to `active`, to count only active contacts, or `all` to include all contacts in the count.
        required: false
        x-example: all
        schema:
          type: string
          enum:
          - all
          - active
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '404':
          description: The requested resource was not found.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:lists:read
    put:
      tags:
      - Contact Lists
      summary: PUT (update) a List
      description: Updates an existing contact list resource, specified by `list_id`
      operationId: putList
      parameters:
      - name: list_id
        in: path
        description: Unique ID of the contact list to update
        required: true
        x-example: cbc05bac-6a41-46fa-a063-79961763bf4b
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactListPutPost'
        '400':
          description: Bad request. Either the JSON was malformed or there was a data validation error.
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '404':
          description: The requested resource was not found.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:lists:write
      x-ctctmcp-allow: true
      x-sdk-methodName: updateList
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListInput'
        description: JSON payload containing updates to the specified contact list
        required: true
    delete:
      tags:
      - Contact Lists
      summary: DELETE a List
      description: Deletes the specified contact list and its membership. DELETE List requests are processed asynchronously, and you can track the status of the request by making a GET call to the URI shown in the `_links` property in the response.
      operationId: deleteListActivity
      parameters:
      - name: list_id
        in: path
        description: Unique ID of the list to delete
        required: true
        x-example: cbc05bac-6a41-46fa-a063-79961763bf4b
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: Accepted
          headers:
            Location:
              description: URL to retrieve the delete activity status
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityDeleteListResponse'
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '404':
          description: The requested resource was not found.
        '415':
          description: Unsupported Media Type.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:lists:write
      x-sdk-methodName: deleteList
  /contact_lists:
    get:
      tags:
      - Contact Lists
      summary: GET Lists Collection
      description: 'Use this method to return details about all contact lists for the account.

        <div class="Msg"><p class="note-text">This method does not currently support filtering results using the contact list update date.</p></div>'
      operationId: getLists
      parameters:
      - name: limit
        in: query
        description: Use to specify the number of results displayed per page of output, from 1 - 500, default = 50.
        required: false
        schema:
          type: integer
          default: 50
          maximum: 1000
          minimum: 1
      - name: include_count
        in: query
        description: Set `include_count` to `true` to return the total number of contact lists that meet your selection criteria.
        required: false
        x-example: true
        schema:
          type: boolean
          default: false
      - name: include_membership_count
        in: query
        description: Use to include the total number of contacts per list. Set to  `active`, to count only active (mailable) contacts, or `all` to count all contacts.
        required: false
        x-example: all
        schema:
          type: string
          enum:
          - all
          - active
      - name: name
        in: query
        description: Use to get details for a single list by entering the full name of the list.
        required: false
        x-example: TopTier
        schema:
          type: string
      - name: status
        in: query
        description: Use to get lists by status. Accepts comma-separated status values.
        required: false
        x-example: all
        schema:
          type: string
          enum:
          - all
          - active
          - deleted
      - name: channel_type
        in: query
        description: Use to return lists by channel type. The default value is `email`.
        required: false
        x-example: all
        schema:
          type: string
          enum:
          - email
          - sms
      - name: include_sms_membership_count
        in: query
        description: Set to `true` to return the total number of SMS members in each list. Only applicable when `channel_type` is `sms`. Default is `false`.
        required: false
        x-example: 'false'
        schema:
          type: boolean
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactListArray'
        '400':
          description: Bad request. Either the JSON was malformed or there was a data validation error.
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:lists:read
      x-sdk-methodName: getAllLists
    post:
      tags:
      - Contact Lists
      summary: POST (create) a List
      description: Create a new contact list resource
      operationId: createList
      responses:
        '201':
          description: New list successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactListPutPost'
        '400':
          description: Bad request. Either the JSON was malformed or there was a data validation error.
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '409':
          description: Conflict. The resource you are creating or updating conflicts with an existing resource.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:lists:write
      x-ctctmcp-allow: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListInput'
        description: JSON payload defining the new contact list
        required: true
  /contact_lists/list_id_xrefs:
    get:
      tags:
      - Contact Lists
      summary: GET a collection of V2 and V3 API List IDs
      description: '<div class="Msg Msg--warning"><p class="note-text">Use this endpoint to migrate your locally stored V2 contact list data to the new V3 format. Developers are expected to use this endpoint sparingly. This endpoint is NOT intended for regular or repeated use. Constant Contact will eventually deprecate and remove this endpoint.</p></div>


        This GET call retrieves a collection of cross-referenced list sequence IDs (`id` used in the V2 API) and UUIDs (`list_id` used in the V3 API). This endpoint is intended for developers who have an existing V2 API integration, and are migrating their users to a new V3 API integration. The V2 and V3 APIs use different resource ID formats. Use the `sequence_ids` query parameter to specify a set of comma delimited V2 list ids to cross-reference. See [Migrating Apps and Data to V3](/api_guide/migration_overview.html) to learn more."'
      operationId: getListIdXrefs
      parameters:
      - name: sequence_ids
        in: query
        description: Comma delimited list of V2 API list `ids` to cross-reference with the V3 API `list_id` value. Endpoint accepts a maximum of 500 ids at a time.
        required: true
        x-example: 1995998026,1882999944,1775099999
        schema:
          type: string
          format: csv
          maxItems: 500
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListXrefs'
        '400':
          description: Bad request. Either the JSON was malformed or there was a data validation error.
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '404':
          description: The requested resource was not found.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:lists:read
components:
  schemas:
    ActivityDeleteListResponse:
      type: object
      properties:
        activity_id:
          type: string
          format: uuid
          description: Unique ID for the delete list batch job.
        state:
          type: string
          example: initialized
          description: "The state of the request:\n <p><ul>\n <li>initialized - request has been received</li>\n <li>processing - request is being processed</li>\n <li>completed - job completed</li>\n <li>cancelled - request was cancelled</li>\n <li>failed - job failed to complete</li>\n <li>timed_out - the request timed out before completing\"</li>\n  </ul> </p>"
        created_at:
          type: string
          format: date-time
          example: '2016-03-03T10:53:04-05:00'
          description: Date and time that the request was received, in ISO-8601 format.
        updated_at:
          type: string
          format: date-time
          example: '2016-03-03T10:56:29-05:00'
          description: Date and time that the request status was updated, in ISO-8601 format.
        percent_done:
          type: integer
          example: 1
          description: Job completion percentage
        activity_errors:
          type: array
          description: Array of messages describing the errors that occurred.
          items:
            type: string
            example: Message describing the error condition.
            description: Message describing the error condition.
            readOnly: true
        _links:
          type: object
          properties:
            self:
              type: object
              description: Link to the activity status to use in tracking the request status.
              properties:
                href:
                  type: string
                  example: /v3/activities/04fa57a7-cf55-4185-cc1a-58ed29bf0a6a
    ListXref:
      type: object
      properties:
        sequence_id:
          type: string
          example: '0016633325'
          description: The V2 API list unique identifier
        list_id:
          type: string
          format: uuid
          example: 71600990-908b-11e6-907f-1200166bff25
          description: The V3 API list unique identifier
      description: The cross-referenced pair of V3 API <code>list_id</code> and V2 API <code>sequence_id</code> for a list. Response is sorted ascending by <code>sequence_id</code>.
    ListXrefs:
      type: object
      properties:
        xrefs:
          type: array
          description: An array of cross-referenced V3 API <code>list_id</code> and V2 API <code>sequence_id</code> properties. Response is sorted ascending by <code>sequence_id</code>.
          items:
            $ref: '#/components/schemas/ListXref'
          maxItems: 500
    ListInput:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          example: Multiple purchases
          description: The name given to the contact list
          maxLength: 255
        favorite:
          type: boolean
          example: true
          description: Identifies whether or not the account has favorited the contact list.
          default: false
        description:
          type: string
          example: List of repeat customers
          description: Text describing the list.
    ContactListArray:
      type: object
      properties:
        lists:
          type: array
          items:
            $ref: '#/components/schemas/ContactList'
        lists_count:
          type: integer
          example: 249
          description: The total number of contact lists.
        _links:
          $ref: '#/components/schemas/PagingLinks'
    ContactList:
      type: object
      required:
      - list_id
      - name
      properties:
        list_id:
          type: string
          format: uuid
          example: 06526938-56dd-11e9-932a-fa163ea075fa
          description: Unique ID for the contact list
          readOnly: true
        name:
          type: string
          example: Multiple purchases
          description: The name given to the contact list
        description:
          type: string
          example: List of repeat customers.
          description: Text describing the list.
        favorite:
          type: boolean
          description: Identifies whether or not the account has favorited the contact list.
          default: false
        created_at:
          type: string
          format: date-time
          example: '2016-01-23T13:48:44.108Z'
          description: System generated date and time that the resource was created, in ISO-8601 format.
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2016-03-03T10:56:29-05:00'
          description: Date and time that the list was last updated, in ISO-8601 format. System generated.
          readOnly: true
        deleted_at:
          type: string
          format: date-time
          example: '2016-03-03T10:56:29-05:00'
          description: If the list was deleted, this property shows the date and time it was deleted, in ISO-8601 format. System generated.
          readOnly: true
        membership_count:
          type: integer
          example: 327
          description: The total number of contacts that are members in a list. Does not apply to segment type lists.
          readOnly: true
    PagingLinks:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/Link'
    ContactListPutPost:
      type: object
      required:
      - list_id
      - name
      properties:
        list_id:
          type: string
          format: uuid
          example: 06526938-56dd-11e9-932a-fa163ea075fa
          description: Unique ID for the contact list
          readOnly: true
        name:
          type: string
          example: Multiple purchases
          description: The name given to the contact list
        description:
          type: string
          example: List of repeat customers.
          description: Text describing the list.
        favorite:
          type: boolean
          description: Identifies whether or not the account has favorited the contact list.
          default: false
        created_at:
          type: string
          format: date-time
          example: '2016-01-23T13:48:44.108Z'
          description: System generated date and time that the resource was created, in ISO-8601 format.
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2016-03-03T10:56:29-05:00'
          description: Date and time that the list was last updated, in ISO-8601 format. System generated.
          readOnly: true
        deleted_at:
          type: string
          format: date-time
          example: '2016-03-03T10:56:29-05:00'
          description: If the list was deleted, this property shows the date and time it was deleted, in ISO-8601 format. System generated.
          readOnly: true
    Link:
      type: object
      properties:
        href:
          type: string
          example: /v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a
  securitySchemes:
    oauth2_implicit:
      type: oauth2
      flows:
        implicit:
          scopes:
            contact_data: Read or modify contact data.
            campaign_data: Read or modify email campaign data.
            account_read: Read account data.
            account_update: Modify account data.
            billing_data: Read or modify billing data.
          authorizationUrl: https://authz.constantcontact.com/oauth2/default/v1/authorize
    oauth2_access_code:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            contact_data: Read or modify contact data.
            campaign_data: Read or modify email campaign data.
            account_read: Read account data.
            account_update: Modify account data.
            billing_data: Read or modify billing data.
          authorizationUrl: https://authz.constantcontact.com/oauth2/default/v1/authorize
          tokenUrl: https://authz.constantcontact.com/oauth2/default/v1/token
    ctctPartnerAuthorizer:
      type: oauth2
      flows:
        implicit:
          scopes:
            v3api/general.partner: Access to general partner API methods
          authorizationUrl: https://v3api-partner.auth.us-east-1.amazoncognito.com/oauth2/token
      description: Partner Authentication
    api_key:
      type: apiKey
      name: x-api-key
      in: header