Constant Contact Segments 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 Segments 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: Segments
  description: Use segments to target a subset of your contacts that are most likely to engage with a particular campaign.
paths:
  /segments:
    get:
      tags:
      - Segments
      summary: GET all Segments
      description: Use this method to get a list of all segments associated with the account. You can sort segment results and limit the number of segments that display per page. Deleted segments are excluded from the results. For more use case information, see Get All Segments in the API guide.
      operationId: getAccountSegments
      parameters:
      - name: limit
        in: query
        description: The number of segments to return on a page.
        required: false
        x-example: '1000'
        schema:
          type: string
          default: '1000'
      - name: sort_by
        in: query
        description: Specify the segment sort order to use. Sort by name (`sort_by=name`) in ascending order, or sort by date (`sort_by=date`) in descending order with the most recently updated segments listed first.
        required: false
        x-example: sort_by=date
        schema:
          type: string
          default: date
      responses:
        '200':
          description: Request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentsDTO'
        '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.
        '415':
          description: Unsupported Media Type.
        '429':
          description: Too many requests. You exceeded the request rate limit.
        '500':
          description: There was a problem with our internal service.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:lists:read
      x-sdk-methodName: getAllSegments
    post:
      tags:
      - Segments
      summary: POST (create) a Segment
      description: 'Use this method to create a new segment. You create segments to target a subset of your contacts that meet your specific criteria for a marketing campaign. The segment `name` must be unique. The `segment_criteria` requires single-string escaped JSON. Constant Contact uses the contact data that you specify in the `segment_criteria` to evaluate and identify the contacts you want to target. Contact data can be grouped from different data sources, including:


        - **`tracking`**: Supports **or** and **and** groups.


        - **`contact`**: Supports **or** and **and** groups.


        - **`list_membership`**: Supports **or** groups.


        - **`tags`**: Supports **or** groups.


        If you do not specify `list_membership` as criteria, Constant Contact evaluates all contacts in your account. To avoid returning a 400 error response, when specifying the `segment_criteria` do not request more than 500 email campaigns or a date range greater than 1825 days (5 years) be evaluated.


        For more use case information, see the Segments Overview in the API guide.'
      operationId: createSegment
      responses:
        '201':
          description: Segment successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentDetail'
        '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.
        '415':
          description: Unsupported Media Type.
        '500':
          description: There was a problem with our internal service.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:lists:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentData'
        description: The segment `name` and `segment_criteria` (requires single-string escaped JSON).
        required: true
  /segments/{segment_id}:
    get:
      tags:
      - Segments
      summary: GET a Segment's Details
      description: Use this method to get details about a segment, including the segment criteria. If you know the `segment_id` You can also use this method to get details about a deleted segment. For more use case information, see Get a Segment's Details in the API guide.
      operationId: getSegmentDetail
      parameters:
      - name: segment_id
        in: path
        description: The system-generated unique ID that identifies a segment.
        required: true
        x-example: 14
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: The segment was successfully returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentDetail'
        '400':
          description: Bad request. Either the JSON was malformed or there was a data validation error.
        '401':
          description: The Access Token used is invalid.
        '404':
          description: The requested resource was not found.
        '415':
          description: Unsupported Media Type.
        '500':
          description: There was a problem with our internal service.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:lists:read
      x-sdk-methodName: getSegmentById
    put:
      tags:
      - Segments
      summary: PUT (update) a Segment
      description: Use this method to update an existing segment's name (`name`) and/or contact selection criteria (`segment_criteria`). You must specify both the `name` and the `segment_criteria` in the request body, even if you don't plan to update both. The segment's name must be unique and the JSON must be valid (requires single-string escaped JSON). To avoid returning a 400 error response, when specifying the `segment_criteria` do not request more than 500 email campaigns or a date range greater than 1825 days (5 years) be evaluated. For more use case information, see Update Segment Details in the API guide.
      operationId: updateSegment
      parameters:
      - name: segment_id
        in: path
        description: The system generated ID that uniquely identifies the segment that you want to modify.
        required: true
        x-example: 14
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: The segment was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentDetail'
        '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.
        '415':
          description: Unsupported Media Type.
        '500':
          description: There was a problem with our internal service.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:lists:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentData'
        description: Include both the `name` and `segment_criteria` (single-string escaped JSON) in the body request, then make updates to either or both.
        required: true
    delete:
      tags:
      - Segments
      summary: DELETE a Segment
      description: 'Use this method to delete a segment from your account. Before deleting a segment, verify that the segment is not associated with a scheduled campaign.


        Deleted segments do not display in the results when using the `GET /segments` endpoint. If you know the `segment_id`, you can use the `GET /segments/{segment_id}` endpoint to view the deleted segment''s details. A segment''s details are preserved for external reference purposes, such as displaying the segment name in a campaign''s history. For more use case information, see Delete a Segment in the API guide.'
      operationId: deleteSegment
      parameters:
      - name: segment_id
        in: path
        description: The system generated ID that uniquely identifies the segment.
        required: true
        x-example: 14
        schema:
          type: integer
          format: int32
      responses:
        '204':
          description: The segment was successfully deleted.
        '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.
        '415':
          description: Unsupported Media Type.
        '500':
          description: There was a problem with our internal service.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:lists:write
  /segments/{segment_id}/name:
    patch:
      tags:
      - Segments
      summary: PATCH (rename) a Segment
      description: Use this method to update an existing segment `name` with a new unique name in the request body. For more use case information, see Rename a Segment in the API guide.
      operationId: updateSegmentName
      parameters:
      - name: segment_id
        in: path
        description: The system generated ID that uniquely identifies the segment that you want to modify.
        required: true
        x-example: 14
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: The segment name was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentDetail'
        '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.
        '415':
          description: Unsupported Media Type.
        '500':
          description: There was a problem with our internal service.
      security:
      - oauth2_implicit:
        - contact_data
      - oauth2_access_code:
        - contact_data
      x-authorization-privileges:
      - contacts:lists:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentName'
        description: Include the existing segment `name` in the body request, then rename the segment using a unique new name.
        required: true
components:
  schemas:
    SegmentDetail:
      type: object
      properties:
        name:
          type: string
          example: Re-engage contacts who did not open the last 5 email campaign activities.
          description: The segment's unique descriptive name.
        segment_criteria:
          type: string
          example: '{"version":"1.0.0","criteria":{"type":"and","group":[{"source":"tracking","field":"not_opened","op":"contains-any","const_value":"last-n-campaigns","param":"5"}]}}'
          description: The segment's contact selection criteria formatted as single-string escaped JSON.
          maxLength: 20000
        segment_id:
          type: integer
          format: int32
          example: 14
          description: The system generated number that uniquely identifies the segment.
          readOnly: true
        created_at:
          type: string
          format: date-time
          example: '2019-04-25T11:08:00.000Z'
          description: The system generated date and time (ISO-8601) that the segment was created.
          readOnly: true
        edited_at:
          type: string
          format: date-time
          example: '2019-04-25T11:08:00.000Z'
          description: The system generated date and time (ISO-8601) that the segment's <code>name</code> or <code> segment_criteria</code> was last updated.
          readOnly: true
    SegmentData:
      type: object
      required:
      - name
      - segment_criteria
      properties:
        name:
          type: string
          example: Re-engage contacts who did not open the last 5 email campaign activities.
          description: The segment's unique descriptive name.
        segment_criteria:
          type: string
          example: '{"version":"1.0.0","criteria":{"type":"and","group":[{"source":"tracking","field":"not_opened","op":"contains-any","const_value":"last-n-campaigns","param":"5"}]}}'
          description: The <code>segment_criteria</code> specifies the contact data that Constant Contact uses to evaluate and identify contacts that meet your criteria. The <code>segment_criteria</code> must be formatted as single-string escaped JSON. The top-level <code>group</code> <code>type</code> must be <code>add</code>.
          maxLength: 20000
    Next:
      type: object
      required:
      - href
      properties:
        href:
          type: string
          description: The next link in the page, or null if there are no additional pages.
    SegmentMaster:
      type: object
      properties:
        name:
          type: string
          example: Re-engage contacts who did not open the last 5 campaigns.
          description: The segment's unique descriptive name.
        segment_id:
          type: integer
          format: int32
          example: 14
          description: The system generated number that uniquely identifies the segment.
          readOnly: true
        created_at:
          type: string
          format: date-time
          example: '2019-04-25T11:08:00.000Z'
          description: The system generated date and time that the segment was created (ISO-8601 format).
          readOnly: true
        edited_at:
          type: string
          format: date-time
          example: '2019-04-25T11:08:00.000Z'
          description: The system generated date and time that the segment's <code>name</code> or <code>segment_criteria</code> was last updated (ISO-8601 format).
          readOnly: true
    SegmentName:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          example: Contacts who did not open any email campaign within the last 100 days.
          description: The segment's unique descriptive name.
    segmentsLinks:
      type: object
      required:
      - next
      properties:
        next:
          description: HAL property that contains next link if applicable.
          $ref: '#/components/schemas/Next'
    SegmentsDTO:
      type: object
      required:
      - segments
      properties:
        segments:
          type: array
          description: Lists all segments for the account.
          items:
            $ref: '#/components/schemas/SegmentMaster'
        _links:
          description: HAL property that contains next link if applicable.
          $ref: '#/components/schemas/segmentsLinks'
  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