Constant Contact Contact Lists API

swagger: '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.149
  title: AppConnect V3 Account Services Contact Lists API
  contact:
    name: webservices@constantcontact.com
  license:
    name: Private
    url: https://www.constantcontact.com/legal/terms-of-use
host: api.cc.email
basePath: /v3
schemes:
- https
consumes:
- application/json
produces:
- application/json
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
      produces:
      - application/json
      parameters:
      - name: list_id
        in: path
        description: The system generated ID that uniquely identifies a contact list.
        required: true
        type: string
        format: uuid
        x-example: cbc05bac-6a41-46fa-a063-79961763bf4b
      - 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
        type: string
        enum:
        - all
        - active
        x-example: all
      responses:
        '200':
          description: Request successful
          schema:
            $ref: '#/definitions/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
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: list_id
        in: path
        description: Unique ID of the contact list to update
        required: true
        type: string
        format: uuid
        x-example: cbc05bac-6a41-46fa-a063-79961763bf4b
      - in: body
        name: JSON PUT body
        description: JSON payload containing updates to the specified contact list
        required: true
        schema:
          $ref: '#/definitions/ListInput'
      responses:
        '200':
          description: Request successful
          schema:
            $ref: '#/definitions/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
    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
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: list_id
        in: path
        description: Unique ID of the list to delete
        required: true
        type: string
        format: uuid
        x-example: cbc05bac-6a41-46fa-a063-79961763bf4b
      responses:
        '202':
          description: Accepted
          headers:
            Location:
              type: string
              description: URL to retrieve the delete activity status
          schema:
            $ref: '#/definitions/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
      produces:
      - application/json
      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
        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
        type: boolean
        default: false
        x-example: true
      - 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
        type: string
        enum:
        - all
        - active
        x-example: all
      - name: name
        in: query
        description: Use to get details for a single list by entering the full name of the list.
        required: false
        type: string
        x-example: TopTier
      - name: status
        in: query
        description: Use to get lists by status. Accepts comma-separated status values.
        required: false
        type: string
        enum:
        - all
        - active
        - deleted
        x-example: all
      - name: channel_type
        in: query
        description: Use to return lists by channel type. The default value is `email`.
        required: false
        type: string
        enum:
        - email
        - sms
        x-example: all
      - 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
        type: boolean
        x-example: 'false'
      responses:
        '200':
          description: Request successful
          schema:
            $ref: '#/definitions/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
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: JSON payload defining the new contact list
        required: true
        schema:
          $ref: '#/definitions/ListInput'
      responses:
        '201':
          description: New list successfully created
          schema:
            $ref: '#/definitions/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
  /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
      produces:
      - application/json
      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
        type: string
        maxItems: 500
        format: csv
        x-example: 1995998026,1882999944,1775099999
      responses:
        '200':
          description: Request successful
          schema:
            $ref: '#/definitions/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
definitions:
  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: '#/definitions/ListXref'
        maxItems: 500
  PagingLinks:
    type: object
    properties:
      next:
        $ref: '#/definitions/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
  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>.
  ContactListArray:
    type: object
    properties:
      lists:
        type: array
        items:
          $ref: '#/definitions/ContactList'
      lists_count:
        type: integer
        example: 249
        description: The total number of contact lists.
      _links:
        $ref: '#/definitions/PagingLinks'
  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.
  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
  Link:
    type: object
    properties:
      href:
        type: string
        example: /v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a
  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
securityDefinitions:
  oauth2_implicit:
    type: oauth2
    authorizationUrl: https://authz.constantcontact.com/oauth2/default/v1/authorize
    flow: 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.
  oauth2_access_code:
    type: oauth2
    authorizationUrl: https://authz.constantcontact.com/oauth2/default/v1/authorize
    tokenUrl: https://authz.constantcontact.com/oauth2/default/v1/token
    flow: accessCode
    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.
  ctctPartnerAuthorizer:
    description: Partner Authentication
    type: oauth2
    authorizationUrl: https://v3api-partner.auth.us-east-1.amazoncognito.com/oauth2/token
    flow: implicit
    scopes:
      v3api/general.partner: Access to general partner API methods
  api_key:
    type: apiKey
    name: x-api-key
    in: header