Constant Contact Tags 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 Tags 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 Tags
  description: Endpoints and methods to get, create, delete, and update one or more contact tags.
paths:
  /contact_tags/{tag_id}:
    get:
      tags:
      - Contact Tags
      summary: GET Tag Details
      description: Use this method to get tag details for a specified `tag_id`. Use the `include_count` query parameter to include or exclude the total number of contacts to which this tag is assigned. To learn more, see Get a Tag's Details.
      operationId: getTag
      parameters:
      - name: tag_id
        in: path
        description: The ID that uniquely identifies a tag (UUID format).
        required: true
        x-example: d938260a-af1e-11e9-a540-fa163e595123
        schema:
          type: string
          format: uuid
      - name: include_count
        in: query
        description: Use to include (`true`) or exclude (`false`) the total number of tagged contacts (`contacts_count`) from the results.
        required: false
        x-example: true
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Request Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        '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.
      security:
      - oauth2_implicit:
        - contact_data
        oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:read
    put:
      tags:
      - Contact Tags
      summary: PUT (Update) a Tag
      description: Use this method to rename an existing tag to a new unique tag name (`name`). The maximum length is 255 characters. The `tag_source` value cannot be updated using this method. You can set the `tag_source` value using the `POST contact_tags method`. Learn more
      operationId: putTag
      parameters:
      - name: tag_id
        in: path
        description: The system generated ID used to uniquely identify the tag that you want to rename (UUID format).
        required: true
        x-example: 30c97dd0-332e-11eb-923c-fa163e595327
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Request Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        '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.
        '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.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagPut'
        description: The JSON payload used to update the tag name (`name`).
        required: true
    delete:
      tags:
      - Contact Tags
      summary: DELETE a Tag
      description: Use this method to create an activity used to un-assign a tag from all assigned contacts and delete the tag. This is an asynchronous activity. To view activity details for the delete request, use the href link returned in the response. Learn more.
      operationId: deleteTag
      parameters:
      - name: tag_id
        in: path
        description: The ID that uniquely identifies a tag in UUID format.
        required: true
        x-example: 30c97dd0-332e-11eb-923c-fa163e595327
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: The asynchronous request was successfully accepted. To view the results of the activity request, use the href link returned in the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityGeneric'
        '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.
        '406':
          description: The requested resource was not found.
        '500':
          description: There was a problem with our internal service.
      security:
      - oauth2_implicit:
        - contact_data
        oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:write
  /contact_tags:
    get:
      tags:
      - Contact Tags
      summary: GET Details for All Tags
      description: 'Use this endpoint to get details for all tags in your account. Use the include_count query parameter to include the total number of contacts assigned each tag. Use the limit query parameter to limit the number of tag results returned per page. To get the next page of results, copy the cursor={the cursor ID} from the resulting href link and add it (&) to the URL. For example:


        /v3/contact_tags?limit=1&cursor=


        bGltaXQ9MSZuZXh0PTJjZDgwMjdhLTc4YzAtMTFlOS1iZmQwLWZhMTYzZTZiMDFjMQ=


        To learn more, see Get Tags.'
      operationId: getTags
      parameters:
      - name: limit
        in: query
        description: Use to specify the number of tag results (up to `500`) to display per page of output. The default is `50`.
        required: false
        x-example: 25
        schema:
          type: integer
          default: 50
          maxLength: 500
          minLength: 1
      - name: include_count
        in: query
        description: Returns the total number of contacts (`contacts_count`) to which a tag applies.
        required: false
        x-example: true
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Request Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tags'
        '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.
      security:
      - oauth2_implicit:
        - contact_data
        oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:read
      x-sdk-methodName: getAllTags
    post:
      tags:
      - Contact Tags
      summary: POST (Create) a Tag
      description: Use this method to create a new tag. The tag `name` is required and must be unique and can include most common keyboard symbols. Optionally, when creating a new tag you can specify the source (`tag_source`) used to identify the contacts to tag in the request body. Learn more.
      operationId: postTag
      responses:
        '201':
          description: Request Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        '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.
        '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.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagPost'
        description: The JSON payload to use to create a new tag.
        required: true
components:
  schemas:
    TagPut:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          example: Bronze card member
          description: The new tag name to use. The tag name must be unique.
          minLength: 1
          maxLength: 255
    ActivityGeneric:
      type: object
      required:
      - activity_id
      - state
      properties:
        activity_id:
          type: string
          example: d44ac96c-24f3-11eb-8ae8-fa163e595123
          description: The ID that uniquely identifies the activity.
        state:
          type: string
          example: completed
          description: The processing state for the activity.
        created_at:
          type: string
          format: date-time
          example: '2016-01-23T13:48:44.108Z'
          description: The 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-01-23T13:48:44.108Z'
          description: The system generated date and time that the resource was last updated, in ISO-8601 format.
          readOnly: true
        percent_done:
          type: integer
          example: 25
          description: The percentage complete for the specified activity.
          readOnly: true
        activity_errors:
          type: array
          description: An array of error messages if errors occurred for a specified activity. The system returns an empty array if no errors occur.
          readOnly: true
          items:
            $ref: '#/components/schemas/ActivityErrors'
        status:
          $ref: '#/components/schemas/ActivityGenericStatus'
        _links:
          $ref: '#/components/schemas/tagsActivityLinks'
    TagPost:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          example: Silver card member
          description: Specify a unique name to use to identify the tag. Tag names must be at least one character in length and not more than 255 characters.
          minLength: 1
          maxLength: 255
        tag_source:
          type: string
          example: ESTY
          description: The source used to identify the contacts to tag.
    Tags:
      type: object
      properties:
        tags:
          type: array
          description: Lists all tags and provides tag details.
          items:
            $ref: '#/components/schemas/Tag'
        _links:
          description: HAL property that contains next link if applicable.
          $ref: '#/components/schemas/tagsPagingLinks'
    tagsPagingLinks:
      type: object
      properties:
        next:
          description: The link to the next page of results.
          $ref: '#/components/schemas/tagsLinks'
    ActivityGenericStatus:
      type: object
      properties:
        items_total_count:
          type: integer
          example: 89
          description: The total number of tags that this activity will delete.
          readOnly: true
        items_completed_count:
          type: integer
          example: 89
          description: The number of tags that this activity has currently deleted.
          readOnly: true
    tagsLinks:
      type: object
      properties:
        href:
          type: string
        next:
          description: Contains the next page link, if applicable.
          $ref: '#/components/schemas/reportingNext'
    tagsActivityLinks:
      type: object
      properties:
        self:
          type: object
          description: The link returned in the response that you use to retrieve the status for the specified activity.
          properties:
            href:
              type: string
              example: /v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a
    Tag:
      type: object
      properties:
        tag_id:
          type: string
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
          description: The ID that uniquely identifies a tag (UUID format)
        name:
          type: string
          example: Gold card member
          description: The unique tag name.
        contacts_count:
          type: integer
          example: 325
          description: The total number of contacts who are assigned this tag.
          readOnly: true
        created_at:
          type: string
          format: date-time
          example: '2019-04-25T11:08:00.000Z'
          description: The system generated date and time when the tag was created (ISO-8601 format).
          readOnly: true
        updated_at:
          type: string
          format: date-time
          example: '2016-01-23T13:48:44.108Z'
          description: The system generated date and time when the tag was last updated (ISO-8601 format).
          readOnly: true
        tag_source:
          type: string
          example: ESTY
          description: The source used to tag contacts.
          readOnly: true
    ActivityErrors:
      type: object
      properties:
        message:
          type: string
          description: Message describing the error condition.
          readOnly: true
    reportingNext:
      type: object
      properties:
        href:
          type: string
          description: The next link in the page or null if there are no additional pages.
  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