Twilio Data Mapping API

openapi: 3.2.0
info:
  title: Twilio Memory Data Mapping 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: DataMapping
  description: A Data Mapping connects an external data source to a Memory Store by mapping fields from the data source to Traits in a Trait Group. This allows for the enrichment of profiles with data from external sources, and can be used to sync customer data from a CRM or Warehouse.
paths:
  /v1/ControlPlane/Stores/{storeId}/DataMappings:
    servers:
    - url: https://memory.twilio.com
    parameters:
    - $ref: '#/components/parameters/StoreId'
    x-twilio:
      pathType: list
    get:
      operationId: ListDataMappings
      summary: List Data Mappings
      description: Get a list of data mappings configured for this Memory Store.
      tags:
      - DataMapping
      parameters:
      - $ref: '#/components/parameters/ControlPlanePageSize'
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/OrderBy'
      - name: type
        in: query
        description: Filter data mappings by type.
        required: false
        schema:
          $ref: '#/components/schemas/DataMappingType'
      responses:
        '200':
          description: DataMappings retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataMappingList'
              example:
                dataMappings:
                - id: mem_datamapping_00000000000000000000000000
                  createdAt: '2024-01-01T00:00:00Z'
                  updatedAt: '2024-01-01T00:00:00Z'
                  version: 1
                  displayName: crm-contacts
                  description: Syncs customer data from CRM dataset to profile traits
                  isEnabled: true
                  mappingTo:
                    type: TRAITS
                    mappings:
                    - expression: primary_email
                      traitGroup: Contact
                      traitName: email
                  mappingFrom:
                    type: DATASET_CLOUDAPP
                    datasetId: tdi_dataset_00000000000000000000000000
                meta:
                  key: dataMappings
                  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: CreateDataMapping
      summary: Create a Data Mapping
      description: 'Create a new data mapping to connect an external data source to this Memory Store.

        For `DATASET_CLOUDAPP` and `DATASET_WAREHOUSE` types, validates that all mapped Trait Groups and traits exist

        and that dataset field data types match their respective mapped trait data types.'
      tags:
      - DataMapping
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDataMappingInput'
      responses:
        '202':
          description: Data mapping 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: Data mapping creation request accepted for processing.
                  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'
  /v1/ControlPlane/Stores/{storeId}/DataMappings/{dataMappingId}:
    servers:
    - url: https://memory.twilio.com
    parameters:
    - $ref: '#/components/parameters/StoreId'
    - $ref: '#/components/parameters/DataMappingId'
    x-twilio:
      pathType: instance
    get:
      operationId: FetchDataMapping
      summary: Retrieve a Data Mapping
      description: Retrieve the details of a specific data mapping by its unique ID.
      tags:
      - DataMapping
      responses:
        '200':
          description: Data mapping details retrieved successfully.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataMapping'
        '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: PatchDataMapping
      parameters:
      - $ref: '#/components/parameters/IfMatchHeader'
      summary: Update a Data Mapping
      description: 'Partially update a data mapping. Only the fields provided in the request body will be updated,

        including replacing the entire contents of the `mappings` array.


        For `DATASET_CLOUDAPP` and `DATASET_WAREHOUSE` types, validates that all mapped Trait Groups and traits exist

        and that dataset field data types match their respective mapped trait data types.'
      tags:
      - DataMapping
      requestBody:
        required: true
        content:
          application/json:
            schema:
              minProperties: 1
              allOf:
              - $ref: '#/components/schemas/DataMappingCore'
      responses:
        '202':
          description: Data mapping update 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: Data mapping update request accepted for processing.
                  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: DeleteDataMapping
      summary: Delete a Data Mapping
      description: Delete a data mapping from the Memory Store. This action cannot be undone.
      tags:
      - DataMapping
      responses:
        '202':
          description: Data mapping 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: Data mapping deletion request accepted for processing.
                  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'
components:
  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
  schemas:
    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
    DataMappingFromCloudAppDataSet:
      type: object
      additionalProperties: false
      description: Configuration for mapping from a TDI dataset backed by a cloud app (CRM) source.
      properties:
        type:
          type: string
          description: The source data type, which determines the source of the data and the required configuration parameters.
          enum:
          - DATASET_CLOUDAPP
          example: DATASET_CLOUDAPP
        datasetId:
          type: string
          description: The unique identifier of the TDI dataset to connect.
          pattern: ^tdi_dataset_[0-7][0-9a-z]{25}$
          example: tdi_dataset_00000000000000000000000000
      required:
      - type
      - datasetId
    DataMappingFromTypes:
      type: object
      description: 'Details of where to map data items from. Each data mapping from type has its own set of configuration

        parameters and source specific properties.'
      oneOf:
      - $ref: '#/components/schemas/DataMappingFromIngress'
      - $ref: '#/components/schemas/DataMappingFromCloudAppDataSet'
      - $ref: '#/components/schemas/DataMappingFromWarehouseDataSet'
      discriminator:
        propertyName: type
        mapping:
          INGRESS: '#/components/schemas/DataMappingFromIngress'
          DATASET_CLOUDAPP: '#/components/schemas/DataMappingFromCloudAppDataSet'
          DATASET_WAREHOUSE: '#/components/schemas/DataMappingFromWarehouseDataSet'
      example:
        type: DATASET_WAREHOUSE
        datasetId: tdi_dataset_00000000000000000000000000
    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
    DataMappingFromWarehouseDataSet:
      type: object
      additionalProperties: false
      description: Configuration for mapping from a TDI dataset backed by a warehouse source.
      properties:
        type:
          type: string
          description: The source data type, which determines the source of the data and the required configuration parameters.
          enum:
          - DATASET_WAREHOUSE
          example: DATASET_WAREHOUSE
        datasetId:
          type: string
          description: The unique identifier of the TDI dataset to connect.
          pattern: ^tdi_dataset_[0-7][0-9a-z]{25}$
          example: tdi_dataset_00000000000000000000000000
      required:
      - type
      - datasetId
    DataMappingFromIngress:
      type: object
      additionalProperties: false
      description: Configuration for mapping from ingress column names provided directly in the request.
      properties:
        type:
          type: string
          description: The source data type, which determines the source of the data and the required configuration parameters.
          enum:
          - INGRESS
          example: INGRESS
        columns:
          type: array
          description: The list of ingress column names that serve as the source fields.
          minItems: 1
          maxItems: 100
          items:
            type: string
            minLength: 1
            maxLength: 256
          example:
          - first_name
          - last_name
          - email
          - favorite_color
      required:
      - type
      - columns
    DataMappingToTypes:
      type: object
      description: 'Details of where to map data items to. Each data mapping to type has its own set of configuration

        parameters and destination specific properties.'
      oneOf:
      - $ref: '#/components/schemas/DataMappingToTraits'
      discriminator:
        propertyName: type
        mapping:
          TRAITS: '#/components/schemas/DataMappingToTraits'
      example:
        type: TRAITS
        mappings:
        - expression: primary_email
          traitGroup: Contact
          traitName: email
    DataMappingCore:
      type: object
      description: 'Writable fields of a data mapping. Every field is optional here; the PATCH request body

        wraps this schema and requires at least one. Composed into CreateDataMappingInput via allOf.'
      properties:
        displayName:
          $ref: '#/components/schemas/DataMappingName'
        description:
          type: string
          description: A human readable description of this resource, up to 512 characters.
          minLength: 1
          maxLength: 512
          example: Syncs customer data from CRM dataset to profile traits
        isEnabled:
          type: boolean
          description: 'Flag indicating whether the data mapping is active. When true, data will be

            ingested and mapped according to the configuration. When false, the data mapping

            will be inactive and no data will be ingested into the Memory Store.'
          default: true
          example: true
        mappingTo:
          $ref: '#/components/schemas/DataMappingToTypes'
    DataMappingType:
      type: string
      description: The type of data mapping defining how data flows into the Memory Store.
      enum:
      - INGRESS
      - DATASET_CLOUDAPP
      - DATASET_WAREHOUSE
      example: DATASET_WAREHOUSE
    DataMappingToTraits:
      type: object
      additionalProperties: false
      description: Configuration for mapping data to traits in a Memory Store.
      properties:
        type:
          type: string
          description: The destination data type, which determines where to write the data and the required configuration parameters.
          enum:
          - TRAITS
          default: TRAITS
          example: TRAITS
        mappings:
          type: array
          description: The list of field to trait mappings.
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/MappingTraitItem'
      required:
      - type
      - mappings
    DataMappingName:
      type: string
      description: Name of the data mapping.
      pattern: ^[a-zA-Z][a-zA-Z0-9-.]*$
      minLength: 1
      maxLength: 64
      example: crm-contacts
    MappingTraitItem:
      type: object
      additionalProperties: false
      description: Maps a field from a source to a Trait in the Memory Store.
      properties:
        expression:
          type: string
          description: The expression identifying the field/column in the source.
          minLength: 1
          maxLength: 256
          example: primary_email
        traitGroup:
          type: string
          description: The name of the Trait Group to map to.
          minLength: 1
          maxLength: 64
          pattern: ^[a-zA-Z0-9_\-\.]+$
          example: Contact
        traitName:
          type: string
          description: The name of the trait within the Trait Group to map to.
          minLength: 1
          maxLength: 128
          pattern: ^[a-z][a-zA-Z0-9_\-\.]*$
          example: email
      required:
      - expression
      - traitGroup
      - traitName
    CreateDataMappingInput:
      type: object
      description: 'A data mapping connects external data sources to a Memory Store, enabling automatic

        ingestion and mapping of data to profile traits.'
      properties:
        displayName:
          $ref: '#/components/schemas/DataMappingName'
        description:
          type: string
          description: A human readable description of this resource, up to 512 characters.
          minLength: 1
          maxLength: 512
          example: Syncs customer data from CRM dataset to profile traits
        isEnabled:
          type: boolean
          description: 'Flag indicating whether the data mapping is active. When true, data will be

            ingested and mapped according to the configuration. When false, the data mapping

            will be inactive and no data will be ingested into the Memory Store.'
          default: true
          example: true
        mappingTo:
          $ref: '#/components/schemas/DataMappingToTypes'
        mappingFrom:
          $ref: '#/components/schemas/DataMappingFromTypes'
      required:
      - mappingTo
      - displayName
      - mappingFrom
    DataMapping:
      type: object
      properties:
        displayName:
          $ref: '#/components/schemas/DataMappingName'
        description:
          type: string
          description: A human readable description of this resource, up to 512 characters.
          minLength: 1
          maxLength: 512
          example: Syncs customer data from CRM dataset to profile traits
        isEnabled:
          type: boolean
          description: 'Flag indicating whether the data mapping is active. When true, data will be

            ingested and mapped according to the configuration. When false, the data mapping

            will be inactive and no data will be ingested into the Memory Store.'
          default: true
          example: true
        mappingTo:
          $ref: '#/components/schemas/DataMappingToTypes'
        mappingFrom:
          $ref: '#/components/schemas/DataMappingFromTypes'
        id:
          type: string
          description: The unique identifier for the data mapping.
          pattern: ^mem_datamapping_[0-7][0-9a-z]{25}$
          example: mem_datamapping_00000000000000000000000000
        createdAt:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the  data mapping was created.
          example: '2026-01-15T10:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the data mapping was last updated.
          example: '2026-01-15T11:45:00Z'
        version:
          type: integer
          minimum: 1
          description: The current version number of the DataMapping. Incremented on each successful update.
          example: 3
      required:
      - displayName
      - id
      - mappingTo
      - updatedAt
      - version
      - createdAt
      - mappingFrom
    DataMappingList:
      type: object
      additionalProperties: false
      properties:
        dataMappings:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/DataMapping'
          description: List of DataMappings associated with the Memory Store.
        meta:
          $ref: '#/components/schemas/Meta'
  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
    DataMappingId:
      name: dataMappingId
      in: path
      required: true
      description: A unique DataMapping ID using Twilio Type ID (TTID) format
      schema:
        type: string
        pattern: ^mem_datamapping_[0-7][0-9a-z]{25}$
        example: mem_datamapping_00000000000000000000000000
    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