Number Masking API - Get Started

The Number Masking API allows you to have two end users send and receive SMS or voice communications to one another without either party disclosing their phone numbers. You and TeleSign know their numbers and track their interactions so you can be sure they are not violating your terms of use.

This page includes requirements and service details common to using any method of this API. It also includes links to other pages that provide details for individual actions of the API.

General Requirements

Request Requirements

  • Authentication: Basic (easiest to implement) or Digest
  • Base URL:
  • Encoding: Accepts only UTF-8 unicode characters as inputs
  • MIME Type: application/json
  • Required Headers: Content-Type

Response Details

  • MIME Type: application/json


Create an anonymous session to use for number-masked SMS communications. Use numbers from TeleSign with only SMS capability, not voice capability, as masking IDs for these sessions.

Reference Page: POST /v1/anonymous/session/sms

Create an anonymous session that can be used for either number-masked SMS or voice communications. Use only dual-capable numbers (both SMS and voice capability) from TeleSign for masking IDs for these sessions.

Reference Page: POST /v1/anonymous/session/sms_voice

Obtain Transaction Status Results

To get status for number masking transactions, you need to set up a notification service that TeleSign can send these results to.
For more details on how to set up and use this service, see Obtain Transaction Status Results.


This section provides an example request to and response from the Number Masking API.


Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Content-Type: application/json; charset=utf-8
Date: Tue, 31 Jan 2017 14:51:26 GMT
   "phone_number_1": "381555555555",
   "phone_number_2": "381555555556",
   "validity_period": 500

Response (body only)

  "reference_id": "B5862A14363C016C8832D53625270015",
  "session_data": {
    "message": "",
    "phone_number_1": {
      "complete_phone_number": "381555555555",
      "country_code": "381",
      "country_iso2": "RS",
      "country_iso3": "SRB",
      "country_name": "Serbia",
      "masked_id": "381671111112"
    "phone_number_2": {
      "complete_phone_number": "381555555556",
      "country_code": "381",
      "country_iso2": "RS",
      "country_iso3": "SRB",
      "country_name": "Serbia",
      "masked_id": "38167111112"
    "resource": "sms",
    "session_end_on": "2018-03-05 10:59:13.761245",
    "validity": 500
  "status": {
    "code": 2700,
    "description": "Session successfully created",
    "updated_on": "2018-02-12T14:57:11.765723Z"

Did this page help you?