Constant Contact 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](/api_guide/tags_get_single.html).
      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](/api_guide/tags_update.html)
      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](/api_guide/tags_delete.html).
      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 <code>include_count</code> query parameter to include the total number of contacts assigned each tag. Use the <code>limit</code> query parameter to limit the number of tag results returned per page. To get the next page of results, copy the <code>cursor={the cursor ID}</code> from the resulting href link and add it (<code>&</code>) to the URL. For example:


        <p><code>/v3/contact_tags?limit=1&cursor=</code></p><p><code>bGltaXQ9MSZuZXh0PTJjZDgwMjdhLTc4YzAtMTFlOS1iZmQwLWZhMTYzZTZiMDFjMQ=</code></p>

        To learn more, see [Get Tags](/api_guide/tags_get.html).'
      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](/api_guide/tags_create.html).
      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:
    reportingNext:
      type: object
      properties:
        href:
          type: string
          description: The next link in the page or null if there are no additional pages.
    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
    ActivityErrors:
      type: object
      properties:
        message:
          type: string
          description: Message describing the error condition.
          readOnly: true
    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
    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
    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'
    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
    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.
    tagsLinks:
      type: object
      properties:
        href:
          type: string
        next:
          description: Contains the next page link, if applicable.
          $ref: '#/components/schemas/reportingNext'
    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'
    tagsPagingLinks:
      type: object
      properties:
        next:
          description: The link to the next page of results.
          $ref: '#/components/schemas/tagsLinks'
  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