Want to provide feedback?

Write to docs@telesign.com.

Set up an Anonymous SMS Session

This page shows you how to set up a session, to be used later when two users communicate via text using assigned masking IDs to conceal their real phone numbers. You must have the Anonymous SMS API enabled.

The fastest way to send your first request and get a code snippet for it is to use the Anonymous SMS API Explorer.


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

Anonymous SMS API Explorer
NOTE: The time shown is not indicative of regular transmission rates, and only applies to this API Explorer.
Send requests directly from the browser (CORS must be enabled)
No $$.env variables are being used in this request.

Use these instructions with the Anonymous SMS API Explorer (above) to send a request for an anonymous SMS session. Get a code snippet for making the request in the language of your choice.

  1. Click the Auth tab and for Username add your customer ID. For Password add your API key.
  2. Click the Body tab and for phone_number_1, enter your complete phone number with the country code and no special characters or spaces. For phone_number_2 enter a second phone number to use for testing. 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 available parameters on the API reference page - POST /anonymous/session/sms.)
  3. Click Send.
  4. Click the Code Generation tab and use the Language and Library drop-downs to choose the language you want your code snippet in.
  5. After you send your request, look through the JSON response and set aside the masked_id and session_id. The masking ID (masked_id) for each number is what your users will use to communicate with their numbers masked. The session ID you will use to track the users’ session and monitor as needed.

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 rest of this page provides details about the Anonymous SMS API:

Anonymous SMS API Information

All requests submitted for the Anonymous SMS API:

  • Can be authenticated with Basic (easiest to implement) and Digest authentication
  • Use https://rest-ww.telesign.com/v1/anonymous/session/sms as the base endpoint
  • Accept only UTF-8 encoded unicode characters as inputs
  • Use Content-Type - application/json in request headers

How it Works

In order 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 speak with another end user (say a rider wants to text the driver in a taxi app).
  2. You create a session request and send it to TeleSign. Your request will include the phone numbers of both parties.
  3. The rider texts 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 a session, you are billed for two text messages. The first message is the one sent to TeleSign. The second text message is when TeleSign sends this message on to the intended party. Each time each user in the session texts a message it will appear as two messages on the bill. This is required in order to mask the users’ phone numbers.


POST https://rest-ww.telesign.com/v1/anonymous/session/sms HTTP/1.1
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
  "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"

Next Steps

Check out these related pages: