Number Masking API - Create Masked Session for SMS

This page shows you how to create an anonymous session where two users can send text messages to each other using assigned masking IDs instead of their real phone numbers. You must use only SMS capable (not voice capable or dual-capable) numbers from TeleSign as masking IDs when using this action. You must have the Number Masking API enabled to use this action.

Reference Page

POST /v1/anonymous/session/sms - See complete technical details for this action, including all request parameters and response properties.

Try It

If you have been granted access and credentials for the Number Masking API, you can try a test request in the API Explorer in the Reference section. You can also get a code snippet for the request.

  1. Select the Auth tab.
  2. Enter your Customer ID for Username.
  3. Enter your API key for Password.
  4. Select the Body tab.
  5. For phone_number_1, enter your complete phone number with the country code and no special characters or spaces.
  6. For phone_number_2, enter a second phone number to use for testing.
  7. For validity_period, enter an integer between 1 and 720 (assuming the units are configured to hours for your account). This is the time duration that you want the session to last. The units may vary depending on your configuration at setup, ask our Customer Support Team if you are not sure what units apply for your account. (See full parameter details on the API reference page at POST /v1/anonymous/session/sms.)
  8. Select Send.
  9. Select the Code Generation tab and use the Language and Library menus to choose the language you want your code snippet in.
  10. After you send your request, look through the response and make a note of the masked_id and session_id values. The masking ID (masked_id) for each number is what your users will use to communicate with their real numbers masked. You will use the session ID to track the users' session and monitor as needed.



When using the API Explorer, you will be charged your contracted rate for each transaction.



It is possible that the masking ID for both parties is the same number. This does not impact SMS communication between the two parties.


The full endpoint for this action is:

How it Works

To connect two users without either knowing the other's true phone number, the flow works like this:

  1. You receive a request for communication from an end user wanting to text with another end user (say a rider wants to text the driver in a taxi app).
  2. You send an anonymous SMS session request to TeleSign. Your request will include the real phone numbers of both parties.
  3. The rider sends their message. This arrives at TeleSign's servers.
  4. TeleSign receives the message and sends a text message to the driver, but masked.



Any time a message is sent in an anonymous session, you are billed for two text messages. The first message is the one sent to TeleSign from the originating end user. The second message is the one TeleSign sends to the destination end user.


Below is an example of basic usage of this action.


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": "15555551212", 
   "phone_number_2": "15558675309",
   "validity_period": 500

Response (body only)

  "reference_id": "B5862A14363C016C8832D53625270015",
  "session_data": {
    "message": "",
    "phone_number_1": {
      "complete_phone_number": "15555551212",
      "country_code": "1",
      "country_iso2": "US",
      "country_iso3": "USA",
      "country_name": "United States",
      "masked_id": "15557740233"
    "phone_number_2": {
      "complete_phone_number": "15558675309",
      "country_code": "1",
      "country_iso2": "US",
      "country_iso3": "USA",
      "country_name": "United States",
      "masked_id": "15557740234"
    "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?