openapi: 3.2.0
info:
  title: Telesign Number Masking API
  version: '1.0'
  contact:
    name: Telesign Customer Support Team
    email: support@telesign.com
  description: 'Operations tagged Number Masking across 2 of this provider''s published API definitions: telesign-engage-api-number-masking-openapi.json, telesign-engage-api-number-masking-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://rest-ww.telesign.com
security:
- Basic: []
tags:
- name: Number Masking
paths:
  /v1/anonymous/session/sms:
    parameters: []
    post:
      summary: Create masked SMS session
      operationId: createMaskedSMSSession
      responses:
        '200':
          $ref: '#/components/responses/resNumMask200'
        '400':
          $ref: '#/components/responses/resNumMask400'
        '429':
          $ref: '#/components/responses/resNumMask429'
        '503':
          $ref: '#/components/responses/resNumMask503'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumMaskInputs'
            examples:
              Example:
                value:
                  phone_number_1: '15555551212'
                  phone_number_2: '15558675309'
                  validity_period: 500
          application/xml:
            schema:
              type: object
              properties: {}
          multipart/form-data:
            schema:
              type: object
              properties: {}
        description: ''
      description: 'Use this action to create an anonymous session for SMS communication with number masking. You must use SMS capable-only (not voice capable-only or dual-capable) numbers from Telesign as masking IDs when using this action.


        > Looking for the high-level guide page related to this action? Go to Number Masking - Create masked session for SMS.


        ## General requirements

        * **Authentication:** Basic (easiest to implement) or Digest

        * **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.

        * **Accepts:** `application/json`

        * **Responds with:** `application/json`

        * **Required headers:** `Content-Type - application/json`

        * **Rate limit:** Default rate limits by product'
      tags:
      - Number Masking
    servers:
    - url: https://rest-ww.telesign.com
  /v1/anonymous/session/sms_voice:
    post:
      summary: Create masked voice-SMS session
      operationId: createMaskedVoiceSMSSession
      responses:
        '200':
          $ref: '#/components/responses/resNumMask200'
        '400':
          $ref: '#/components/responses/resNumMask400'
        '429':
          $ref: '#/components/responses/resNumMask429'
        '503':
          $ref: '#/components/responses/resNumMask503'
      description: 'Use this action to create an anonymous session, usable either for SMS or voice communication with number masking. You must use only dual-capable (both SMS and voice capable) numbers from Telesign as masking IDs when using this action.


        > Looking for the high-level guide page related to this action? Go to Number Masking - Create masked session for SMS or voice.


        ## General requirements

        * **Authentication:** Basic (easiest to implement) or Digest

        * **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.

        * **Accepts:** `application/json`

        * **Responds with:** `application/json`

        * **Required headers:** `Content-Type - application/json`

        * **Rate limit:** Default rate limits by product'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumMaskInputs'
      tags:
      - Number Masking
    servers:
    - url: https://rest-ww.telesign.com
components:
  schemas:
    NumMaskPhoneNumberDetails:
      title: NumMaskPhoneNumberDetails
      type: object
      properties:
        complete_phone_number:
          type: string
          description: The base phone number prefixed with the country dialing code.
          example: '15555551212'
        country_name:
          type: string
          description: The country name associated with phone number.
          example: United States
        country_iso3:
          type: string
          description: The ISO 3166-1 three-letter country code associated with the phone number.
          example: USA
        masked_id:
          type:
          - string
          - 'null'
          description: The masking ID allocated to conceal this phone number.
          example: '15557740233'
        country_iso2:
          type: string
          description: The ISO 3166-1 two-letter country code associated with the phone number.
          example: US
        country_code:
          type: string
          description: The one, two, or three-digit country dialing code.
          example: '1'
    NumMaskResSchema:
      title: NumMaskResSchema
      type: object
      properties:
        reference_id:
          type: string
          description: Unique 32-digit hex value generated by the service to identify both your request and the session created.
          example: B5862A14363C016C8832D53625270015
        external_id:
          type:
          - string
          - 'null'
          example: MSG432538
        status:
          $ref: '#/components/schemas/NumMaskStatus'
        session_data:
          $ref: '#/components/schemas/NumMaskSessionData'
        error:
          description: Unused property. You can disregard this.
          type:
          - string
          - 'null'
    NumMaskInputs:
      title: NumMaskInputs
      type: object
      properties:
        phone_number_1:
          type: string
          description: 'The phone number for one of the end users that will engage in the anonymous exchange. '
          example: '15555551212'
        phone_number_2:
          type: string
          description: 'The phone number for the other end user that will engage in the anonymous exchange. Must be different from `phone_number_1`. '
          example: '15558675309'
        validity_period:
          type: integer
          description: The amount of time you want the two end users to be able to communicate for. The unit this number represents can be seconds, minutes, hours, or days. The unit used is configured by Telesign; ask our Customer Support Team if you need it changed. The maximum value depends on the units configured for your account, but will always be equivalent to 720 hours.
          minimum: 1
          example: 500
    NumMaskStatus:
      title: NumMaskStatus
      type: object
      description: Contains details related to the processing status of this transaction.
      properties:
        code:
          type: integer
          description: Numeric code indicating the processing status of the request.
          example: 2700
        description:
          type: string
          description: Text describing the processing status of the request.
          example: Session successfully created
        updated_on:
          type: string
          description: A timestamp in ISO 8601 format indicating when the status was last updated.
          example: '2018-02-12T14:57:11.765723Z'
    NumMaskSessionData:
      title: NumMaskSessionData
      type: object
      description: Contains properties related to the session created for this request.
      properties:
        session_end_on:
          type: string
          description: The time stamp, in ISO 8601 format, indicating when the session will expire.
          example: '2018-03-05 10:59:13.761245'
        resource:
          type: string
          description: The Number Masking resource you used to create this session. If this value is `sms`, the session can only be used for SMS communication. If this value is `sms_voice`, the session can be used for either SMS or voice communication.
          example: sms
          enum:
          - sms
          - sms_voice
        message:
          type: string
          description: Any additional description of what happened during the creation of the session. For example, this value might give you a notification that the countries for phone number 1 and the assigned masking ID are different.
          example: Failed to obtain mask for 15555551212
        phone_number_2:
          description: One of the two phone numbers being masked in the anonymous session.
          allOf:
          - $ref: '#/components/schemas/NumMaskPhoneNumberDetails'
          - type: object
            properties:
              complete_phone_number:
                type: string
                example: '15558675309'
              masked_id:
                type:
                - string
                - 'null'
                example: '15557740234'
        validity:
          type: string
          description: The period of time that the session will be available. Defined in terms of seconds, minutes, hours, or days. The unit used is configured by Telesign and can be changed at your request.
          example: '500'
        phone_number_1:
          $ref: '#/components/schemas/NumMaskPhoneNumberDetails'
  responses:
    resNumMask200:
      description: "**Success.** Your request was fulfilled and resulted in the creation of a new session. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.  \n\n| Status code | Description |\n|--|--|\n| 2700 | Session successfully created |\n| 2701 | Session successfully created, the country codes of the phone number and assigned masked_id differs |"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NumMaskResSchema'
          examples:
            Example:
              value:
                session_data:
                  session_end_on: '2018-03-05 10:59:13.761245'
                  resource: sms
                  message: ''
                  phone_number_2:
                    complete_phone_number: '15558675309'
                    country_name: United States
                    country_iso3: USA
                    masked_id: '15557740234'
                    country_iso2: US
                    country_code: '1'
                  validity: '500'
                  phone_number_1:
                    complete_phone_number: '15555551212'
                    country_name: United States
                    country_iso3: USA
                    masked_id: '15557740233'
                    country_iso2: US
                    country_code: '1'
                reference_id: B5862A14363C016C8832D53625270015
                external_id: MSG432538
                status:
                  code: 2700
                  description: Session successfully created
                  updated_on: '2018-02-12T14:57:11.765723Z'
                error: null
    resNumMask429:
      description: Too many requests.
      content:
        text/plain:
          schema:
            type: string
            description: Too many requests.
            example: Too many requests.
    resNumMask400:
      description: '**Bad request.** The request could not be understood by the server due to malformed syntax. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.


        | Status code | Description |

        |--|--|

        | 2702 | Request for creating session failed, there isn''t available masked_id |

        | 2703 | Request for creating session failed, invalid session type |

        | 2705 | Request for creating session failed, validity_period must be integer greater than zero |

        | 2706 | Request for creating session failed, phone number {phone_number} blocked by Telesign |

        | 2707 | Request for creating session failed, phone number {phone_number} blocked by customer |

        | 2708 | Request for creating session failed, phone_number_1 and phone_number_2 parameters cannot be the same value |

        '
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/NumMaskResSchema'
            - type: object
              properties:
                status:
                  type: object
                  properties:
                    code:
                      type: integer
                      example: 2702
                    description:
                      type: string
                      example: Request for creating session failed, there isn't available masked_id
          examples:
            Example:
              value:
                reference_id: B5862A14363C016C8832D53625270015
                external_id: MSG432538
                status:
                  code: 2702
                  description: Request for creating session failed, there isn't available masked_id
                  updated_on: '2018-02-12T14:57:11.765723Z'
                session_data:
                  session_end_on: '2018-03-05 10:59:13.761245'
                  resource: sms
                  message: Failed to obtain mask for 15555551212
                  phone_number_2:
                    complete_phone_number: '15558675309'
                    country_name: United States
                    country_iso3: USA
                    masked_id: null
                    country_iso2: US
                    country_code: '1'
                  validity: '500'
                  phone_number_1:
                    complete_phone_number: '15555551212'
                    country_name: United States
                    country_iso3: USA
                    masked_id: null
                    country_iso2: US
                    country_code: '1'
                error: null
    resNumMask503:
      description: '**Service unavailable.** The system is unavailable, try again. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.


        | Status code | Description |

        |--|--|

        | 2704 | Request for creating session failed, internal error |

        '
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/NumMaskResSchema'
            - type: object
              properties:
                status:
                  type: object
                  properties:
                    code:
                      type: integer
                      example: 2704
                    description:
                      type: string
                      example: Request for creating session failed, internal error
          examples:
            Example:
              value:
                reference_id: B5862A14363C016C8832D53625270015
                external_id: MSG432538
                status:
                  code: 2704
                  description: Request for creating session failed, internal error
                  updated_on: '2018-02-12T14:57:11.765723Z'
                session_data:
                  session_end_on: '2018-03-05 10:59:13.761245'
                  resource: sms
                  message: ''
                  phone_number_2:
                    complete_phone_number: '15558675309'
                    country_name: United States
                    country_iso3: USA
                    masked_id: null
                    country_iso2: US
                    country_code: '1'
                  validity: '500'
                  phone_number_1:
                    complete_phone_number: '15555551212'
                    country_name: United States
                    country_iso3: USA
                    masked_id: null
                    country_iso2: US
                    country_code: '1'
                error: null
  securitySchemes:
    Basic:
      type: http
      scheme: basic
      description: Easiest to implement. See [Basic Authentication](/enterprise/docs/authentication#basic-authentication) for more details.
x-refined-from:
- telesign-engage-api-number-masking-openapi.json
- telesign-engage-api-number-masking-openapi.yml
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true