openapi: 3.1.0
security:
- BearerAuth: []
info:
  title: Twilio SendGrid Marketing Campaigns Segments 2.0 API
  summary: The Twilio SendGrid Marketing Campaigns Segments V2 API allows you to create,
    edit, and delete segments as well as retrieve a list of segments or an individual
    segment by ID.
  description: 'The Twilio SendGrid Marketing Campaigns Segments V2 API allows you
    to create, edit, and delete segments as well as retrieve a list of segments or
    an individual segment by ID.


    Segments are similar to contact lists, except they update dynamically over time
    as information stored about your contacts or the criteria used to define your
    segments changes. When you segment your audience, you are able to create personalized
    Automation emails and Single Sends that directly address the wants and needs of
    your particular audience.


    Note that Twilio SendGrid checks for newly added or modified contacts who meet
    a segment''s criteria on an hourly schedule. Only existing contacts who meet a
    segment''s criteria will be included in the segment searches within 15 minutes.


    Segments built using engagement data such as "was sent" or "clicked" will take
    approximately 30 minutes to begin populating.


    Segment samples and counts are refreshed approximately once per hour; they do
    not update immediately. If no contacts are added to or removed from a segment
    since the last refresh, the sample and UI count displayed will be refreshed at
    increasing time intervals with a maximum sample and count refresh delay of 24
    hours.


    You can also manage your Segments with the [Marketing Campaigns application user
    interface](https://mc.sendgrid.com/contacts). See [**Segmenting Your Contacts**](https://docs.sendgrid.com/ui/managing-contacts/segmenting-your-contacts)
    for more information.'
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio SendGrid Support
    url: https://support.sendgrid.com/hc/en-us
  license:
    name: MIT
    url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
  version: 1.0.0
  x-sendgrid:
    libraryPackage: mc_segments_2
servers:
- url: https://api.sendgrid.com
  description: The Twilio SendGrid v3 API
paths:
  /v3/marketing/segments/2.0:
    post:
      operationId: CreateSegment
      summary: Create Segment
      tags:
      - Segmenting Contacts V2
      description: Segment `name` has to be unique. A user can not create a new segment
        with an existing segment name.
      requestBody:
        $ref: '#/components/requestBodies/SegmentWriteV2'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Segment2xx'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsSegmentV2'
        '404':
          description: ''
        '429':
          description: ''
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsSegmentV2'
    get:
      operationId: ListSegment
      summary: Get List of Segments
      tags:
      - Segmenting Contacts V2
      description: '**This endpoint allows you to retrieve a list of segments.**


        The query param `parent_list_ids` is treated as a filter.  Any match will
        be returned.  Zero matches will return a response code of 200 with an empty
        `results` array.


        `parent_list_ids` | `no_parent_list_id` | `ids` | `result`

        -----------------:|:--------------------:|:-------------:|:-------------:

        empty | false | empty | all segments values

        list_ids | false | empty | segments filtered by list_ids values

        list_ids |true | empty | segments filtered by list_ids and segments with no
        parent list_ids empty

        empty | true | empty | segments with no parent list_ids

        anything | anything | ids | segments with matching segment ids |'
      parameters:
      - name: ids
        in: query
        description: A list of segment IDs to retrieve. When this parameter is included,
          the `no_parent_list_ids` and `parent_list_ids` parameters are ignored and
          only segments with given IDs are returned.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: parent_list_ids
        in: query
        description: A comma separated list up to 50 in size, to filter segments on.  Only
          segments that have any of these list ids as the parent list will be retrieved.
          This is different from the parameter of the same name used when creating
          a segment.
        required: false
        schema:
          type: string
      - name: no_parent_list_id
        in: query
        description: If set to `true`, segments with an empty value of `parent_list_id`
          will be returned in the filter.  If the value is not present, it defaults
          to 'false'.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllSegments200'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsSegmentV2'
        '404':
          description: ''
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsSegmentV2'
  /v3/marketing/segments/2.0/{segment_id}:
    parameters:
    - name: segment_id
      in: path
      required: true
      schema:
        type: string
    patch:
      operationId: UpdateSegment
      summary: Update Segment
      tags:
      - Segmenting Contacts V2
      description: Segment `name` has to be unique. A user can not create a new segment
        with an existing segment name.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentUpdate'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Segment2xx'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsSegmentV2'
        '429':
          description: ''
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsSegmentV2'
    get:
      operationId: GetSegment
      summary: Get Segment by ID
      tags:
      - Segmenting Contacts V2
      description: Get Marketing Campaigns Segment by ID
      parameters:
      - name: contacts_sample
        in: query
        description: Defaults to `true`. Set to `false` to exclude the contacts_sample
          in the response.
        schema:
          type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Segment2xx'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsSegmentV2'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsSegmentV2'
    delete:
      operationId: DeleteSegment
      summary: Delete segment
      tags:
      - Segmenting Contacts V2
      description: '**This endpoint allows you to delete a segment by ID.**'
      responses:
        '202':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsSegmentV2'
        '404':
          description: ''
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsSegmentV2'
  /v3/marketing/segments/2.0/refresh/{segment_id}:
    post:
      operationId: RefreshSegment
      summary: Manually refresh a segment
      description: Manually refresh a segment by segment ID.
      tags:
      - Segmenting Contacts V2
      parameters:
      - name: segment_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 36
          minLength: 36
          format: uuid
      requestBody:
        $ref: '#/components/requestBodies/SegmentRefresh'
      responses:
        '202':
          description: The refresh was accepted and a request was sent to process.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentRefresh202'
              example:
                job_id: 1588e03b-50aa-454a-97d1-e1530345a5ec
        '403':
          description: Endpoint is forbidden to the user because they are a free user.
        '404':
          description: Segment ID was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentError'
              example:
                error: Segment does not exist.
        '429':
          description: The user has reached their limit of 2 requests per segment
            per day, 1 request per segment per hour, or 10 requests across all segments
            per day.
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentError'
              example:
                error: Please check [our status page](https://status.sendgrid.com/)
                  for updates or [contact support](https://support.sendgrid.com/)
                  if the issue is not listed.
components:
  schemas:
    Metadata:
      title: _metadata
      type: object
      properties:
        prev:
          type: string
          format: uri
        self:
          type: string
          format: uri
        next:
          type: string
          format: uri
        count:
          type: integer
          minimum: 0
    AllSegments200:
      title: all_segments_response
      type: object
      properties:
        id:
          type: string
          minLength: 36
          maxLength: 36
          format: uuid
          description: ID assigned to the segment when created.
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name of the segment.
        contacts_count:
          type: integer
          description: Total number of contacts present in the segment
        created_at:
          type: string
          description: ISO8601 timestamp of when the object was created
        updated_at:
          type: string
          description: ISO8601 timestamp of when the object was last updated
        sample_updated_at:
          type: string
          description: ISO8601 timestamp of when the samples were last updated
        next_sample_update:
          type: string
          description: ISO8601 timestamp of when the samples will be next updated
        parent_list_ids:
          type: array
          description: The array of list ids to filter contacts on when building this
            segment. It allows only one such list id for now. We will support more
            in future
          uniqueItems: true
          items:
            type: string
        query_version:
          type: string
          description: If not set, segment contains a query for use with Segment v1
            APIs. If set to '2', segment contains a SQL query for use in v2.
        _metadata:
          $ref: '#/components/schemas/Metadata'
        status:
          $ref: '#/components/schemas/SegmentStatusResponse'
      required:
      - id
      - name
      - contacts_count
      - created_at
      - updated_at
      - sample_updated_at
      - next_sample_update
      - parent_list_ids
      - query_version
      - status
    SegmentStatusResponse:
      title: segment_status_response
      type: object
      description: Segment status indicates whether the segment's contacts will be
        updated periodically
      properties:
        query_validation:
          type: string
          description: Status of query validation. PENDING, VALID, or INVALID
        error_message:
          type: string
          description: Describes any errors that were encountered during query validation
      required:
      - query_validation
    SegmentRefreshRequest:
      title: segment_refresh_request
      required:
      - user_time_zone
      type: object
      properties:
        user_time_zone:
          type: string
          description: The user's timezone. The timezone is used to reset the refresh
            count at midnight in the user's local time. Only [IANA time zone format](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
            is accepted.
      example:
        user_time_zone: America/Chicago
    SegmentRefresh202:
      title: segment_refresh_response
      type: object
      properties:
        job_id:
          type: string
          description: The ID of the manual refresh job. Used only for internal purposes.
      example:
        job_id: 1588e03b-50aa-454a-97d1-e1530345a5ec
    Segment2xx:
      title: segment_response
      type: object
      properties:
        id:
          type: string
          minLength: 36
          maxLength: 36
          format: uuid
          description: ID assigned to the segment when created.
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name of the segment.
        query_dsl:
          type: string
          description: SQL query which will filter contacts based on the conditions
            provided
        contacts_count:
          type: integer
          description: Total number of contacts present in the segment
        contacts_sample:
          type: array
          description: A subset of all contacts that are in this segment
          items:
            $ref: '#/components/schemas/ContactResponse'
        created_at:
          type: string
          description: ISO8601 timestamp of when the object was created
        updated_at:
          type: string
          description: ISO8601 timestamp of when the object was last updated
        sample_updated_at:
          type: string
          description: ISO8601 timestamp of when the samples were last updated
        next_sample_update:
          type: string
          description: ISO8601 timestamp of when the samples will be next updated
        parent_list_ids:
          type: array
          description: The array of list ids to filter contacts on when building this
            segment. It allows only one such list id for now. We will support more
            in future
          uniqueItems: true
          items:
            type: string
        query_version:
          type: string
          description: If not set, segment contains a Query for use with Segment v1
            APIs. If set to '2', segment contains a SQL query for use in v2.
        status:
          $ref: '#/components/schemas/SegmentStatusResponse'
        refreshes_used:
          type: integer
          description: The number of times a segment has been manually refreshed since
            start of today in the user's timezone.
        max_refreshes:
          type: integer
          description: The maximum number of manual refreshes allowed per day for
            this segment. Currently, only 2 are allowed.
        last_refreshed_at:
          type: string
          description: The ISO8601 timestamp when the segment was last refreshed in
            UTC time.
      required:
      - id
      - name
      - query_dsl
      - contacts_count
      - contacts_sample
      - created_at
      - updated_at
      - sample_updated_at
      - next_sample_update
      - parent_list_ids
      - query_version
      - status
    ErrorsSegmentV2:
      title: errors-seg
      type: object
      description: If the request is incorrect, an array of errors will be returned.
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: the field in the request body that is incorrect
              message:
                type: string
                description: a description of what is specifically wrong with the
                  field passed in the request
            required:
            - field
            - message
      required:
      - errors
    SegmentWriteV2:
      title: segment_write
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name of the segment.
        parent_list_ids:
          type: array
          description: The array of list ids to filter contacts on when building this
            segment. It allows only one such list id for now. We will support more
            in future
          uniqueItems: true
          items:
            type: string
        query_dsl:
          type: string
          description: SQL query which will filter contacts based on the conditions
            provided
      required:
      - name
      - query_dsl
    SegmentUpdate:
      title: segment_update
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name of the segment.
        query_dsl:
          type: string
          description: SQL query which will filter contacts based on the conditions
            provided
    ContactResponse:
      title: contact_response
      type: object
      properties:
        id:
          type: string
          maxLength: 36
          pattern: '[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}'
          format: uuid
          description: ID assigned to a contact when added to the system.
        email:
          type: string
          minLength: 3
          maxLength: 254
          format: email
          description: Email of the contact. This is a reserved field.
        phone_number_id:
          type: string
          description: The contact's Phone Number ID. This must be a valid phone number.
        external_id:
          type: string
          description: The contact's External ID.
          maxLength: 254
        anonymous_id:
          type: string
          description: The contact's Anonymous ID.
          maxLength: 254
        alternate_emails:
          type: array
          uniqueItems: true
          minItems: 0
          description: Alternate emails of the contact. This is a reserved field.
          items:
            type: string
            minLength: 3
            maxLength: 254
            format: email
        first_name:
          type: string
          minLength: 1
          description: First name of the contact. This is a reserved field.
        last_name:
          type: string
          minLength: 1
          description: Last name of the contact. This is a reserved field.
        address_line_1:
          type: string
          minLength: 0
          description: First line of address of the contact. This is a reserved field.
        address_line_2:
          type: string
          minLength: 0
          description: Second line of address of the contact. This is a reserved field.
        city:
          type: string
          minLength: 0
          pattern: ^[a-zA-Z\u0080-\u024F\s\/\-\)\(\`\.\"\']+$
          description: City associated with the contact. This is a reserved field.
        state_province_region:
          type: string
          minLength: 0
          description: State associated with the contact. This is a reserved field.
        postal_code:
          type: integer
          description: Zipcode associated with the address of the contact. This is
            a reserved field.
        country:
          type: string
          minLength: 0
          description: Country associated with the address of the contact. This is
            a reserved field.
        list_ids:
          type: array
          uniqueItems: true
          description: IDs of all lists the contact is part of
          items:
            type: string
            format: uuid
        custom_fields:
          type: object
          minProperties: 0
          description: The user may choose to create up to 120 custom fields or none
            at all. This is not a reserved field.
          properties:
            custom_field_name1:
              type: string
              minLength: 0
            custom_field_name2:
              type: string
              minLength: 0
        segment_ids:
          type: array
          uniqueItems: true
          description: IDs of all segments the contact is part of
          items:
            type: string
            format: uuid
      required:
      - id
      - alternate_emails
      - first_name
      - last_name
      - address_line_1
      - address_line_2
      - city
      - state_province_region
      - postal_code
      - country
      - custom_fields
      example:
        id: 47d23ab0-d895-4359-a0d1-ffc7a6fc7e70
        email: abcd@gmail.com
        alternate_emails:
        - abcd@yahoo.com
        - abcd@hotmail.com
        first_name: Ab
        last_name: Cd
        address_line_1: street address / P.O. box / CompanyName / c/o
        address_line_2: apartment, suite, unit, building, floor etc
        city: Redwood City
        state_province_region: CA
        postal_code: 94063
        country: USA
        custom_fields:
          custom_field_name1: custom_field_value1
          custom_field_name2: custom_field_value2
    SegmentError:
      title: error
      required:
      - error
      type: object
      properties:
        error:
          type: string
          description: A description of the error.
  responses: {}
  parameters: {}
  examples: {}
  requestBodies:
    SegmentWriteV2:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SegmentWriteV2'
    SegmentRefresh:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SegmentRefreshRequest'
  headers: {}
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Twilio SendGrid requires you to authenticate with its APIs using
        an API key. The API key must be sent as a bearer token in the Authorization
        header.
tags:
- name: Segmenting Contacts V2
  description: Twilio SendGrid Marketing Campaigns Segments API V2
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid