openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Segmenting Contacts V2 API
  summary: The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts.
  description: 'The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid.


    You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio [SendGrid Subusers](https://docs.sendgrid.com/ui/account-and-settings/subusers) feature, which is available with [Pro and Premier plans](https://sendgrid.com/pricing/).'
  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: account_provisioning
servers:
- url: https://api.sendgrid.com
  description: for global users and subusers
- url: https://api.eu.sendgrid.com
  description: for EU regional subusers
security:
- BearerAuth: []
tags:
- name: Segmenting Contacts V2
  description: Twilio SendGrid Marketing Campaigns Segments API V2
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:
    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
    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
    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
    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
    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
    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
    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
    SegmentError:
      title: error
      required:
      - error
      type: object
      properties:
        error:
          type: string
          description: A description of the error.
    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
    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
    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
  requestBodies:
    SegmentWriteV2:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SegmentWriteV2'
    SegmentRefresh:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SegmentRefreshRequest'
  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.
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid