openapi: 3.2.0
info:
  title: Twilio Memory Identity Resolution Settings 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: IdentityResolutionSettings
  description: The Identity Resolution Settings endpoints allow you to define and manage the logic used to identify, merge, and resolve customer profiles within a specific Memory Store.
paths:
  /v1/ControlPlane/Stores/{storeId}/IdentityResolutionSettings:
    servers:
    - url: https://memory.twilio.com
    parameters:
    - $ref: '#/components/parameters/StoreId'
    x-twilio:
      defaultOutputProperties:
      - identifierConfigs
      - matchingRules
      pathType: list
    get:
      operationId: FetchIdentityResolutionSettings
      summary: Retrieve Identity Resolution Settings
      description: 'These settings determine how Customer Memory will use identifiers for searching, merging, and resolving profiles.

        > Some settings can only take on their default values and are not yet available to change, but coming soon.'
      tags:
      - IdentityResolutionSettings
      responses:
        '200':
          description: Identity resolution settings retrieved successfully
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityResolutionSettings'
              example:
                identifierConfigs:
                - idType: email
                  matchingAlgo: exact
                  normalization: email
                  enforceUnique: true
                - idType: whatsapp
                  matchingAlgo: exact
                  normalization: trim
                  enforceUnique: true
                - idType: phone
                  matchingAlgo: exact
                  normalization: phone
                  enforceUnique: true
                matchingRules:
                - email
                - whatsapp
                - phone
                version: 3
        '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'
    put:
      operationId: UpdateIdentityResolutionSettings
      parameters:
      - $ref: '#/components/parameters/IfMatchHeader'
      summary: Update Identity Resolution Settings
      description: 'Update the identity resolution settings for this memory store, which

        determine how Customer Memory will use identifiers for searching,

        merging, and resolving profiles.'
      tags:
      - IdentityResolutionSettings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityResolutionSettingsCore'
            examples:
              Basic Configuration:
                value:
                  identifierConfigs:
                  - idType: email
                    matchingAlgo: exact
                    normalization: email
                    enforceUnique: true
                  - idType: whatsapp
                    matchingAlgo: exact
                    normalization: trim
                    enforceUnique: true
                  - idType: phone
                    matchingAlgo: exact
                    normalization: phone
                    enforceUnique: true
                  matchingRules:
                  - email
                  - whatsapp
                  - phone
      responses:
        '202':
          description: Identity Resolution Settings 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: Identity Resolution Settings accepted for processing.
                  statusUrl:
                    type: string
                    description: URI to check operation status.
                    maxLength: 512
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    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"'
    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
  responses:
    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]+$
    PreconditionFailed:
      description: Precondition Failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20412
            message: Precondition Failed
            more_info: https://www.twilio.com/docs/api/errors/20412
            status: 412
    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
    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
  schemas:
    IdentityResolutionSettings:
      type: object
      properties:
        identifierConfigs:
          type: array
          minItems: 1
          maxItems: 15
          description: List of identifier types and their resolution settings.
          items:
            $ref: '#/components/schemas/IdentifierConfig'
        matchingRules:
          type: array
          minItems: 1
          maxItems: 15
          example:
          - email
          - whatsapp
          - phone
          description: "Priority list of identifiers to locate profiles to apply new data to, or for determining if two existing profiles should merge. \n\nIndividual rules are evaluated with `OR` logic between them, meaning that satisfying any single rule will trigger a match. Each rule is a single identifier type; compound rules are not supported.\n\nRules are evaluated in order.\n- If no rule matches against existing profiles, a new profile will be created. \n- If a rule matches to a single existing profile, the profile will be updated. \n- If a rule matches to multiple existing profiles, those existing profiles will be merged."
          items:
            type: string
            maxLength: 30
            description: Name of a single identifier type, such as "email" or "phone". Compound rules (e.g. joining identifiers with `AND`) are not supported.
        version:
          type: integer
          minimum: 1
          description: The current version number of the Identity Resolution Settings. Incremented on each successful update.
          example: 3
      required:
      - matchingRules
      - version
      - identifierConfigs
    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
    IdentifierConfig:
      type: object
      additionalProperties: false
      required:
      - idType
      properties:
        idType:
          type: string
          description: Name of the identifier type. Usual values are email, phone, external_id etc.
          example: email
          minLength: 2
          maxLength: 30
        matchingAlgo:
          type: string
          description: "The algorithm to use for matching identifier values. \n  - `exact`, exact string match.\n  - `fuzzy`, low precision match allowing for some variations."
          enum:
          - exact
          - fuzzy
          default: exact
        matchingThreshold:
          type: integer
          description: The `fuzzy` matching threshold percentage.
          minimum: 50
          maximum: 99
          default: 75
        limit:
          type: integer
          description: Maximum number of historical values to retain.
          minimum: 1
          maximum: 100
          default: 100
        limitPolicy:
          type: string
          enum:
          - fifo
          - lifo
          description: 'Removal policy to apply when the number of values exceeds the limit and

            is based on the timestamp of the request when the identifier was added.

            - `fifo`: First In First Out, removes the oldest values first.

            - `lifo`: Last In First Out, removes the most recent values first.'
          default: fifo
          example: fifo
        enforceUnique:
          type: boolean
          description: 'When enabled, more than one profile may not share the same identifier value.

            Adding a shared identifier to a second profile may trigger a merge.

            Disabling creates a compound identifier where merges are only triggered if

            two or more identifiers satisfy a matching rule.'
          default: true
          example: true
        normalization:
          type: string
          enum:
          - phone
          - email
          - trim
          - none
          description: 'Normalization to apply to the identifier value before storing and matching.

            - `phone`: Normalize phone numbers to E.164 format.

            - `email`: Normalize email addresses by coverting to lowercase and removing spaces.

            - `trim`: Removes spaces from both ends of the string.

            - `none`: No normalization.


            **Important Note for Phone Number Normalization:**

            When using the `phone` normalization option, please adhere to the following guidelines to ensure proper formatting:

            - All US numbers must be at least valid 10 digit phone numbers with area code. They may also include or omit the "+1" prefix.

            - Non-US numbers must include a 1-3 digit country code (a "+" prefix is optional). Non-US national formats are not supported and will be interpreted as US numbers.'
          default: trim
          example: email
    IdentityResolutionSettingsCore:
      type: object
      description: 'Identity Resolution settings help determine if a new profile should be created,

        or if the incoming conversation should be added to an existing profile. These

        settings resolve how profiles are looked up and which profiles should merge together.'
      required:
      - identifierConfigs
      - matchingRules
      properties:
        identifierConfigs:
          type: array
          minItems: 1
          maxItems: 15
          description: List of identifier types and their resolution settings.
          items:
            $ref: '#/components/schemas/IdentifierConfig'
        matchingRules:
          type: array
          minItems: 1
          maxItems: 15
          example:
          - email
          - whatsapp
          - phone
          description: "Priority list of identifiers to locate profiles to apply new data to, or for determining if two existing profiles should merge. \n\nIndividual rules are evaluated with `OR` logic between them, meaning that satisfying any single rule will trigger a match. Each rule is a single identifier type; compound rules are not supported.\n\nRules are evaluated in order.\n- If no rule matches against existing profiles, a new profile will be created. \n- If a rule matches to a single existing profile, the profile will be updated. \n- If a rule matches to multiple existing profiles, those existing profiles will be merged."
          items:
            type: string
            maxLength: 30
            description: Name of a single identifier type, such as "email" or "phone". Compound rules (e.g. joining identifiers with `AND`) are not supported.
  headers:
    OperationId:
      description: The operation identifier.
      schema:
        type: string
        maxLength: 512
    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
    OperationRetryAfter:
      description: Suggested number of seconds to wait before checking status again.
      schema:
        type: integer
    OperationLocation:
      description: URI to check operation status.
      schema:
        type: string
        maxLength: 512
  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