Twilio Identifiers API

openapi: 3.2.0
info:
  title: Twilio Memory Identifiers 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: Identifiers
  description: Every customer interaction must be attached to the correct profile.
paths:
  /v1/Stores/{storeId}/Profiles/{profileId}/Identifiers:
    servers:
    - url: https://memory.twilio.com
    parameters:
    - $ref: '#/components/parameters/StoreId'
    - $ref: '#/components/parameters/ProfileId'
    x-twilio:
      defaultOutputProperties:
      - identifiers
      pathType: list
    get:
      operationId: ListProfileIdentifiers
      summary: List Profile Identifiers
      description: Retrieve all identifier types linked to a profile along with their stored values. Use this to audit which external keys (phone, email, externalId, etc.) are currently associated. Values are returned in the order enforced by each identifier settings `limitPolicy` and reflect any normalization applied by the service.
      tags:
      - Identifiers
      responses:
        '200':
          description: A list of identifiers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifiers:
                    type: array
                    maxItems: 50
                    items:
                      $ref: '#/components/schemas/IdentifierSet'
        '301':
          $ref: '#/components/responses/MovedPermanently'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: CreateProfileIdentifier
      summary: Add Profile Identifier
      description: Asynchronously attach a new identifier value to a profile. When multiple values exist for an `idType`, ordering, limits, and uniqueness checks are enforced by the corresponding identifier settings `limitPolicy` and reflect any normalization. If the identifier already exists and points to another profile, resolution rules or merge processes may apply. Use the identifier specific endpoint to inspect, update, or remove existing values.
      tags:
      - Identifiers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Identifier'
            example:
              idType: phone
              value: '+13175556789'
      responses:
        '202':
          description: Identifier association accepted.
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
                    maxLength: 512
                    example: Identifier accepted for processing.
              examples:
                Accepted:
                  value:
                    message: Identifier accepted for processing.
        '308':
          $ref: '#/components/responses/PermanentRedirect'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/Stores/{storeId}/Profiles/{profileId}/Identifiers/{idType}:
    servers:
    - url: https://memory.twilio.com
    parameters:
    - $ref: '#/components/parameters/StoreId'
    - $ref: '#/components/parameters/ProfileId'
    - $ref: '#/components/parameters/IdentifierType'
    x-twilio:
      pathType: instance
    get:
      operationId: FetchProfileIdentifier
      summary: Retrieve Profile Identifier
      description: Retrieve all stored values for a specific identifier type on a profile. Values are normalized according to the configured identifier settings and returned in the order determined by its `limitPolicy`.
      tags:
      - Identifiers
      responses:
        '200':
          description: Identifier values associated with the requested type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentifierSet'
        '301':
          $ref: '#/components/responses/MovedPermanently'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: PatchProfileIdentifier
      summary: Modify Profile Identifier
      description: 'Asynchronously replace one of the stored values associated with the

        identifier type on a profile. `newValue` is normalized according to

        the configured identifier settings.


        If the new identifier already exists and points to another profile,

        merge processes may apply.'
      tags:
      - Identifiers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifierUpdate'
            example:
              idType: phone
              oldValue: '+13175556789'
              newValue: '+13175556798'
      responses:
        '202':
          description: Identifier update accepted.
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
                    maxLength: 512
                    example: Identifier update accepted.
              examples:
                Accepted:
                  value:
                    message: Identifier update accepted.
        '308':
          $ref: '#/components/responses/PermanentRedirect'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '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'
    delete:
      operationId: DeleteProfileIdentifier
      summary: Remove Profile Identifier
      description: Asynchronously remove stored values for the identifier type. The optional `removeAll` query parameter allows bulk removal; otherwise the service selects a single value to delete using the identifier settings `limitPolicy`.
      tags:
      - Identifiers
      parameters:
      - name: removeAll
        in: query
        required: false
        description: When true, removes every stored value for the identifier type in a single operation. Defaults to false.
        schema:
          type: boolean
          default: false
      responses:
        '202':
          description: Identifier removal accepted.
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
                    maxLength: 512
                    example: Identifier removal accepted.
              examples:
                Accepted:
                  value:
                    message: Identifier removal accepted.
        '308':
          $ref: '#/components/responses/PermanentRedirect'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  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
    Identifier:
      type: object
      additionalProperties: false
      required:
      - idType
      - value
      description: Represents a single identifier value paired with its `idType`. Write operations obey limits, uniqueness, and normalization rules configured via identifier settings.
      properties:
        idType:
          type: string
          description: Identifier type as configured in the service's Identity Resolution Settings.
          minLength: 2
          maxLength: 30
          example: phone
        value:
          type: string
          description: Raw value captured for the identifier. The service may normalize this value according to the `normalization` rule defined in the identifier settings before storage or matching (for example E.164 formatting for phone numbers).
          maxLength: 255
          example: '+13175556789'
    IdentifierSet:
      type: object
      additionalProperties: false
      required:
      - idType
      - values
      description: All the known values for a specific identifier type. These are normalized according to the corresponding identifier settings and ordered chronologically. It includes any promoted values from traits and explicitly set values from API calls, both historical and current.
      properties:
        idType:
          type: string
          description: Identifier type defined in Identity Resolution Settings.
          minLength: 2
          maxLength: 30
          example: email
        values:
          type: array
          maxItems: 100
          description: Server managed collection of stored values for the identifier type.  Identifier values are normalized according to the corresponding identifier settings and ordered chronologically.
          items:
            type: string
            maxLength: 255
          example:
          - primary@example.com
          - backup@example.com
    IdentifierUpdate:
      type: object
      additionalProperties: false
      required:
      - idType
      - oldValue
      - newValue
      properties:
        idType:
          type: string
          description: The identifier type to update (e.g., email, phone).
          minLength: 2
          maxLength: 30
          example: phone
        oldValue:
          type: string
          description: Existing stored value to replace.
          maxLength: 255
          example: '+13175556789'
        newValue:
          type: string
          description: New value to store for the identifier. Normalization rules from the corresponding identifier settings apply.
          maxLength: 255
          example: '+13175556798'
  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
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 403
            message: Permission to access resource denied
            more_info: https://www.twilio.com/docs/api/errors/403
            status: 403
    PermanentRedirect:
      description: This resource has moved.
      content:
        application/json:
          schema:
            type: object
            required:
            - message
            - uri
            properties:
              message:
                type: string
                default: This resource has moved.
                example: This resource has moved.
                maxLength: 255
              uri:
                type: string
                example: https://memory.twilio.com/v1/Stores/mem_store_00000000000000000000000000/Profiles/mem_profile_00000000000000000000000000
                maxLength: 2048
            maxProperties: 2
      headers:
        Canonical-Profile-Id:
          $ref: '#/components/headers/Canonical-Profile-Id'
        Location:
          $ref: '#/components/headers/Location'
    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
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20003
            message: Failed to complete request due to lack of authentication credentials
            more_info: https://www.twilio.com/docs/api/errors/20003
            status: 401
    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]+$
    MovedPermanently:
      description: This resource has moved.
      content:
        application/json:
          schema:
            type: object
            required:
            - message
            - uri
            properties:
              message:
                type: string
                default: This resource has moved.
                example: This resource has moved.
                maxLength: 255
              uri:
                type: string
                example: https://memory.twilio.com/v1/Stores/mem_store_00000000000000000000000000/Profiles/mem_profile_00000000000000000000000000
                maxLength: 2048
            maxProperties: 2
      headers:
        Canonical-Profile-Id:
          $ref: '#/components/headers/Canonical-Profile-Id'
        Location:
          $ref: '#/components/headers/Location'
    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
  headers:
    Location:
      description: The URL of the new location for the resource.
      schema:
        type: string
        format: uri
        example: https:///memory.twilio.com/v1/Stores/mem_store_00000000000000000000000000/Profiles/mem_profile_00000000000000000000000000
        description: The URL of the new location for the resource.
    Canonical-Profile-Id:
      description: The canonical profile ID associated with the requested resource. If provided, this header indicates that the requested profile is merged to the canonical profile ID.
      schema:
        type: string
        pattern: ^mem_profile_[0-7][0-9a-z]{25}$
        example: mem_profile_00000000000000000000000000
        description: The canonical profile ID.
  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
    ProfileId:
      name: profileId
      in: path
      required: true
      description: The unique identifier for the profile using Twilio Type ID (TTID) format.
      schema:
        type: string
        pattern: ^mem_profile_[0-7][0-9a-z]{25}$
        example: mem_profile_00000000000000000000000000
    IdentifierType:
      name: idType
      in: path
      required: true
      description: Identifier type configured for the service (for example `email`, `phone`, or `externalId`).
      schema:
        type: string
        minLength: 2
        maxLength: 30
        example: email
  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