SendGrid Segmenting Contacts API

openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Segmenting Contacts 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
  description: Twilio SendGrid Marketing Campaigns Segments API
paths:
  /v3/marketing/segments:
    get:
      operationId: ListSegment
      summary: Get List of Segments
      tags:
      - Segmenting Contacts
      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 of list ids to be used when searching for segments with the specified parent_list_id, no more than 50 is allowed
        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'.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    uniqueItems: true
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/SegmentSummary'
                required:
                - results
              examples:
                response:
                  value:
                    results:
                    - id: 12099613-91e5-4d09-a900-df7626325288
                      contacts_count: 78434802
                      created_at: '2921-01-27T19:33:36.479Z'
                      sample_updated_at: '4685-11-26T07:05:04.660Z'
                      updated_at: '2883-07-10T13:13:37.697Z'
                    - id: 60c37015-3734-4c8e-b293-68cfa2ae4fa5
                      contacts_count: 34177253
                      created_at: '2575-07-26T23:17:20.984Z'
                      sample_updated_at: '3074-09-04T09:49:58.127Z'
                      updated_at: '5116-10-15T07:37:40.838Z'
                      parent_list_id: fd38af3d-3f69-4947-8dca-5fa967e7be82
                      name: amet
        '401':
          $ref: '#/components/responses/Segments401'
        '403':
          $ref: '#/components/responses/Segments403'
        '404':
          $ref: '#/components/responses/Segments404'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                      required:
                      - message
                required:
                - errors
  /v3/marketing/segments/{segment_id}:
    parameters:
    - name: segment_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        minLength: 36
        maxLength: 36
    get:
      operationId: GetSegment
      summary: Get Segment by ID
      tags:
      - Segmenting Contacts
      description: '**This endpoint allows you to retrieve a single segment by ID.**'
      parameters:
      - name: query_json
        in: query
        description: Defaults to `false`.  Set to `true` to return the parsed SQL AST as a JSON object in the field `query_json`
        schema:
          type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FullSegment'
              examples:
                response:
                  value:
                    id: 3b049926-0a54-4a91-83f0-086ace63c530
                    contacts_count: -83213117
                    created_at: '2921-01-27T19:33:36.479Z'
                    sample_updated_at: '3407-09-25T04:25:02.140Z'
                    updated_at: '4389-06-21T16:59:51.403Z'
                    contacts_sample:
                    - id: e70eac25-1431-4231-bccd-1cfab432301e
                      email: KLTF@SurgGzlAxCPOqhOUHYNBLsfpfE.trh
                      alternate_emails:
                      - dTeJZgU5uN9UYSo@nfIB.ijxg
                      first_name: ullamco esse culpa do
                      last_name: officia laboris veniam consequat
                      address_line_1: in occaecat labore est tempor
                      address_line_2: magna adipisicing
                      city: ƞó
                      state_province_region: culpa ut
                      postal_code: -75218567
                      country: voluptate in in reprehenderit aliquip
                      custom_fields:
                        custom_field_name1: amet deserunt mollit
                        custom_field_name2: minim consequat id
                    - id: db637d33-bce1-462c-ae9c-91ec4f761de6
                      email: t7N5TjDmKhC0@gfdifW.ua
                      alternate_emails:
                      - gQol@Xcfilli.hc
                      - n4K7OdaVQh@YfsnF.ie
                      - TdnvS3nMStREn@miFjGzNDCPZWhiswJNxrFnOYdUAZEpesQ.yxpu
                      - xRzGDTTzzbYK@eJ.wpgb
                      - iI1rOpx2ct@aZhuYGZBxJLZ.phr
                      first_name: ea et eu
                      last_name: velit Ut laborum ipsu
                      address_line_1: labore
                      address_line_2: non
                      city: "Ĕȸą\x9F¸ȠɏbɄ"
                      state_province_region: deserunt dolore
                      postal_code: -95171713
                      country: do
                      list_ids:
                      - c712288b-2300-4069-bef4-2e05b5948ec3
                      - 9003ef29-5eb7-4951-898b-1b102e490d6e
                      custom_fields:
                        custom_field_name1: amet deserunt mollit
                        custom_field_name2: minim consequat id
                    name: enim et anim
                    query_dsl: nostrud
        '401':
          $ref: '#/components/responses/Segments401'
        '403':
          $ref: '#/components/responses/Segments403'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        field:
                          type: string
                      required:
                      - message
                      - field
                required:
                - errors
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                      required:
                      - message
                required:
                - errors
    delete:
      operationId: DeleteSegment
      summary: Delete Segment
      tags:
      - Segmenting Contacts
      description: '**This endpoint allows you to delete a segment by `segment_id`.**


        Note that deleting a segment does not delete the contacts associated with the segment by default. Contacts associated with a deleted segment will remain in your list of all contacts and any other segments they belong to.'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                type: object
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Segments401'
        '403':
          $ref: '#/components/responses/Segments403'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        field:
                          type: string
                      required:
                      - message
                      - field
                required:
                - errors
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                      required:
                      - message
                required:
                - errors
components:
  responses:
    Segments404:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Segments403:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Segments401:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    SegmentSummary:
      title: segment_summary
      type: object
      properties:
        id:
          type: string
          minLength: 36
          maxLength: 36
          format: uuid
        contacts_count:
          type: integer
        created_at:
          type: string
          description: 'ISO8601 of created timestamp

            '
          format: date-time
        name:
          type: string
          minLength: 1
          maxLength: 100
        parent_list_id:
          type: string
          minLength: 36
          maxLength: 36
          format: uuid
          description: The id of the list if this segment is a child of a list.  This implies the query `AND CONTAINS(list_ids, ${parent_list_id})`
        sample_updated_at:
          type: string
          description: ISO8601 timestamp the sample was last updated
          format: date-time
        updated_at:
          type: string
          description: ISO8601 timestamp the object was last updated
          format: date-time
        next_sample_update:
          type: string
          description: ISO8601 string that is equal to `sample_updated_at` plus an internally calculated offset that depends on how often contacts enter or exit segments as the scheduled pipeline updates the samples.
      required:
      - id
      - contacts_count
      - created_at
      - sample_updated_at
      - updated_at
    FullSegment:
      title: full_segment
      example:
        id: 58567a46-305e-48d1-b4f8-a006c906920e
        contacts_count: 9266921
        created_at: '2085-08-08T21:07:05.692Z'
        sample_updated_at: '3407-09-25T04:25:02.140Z'
        updated_at: '4431-05-07T22:23:22.352Z'
        contacts_sample:
        - id: c1183ada-b784-49ac-9b1f-50e73578a6dc
          email: ft88@d.izxx
          external_id: '1234'
          alternate_emails:
          - yKDUP11FDch@QoU.vwy
          - ZNSN5@czAMqPi.at
          - 7wr51kFVVKlcBSH@DWxOueOZepetzBrku.qosk
          - iib-ObtO7Fxz5@vLJPRIFKPOqJGCEqcIDab.ypn
          first_name: est
          last_name: eiusmod in laboris velit cupidatat
          address_line_1: sunt aliqua
          address_line_2: sit proident Lorem veniam labore
          city: "\x9CȎţȸÛ\tč\vCŁ"
          state_province_region: ut proident
          postal_code: 30296612
          country: do reprehenderit qui
          custom_fields:
            custom_field_name2: in consectetur ut aliqua sint
            custom_field_name1: esse
        name: culpa
        query_dsl: cillum eiusmod
        parent_list_id: 2357714d-3d82-4c80-826c-b44a4147f81c
        next_sample_update: ''
      type: object
      properties:
        id:
          type: string
          minLength: 36
          maxLength: 36
          format: uuid
        contacts_count:
          type: integer
        created_at:
          type: string
          description: 'ISO8601 of created timestamp

            '
          format: date-time
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name of the segment.
        parent_list_id:
          type: string
          minLength: 36
          maxLength: 36
          format: uuid
          description: The id of the list if this segment is a child of a list.  This implies the query `AND CONTAINS(list_ids, ${parent_list_id})`
        sample_updated_at:
          type: string
          description: ISO8601 timestamp the sample was last updated
          format: date-time
        updated_at:
          type: string
          description: ISO8601 timestamp the object was last updated
          format: date-time
        next_sample_update:
          type: string
          description: ISO8601 string that is equal to `sample_updated_at` plus an internally calculated offset that depends on how often contacts enter or exit segments as the scheduled pipeline updates the samples.
        contacts_sample:
          type: array
          items:
            $ref: '#/components/schemas/ContactResponse'
        query_json:
          type: object
          description: AST representation of the query DSL
        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:
      - contacts_count
      - contacts_sample
      - created_at
      - id
      - name
      - query_dsl
      - sample_updated_at
      - updated_at
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: An error message.
              field:
                description: When applicable, this property value will be the field that generated the error.
                nullable: true
                type: string
              help:
                type: object
                description: When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error.
        id:
          type: string
          description: When applicable, this property value will be an error ID.
      example:
        errors:
        - field: field_name
          message: error message
    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
  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