Twilio Trait Group API

openapi: 3.2.0
info:
  title: Twilio Memory Trait Group API
  description: APIs for managing memory stores, profiles, and conversational intelligence capabilities.
  version: '1.0'
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio Support
    url: https://support.twilio.com
    email: support@twilio.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-twilio:
    apiStandards: v1.0
servers:
- url: https://memory.twilio.com
security:
- accountSid_authToken: []
tags:
- name: TraitGroup
  description: 'Trait Groups are the organized containers used to group related facts about a profile, such as contact details or account preferences. Trait schemas within each Trait Group must be defined before customer information is ingested into profiles.


    Out-of-the-box trait groups like "Contacts" are available by default to help store identity information consistently across channels. Custom groups can also be created to store industry-specific information or satisfy unique business needs.'
paths:
  /v1/ControlPlane/Stores/{storeId}/TraitGroups:
    servers:
    - url: https://memory.twilio.com
    parameters:
    - $ref: '#/components/parameters/StoreId'
    x-twilio:
      defaultOutputProperties:
      - traitGroups
      pathType: list
    get:
      operationId: ListTraitGroups
      summary: List Trait Groups
      description: Returns a list of Trait Groups for this Memory Store, with optional traits information.
      tags:
      - TraitGroup
      parameters:
      - name: includeTraits
        in: query
        description: Whether to include trait definitions in the response
        required: false
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/ControlPlanePageSize'
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/OrderBy'
      responses:
        '200':
          description: List of TraitGroups retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  traitGroups:
                    type: array
                    maxItems: 50
                    items:
                      $ref: '#/components/schemas/TraitGroup'
                  meta:
                    $ref: '#/components/schemas/Meta'
              example:
                traitGroups:
                - displayName: Contact
                  description: Traits related to contact information.
                  traits:
                    email:
                      dataType: STRING
                      description: User's email address
                    dob:
                      dataType: STRING
                      description: User's date of birth
                  version: 1
                meta:
                  key: traitGroups
                  pageSize: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: CreateTraitGroup
      summary: Create a Trait Group
      description: Creates a Trait Group with declarative trait schemas for this Memory Store.
      tags:
      - TraitGroup
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TraitGroupRequest'
            examples:
              Basic Traits:
                value:
                  displayName: Contact
                  description: Traits related to contact information.
                  traits:
                    email:
                      dataType: STRING
                      description: User's email address
                    dob:
                      dataType: STRING
                      description: User's date of birth
              All Trait Types:
                value:
                  displayName: mixedTraits
                  description: Demonstrates string, number, boolean, and array traits.
                  traits:
                    email:
                      dataType: STRING
                      description: User's email address
                      validationRule:
                        ruleType: STRING
                        pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
                        minLength: 5
                        maxLength: 254
                    age:
                      dataType: NUMBER
                      description: User's age in years
                      validationRule:
                        ruleType: NUMBER
                        min: 0
                        max: 150
                    isSubscribed:
                      dataType: BOOLEAN
                      description: Whether user is subscribed to newsletter
                      validationRule:
                        ruleType: BOOLEAN
                    favoriteColors:
                      dataType: ARRAY
                      description: List of user's favorite colors
                      validationRule:
                        ruleType: ARRAY
                        minItems: 1
                        maxItems: 10
              With Validation Rules:
                value:
                  displayName: validatedTraits
                  description: Demonstrates traits that include validation metadata.
                  traits:
                    email:
                      dataType: STRING
                      description: User's email address
                      validationRule:
                        ruleType: STRING
                        pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
                        minLength: 5
                        maxLength: 254
                    age:
                      dataType: NUMBER
                      description: User's age in years
                      validationRule:
                        ruleType: NUMBER
                        min: 0
                        max: 150
                    isSubscribed:
                      dataType: BOOLEAN
                      description: Whether user is subscribed to newsletter
                      validationRule:
                        ruleType: BOOLEAN
                    favoriteColors:
                      dataType: ARRAY
                      description: List of user's favorite colors
                      validationRule:
                        ruleType: ARRAY
                        minItems: 1
                        maxItems: 10
      responses:
        '202':
          description: TraitGroup creation request accepted.
          headers:
            Operation-Id:
              $ref: '#/components/headers/OperationId'
            Location:
              $ref: '#/components/headers/OperationLocation'
            Retry-After:
              $ref: '#/components/headers/OperationRetryAfter'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  message:
                    type: string
                    maxLength: 512
                    example: TraitGroup creation request accepted.
                  statusUrl:
                    type: string
                    description: URI to check operation status.
                    maxLength: 512
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/ControlPlane/Stores/{storeId}/TraitGroups/{traitGroupName}:
    servers:
    - url: https://memory.twilio.com
    parameters:
    - $ref: '#/components/parameters/StoreId'
    - $ref: '#/components/parameters/traitGroupName'
    x-twilio:
      defaultOutputProperties:
      - traitGroup
      - meta
      pathType: instance
    get:
      operationId: FetchTraitGroup
      summary: Retrieve a Trait Group
      description: Retrieve a specific Trait Group by its unique name for this Memory Store, with optional traits information.
      tags:
      - TraitGroup
      parameters:
      - name: includeTraits
        in: query
        description: Whether to include trait definitions in the response
        required: false
        schema:
          type: boolean
          default: true
      - $ref: '#/components/parameters/ControlPlanePageSize'
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/OrderBy'
      responses:
        '200':
          description: TraitGroup retrieved successfully
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                type: object
                properties:
                  traitGroup:
                    $ref: '#/components/schemas/TraitGroup'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: PatchTraitGroup
      parameters:
      - $ref: '#/components/parameters/IfMatchHeader'
      summary: Update Trait Group
      description: 'Partially updates a Trait Group. Only the fields provided in the request body will be updated. For traits:

        existing traits with matching keys will be updated, new keys will be added. To remove a trait, set its dataType to

        an empty string ("") - this serves as an explicit deletion marker.'
      tags:
      - TraitGroup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              minProperties: 1
              properties:
                description:
                  type: string
                  maxLength: 1024
                  description: Updated description of the Trait Group
                  example: Updated Trait Group contains traits related to contact information.
                traits:
                  type: object
                  description: 'Map of traits to add, update, or remove in this Trait Group, where the key is the trait name. - To update/add a trait: provide the complete TraitDefinition object - To remove a trait: set dataType to an empty string ("")'
                  additionalProperties:
                    $ref: '#/components/schemas/TraitDefinition'
                  maxProperties: 95
            examples:
              Update Traits:
                value:
                  description: Update loyalty-related traits.
                  traits:
                    phone:
                      dataType: STRING
                      description: User's phone number
                    loyaltyPoints:
                      dataType: NUMBER
                      description: User's accumulated loyalty points
              Add and Delete Traits:
                value:
                  description: Demonstrates adding and removing traits in one request.
                  traits:
                    addThisTrait:
                      dataType: STRING
                      description: Example of trait definition being added
                    removeThisTrait:
                      dataType: ''
              With Validation Rules:
                value:
                  description: Updates traits while enforcing validation rules.
                  traits:
                    phone:
                      dataType: STRING
                      description: User's phone number
                      validationRule:
                        ruleType: STRING
                        pattern: ^\+?[1-9]\d{1,16}$
                        minLength: 10
                        maxLength: 17
                    loyaltyPoints:
                      dataType: NUMBER
                      description: User's accumulated loyalty points
                      validationRule:
                        ruleType: NUMBER
                        min: 0
                        max: 1000000
                    tags:
                      dataType: ARRAY
                      description: User tags for segmentation
                      validationRule:
                        ruleType: ARRAY
                        minItems: 0
                        maxItems: 20
      responses:
        '202':
          description: TraitGroup update request accepted for processing.
          headers:
            Operation-Id:
              $ref: '#/components/headers/OperationId'
            Location:
              $ref: '#/components/headers/OperationLocation'
            Retry-After:
              $ref: '#/components/headers/OperationRetryAfter'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  message:
                    type: string
                    maxLength: 512
                    example: TraitGroup update request accepted.
                  statusUrl:
                    type: string
                    description: URI to check operation status.
                    maxLength: 512
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: DeleteTraitGroup
      summary: Delete a Trait Group
      description: Deletes the Trait Group and all associated Traits from the Memory Store.
      tags:
      - TraitGroup
      responses:
        '202':
          description: TraitGroup deletion request accepted.
          headers:
            Operation-Id:
              $ref: '#/components/headers/OperationId'
            Location:
              $ref: '#/components/headers/OperationLocation'
            Retry-After:
              $ref: '#/components/headers/OperationRetryAfter'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  message:
                    type: string
                    maxLength: 512
                    example: TraitGroup deletion request accepted.
                  statusUrl:
                    type: string
                    description: URI to check operation status.
                    maxLength: 512
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    TraitDefinition:
      type: object
      additionalProperties: false
      description: A Trait is a single attribute or characteristic of a profile, such as age, location, or preferences.
      properties:
        dataType:
          type: string
          description: 'Data type of the Trait, such as STRING, NUMBER, BOOLEAN, ARRAY.

            For DELETE operations in PATCH requests, set this to an empty string ("") to mark the trait for deletion.'
          example: STRING
          enum:
          - STRING
          - NUMBER
          - BOOLEAN
          - ARRAY
          - ''
        description:
          type: string
          maxLength: 1024
          description: Description of the Trait, providing additional context or information.
          example: The user's primary email address
        validationRule:
          $ref: '#/components/schemas/ValidationRule'
        idTypePromotion:
          type: string
          maxLength: 30
          description: 'The name of the identifier type to promote the trait value to, such as ''''email'''', ''''phone'''', ''''user_id'''',

            etc. This allows the trait to be mapped to an identifier in Identity Resolution. The identifier type should be

            configured in the Identity Resolution Settings.'
          example: email
      required:
      - dataType
    TwilioError:
      type: object
      additionalProperties: false
      maxProperties: 10
      description: A generic error object communicating client and server side API errors.
      properties:
        code:
          type: integer
          minimum: 100
          maximum: 999999
          description: The Twilio error code.
          format: int32
        message:
          type: string
          maxLength: 1024
          description: A human readable message describing the error.
        more_info:
          type: string
          description: A URL to a [Twilio error directory](https://www.twilio.com/docs/api/errors) page with more information about the error code.
        status:
          type: integer
          minimum: 100
          maximum: 599
          description: The HTTP status code for the error.
          format: int32
      example:
        code: 21614
        message: The address specified in the request is not a valid phone number.
        more_info: https://www.twilio.com/docs/api/errors/21614
        status: 400
    TraitGroup:
      type: object
      properties:
        displayName:
          type: string
          description: Provides a unique and addressable name to be assigned to this Trait Group
          minLength: 1
          maxLength: 64
          pattern: ^[a-zA-Z0-9_\-\.]+$
          example: Contact
        description:
          type: string
          maxLength: 1024
          description: description of the Trait Group
          example: This Trait Group contains traits related to contact information.
        traits:
          type: object
          description: Map of traits that are part of this Trait Group, where the key is the trait name and the value is the trait's definition.
          additionalProperties:
            type: object
            title: TraitGroupCoreTraits
            additionalProperties: false
            description: A Trait is a single attribute or characteristic of a profile, such as age, location, or preferences.
            properties:
              dataType:
                type: string
                description: 'Data type of the Trait, such as STRING, NUMBER, BOOLEAN, ARRAY.

                  For DELETE operations in PATCH requests, set this to an empty string ("") to mark the trait for deletion.'
                example: STRING
                enum:
                - STRING
                - NUMBER
                - BOOLEAN
                - ARRAY
                - ''
              description:
                type: string
                maxLength: 1024
                description: Description of the Trait, providing additional context or information.
                example: The user's primary email address
              validationRule:
                $ref: '#/components/schemas/ValidationRule'
              idTypePromotion:
                type: string
                maxLength: 30
                description: 'The name of the identifier type to promote the trait value to, such as ''''email'''', ''''phone'''', ''''user_id'''',

                  etc. This allows the trait to be mapped to an identifier in Identity Resolution. The identifier type should be

                  configured in the Identity Resolution Settings.'
                example: email
            required:
            - dataType
          maxProperties: 95
          example:
            email:
              dataType: STRING
              description: User's email address
            dob:
              dataType: STRING
              description: User's date of birth
        version:
          type: integer
          minimum: 1
          description: The current version number of the Trait Group. Incremented on each successful update.
          example: 3
      required:
      - version
      - displayName
    TraitGroupRequest:
      type: object
      additionalProperties: false
      description: Payload schema for creating Trait Groups.
      properties:
        displayName:
          type: string
          description: Unique name of the Trait Group
          minLength: 1
          maxLength: 64
          pattern: ^[a-zA-Z0-9_\-\.]+$
          example: Contact
        description:
          type: string
          maxLength: 1024
          description: description of the Trait Group
          example: This Trait Group contains traits related to contact information.
        traits:
          type: object
          description: Map of traits belonging to this Trait Group, keyed by trait name.
          additionalProperties:
            type: object
            additionalProperties: false
            description: A Trait is a single attribute or characteristic of a profile, such as age, location, or preferences.
            title: TraitGroupRequestTraits
            properties:
              dataType:
                type: string
                description: 'Data type of the Trait, such as STRING, NUMBER, BOOLEAN, ARRAY.

                  For DELETE operations in PATCH requests, set this to an empty string ("") to mark the trait for deletion.'
                example: STRING
                enum:
                - STRING
                - NUMBER
                - BOOLEAN
                - ARRAY
                - ''
              description:
                type: string
                maxLength: 1024
                description: Description of the Trait, providing additional context or information.
                example: The user's primary email address
              validationRule:
                $ref: '#/components/schemas/ValidationRule'
              idTypePromotion:
                type: string
                maxLength: 30
                description: 'The name of the identifier type to promote the trait value to, such as ''''email'''', ''''phone'''', ''''user_id'''',

                  etc. This allows the trait to be mapped to an identifier in Identity Resolution. The identifier type should be

                  configured in the Identity Resolution Settings.'
                example: email
            required:
            - dataType
          maxProperties: 95
          example:
            email:
              dataType: STRING
              description: User's email address
            dob:
              dataType: STRING
              description: User's date of birth
      required:
      - displayName
    ValidationRule:
      oneOf:
      - $ref: '#/components/schemas/StringValidationRule'
      - $ref: '#/components/schemas/NumberValidationRule'
      - $ref: '#/components/schemas/BooleanValidationRule'
      - $ref: '#/components/schemas/ArrayValidationRule'
      discriminator:
        propertyName: ruleType
        mapping:
          STRING: '#/components/schemas/StringValidationRule'
          NUMBER: '#/components/schemas/NumberValidationRule'
          BOOLEAN: '#/components/schemas/BooleanValidationRule'
          ARRAY: '#/components/schemas/ArrayValidationRule'
    Meta:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
          maxLength: 64
          description: 'The key of the list property contains the actual data items.

            This enables programmatic iteration over paginated results.

            '
        pageSize:
          type: integer
          description: The number of items returned in this page of results.
        nextToken:
          type: string
          maxLength: 4096
          example: eyJlYXN0ZXIiOiJlZ2cifQ
        previousToken:
          type: string
          maxLength: 4096
          example: eyJlYXN0ZXIiOiJlZ2cifQ
    StringValidationRule:
      type: object
      description: Validation for string dataType.
      properties:
        pattern:
          type: string
          description: Regex pattern (max 1000 chars)
          maxLength: 1000
        minLength:
          type: integer
          description: Minimum string length
          minimum: 0
        maxLength:
          type: integer
          description: Maximum string length
          minimum: 1
        ruleType:
          type: string
          description: Discriminator field indicating this is a string validation rule.
          enum:
          - STRING
      additionalProperties: false
      required:
      - ruleType
    ArrayValidationRule:
      type: object
      description: Validation for array dataType.
      properties:
        minItems:
          type: integer
          description: Minimum number of items
          minimum: 0
        maxItems:
          type: integer
          description: Maximum number of items
          minimum: 0
        ruleType:
          type: string
          description: Discriminator field indicating this is an array validation rule.
          enum:
          - ARRAY
      additionalProperties: false
      required:
      - ruleType
    BooleanValidationRule:
      type: object
      description: Validation for boolean dataType (no extra properties)
      additionalProperties: false
      properties:
        ruleType:
          type: string
          description: Discriminator field indicating this is a boolean validation rule.
          enum:
          - BOOLEAN
      required:
      - ruleType
    NumberValidationRule:
      type: object
      description: Validation for number dataType.
      properties:
        min:
          type: number
          description: Minimum value
        max:
          type: number
          description: Maximum value
        ruleType:
          type: string
          description: Discriminator field indicating this is a number validation rule.
          enum:
          - NUMBER
      additionalProperties: false
      required:
      - ruleType
  headers:
    OperationId:
      description: The operation identifier.
      schema:
        type: string
        maxLength: 512
    OperationLocation:
      description: URI to check operation status.
      schema:
        type: string
        maxLength: 512
    OperationRetryAfter:
      description: Suggested number of seconds to wait before checking status again.
      schema:
        type: integer
    ETag:
      description: 'Entity tag that acts as a unique identifier for a specific version of the resource.

        Send updates with If-Match conditional headers for optimistic concurrency control.'
      schema:
        type: string
        maxLength: 512
      example: eyJpZCI6ImFuX2lkIiwidiI6MX0
  responses:
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20500
            message: Internal Server Error
            more_info: https://www.twilio.com/docs/api/errors/20500
            status: 500
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20404
            message: Not Found
            more_info: https://www.twilio.com/docs/api/errors/20404
            status: 404
    ServiceUnavailable:
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20503
            message: Service Unavailable
            more_info: https://www.twilio.com/docs/api/errors/20503
            status: 503
    TooManyRequests:
      description: This error indicates that you have sent too many requests to the API. You should retry according to the `Retry-After` response header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20429
            message: Too many requests. Please retry according to the Retry-After response header.
            more_info: https://www.twilio.com/docs/api/errors/20429
            status: 429
      headers:
        Retry-After:
          description: The amount of time in seconds that the customer should wait before issuing a new request towards the API.
          schema:
            type: string
            pattern: ^[0-9]+$
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 400
            message: Failed to complete request due to a bad request
            more_info: https://www.twilio.com/docs/api/errors/400
            status: 400
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20409
            message: Conflict
            more_info: https://www.twilio.com/docs/api/errors/20409
            status: 409
  parameters:
    StoreId:
      name: storeId
      in: path
      required: true
      description: A unique Memory Store ID using Twilio Type ID (TTID) format
      schema:
        type: string
        pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$
        example: mem_store_00000000000000000000000000
    IfMatchHeader:
      in: header
      name: If-Match
      description: 'Allows for optimistic concurrency control by making the request conditional.

        Server will only act if the resource''s current Entity Tag (ETag) matches

        the one provided, preventing accidental overwrites.'
      schema:
        type: string
        maxLength: 100
        example: '"eyJpZCI6ImFuX2lkIiwidiI6MX0"'
    PageToken:
      name: pageToken
      in: query
      required: false
      description: The token for the page of results to retrieve.
      schema:
        type: string
        maxLength: 4096
    traitGroupName:
      name: traitGroupName
      in: path
      required: true
      description: A unique Name of the TraitGroup
      schema:
        type: string
        minLength: 1
        maxLength: 64
        example: Contact
    OrderBy:
      name: orderBy
      in: query
      required: false
      description: Either 'ASC' or 'DESC' to sort results ascending or descending respectively.
      schema:
        type: string
        enum:
        - ASC
        - DESC
        default: DESC
    ControlPlanePageSize:
      name: pageSize
      in: query
      required: false
      description: The maximum number of items to return per page, maximum of 100.
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 100
  securitySchemes:
    basic_apikey_or_accountsid:
      scheme: basic
      type: http
      description: This API uses [basic authentication](https://www.twilio.com/docs/glossary/what-is-basic-authentication). Use an [API key](https://www.twilio.com/docs/iam/api-keys) as the username and the API key secret as the password. You can also use your account SID and auth token, but limit their use to local testing.
    accountSid_authToken:
      scheme: basic
      type: http