Want to provide feedback?

Write to docs@telesign.com.


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

General 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

Set up an Anonymous Session

You can read more about setting up an anonymous session on the Set up an Anonymous Session page.

Read about available parameters you can send in your request on the POST v1/anonymous/session/sms page.


The Anonymous SMS API always tries to assign a sender ID from the same country as the end user’s phone number. If there is no available sender ID for the specific country, the sender ID will be assigned from a pool of sender IDs, but in the response you are notified of this. For status code 2701, the message field describes what happened. There are three scenarios that may be described by the message field:

  • sender_id for phone_number_1 and phone_number_1 have different country codes.
  • sender_id for phone_number_1 and phone_number_2 have different country codes.
  • Both sender IDs for both phone numbers have different country codes.

It is possible that the sender ID for phone number 1 and 2 have the same value. This does not impact SMS communication between the two parties.

Obtain Transaction Status Results

You can read about how status results are obtained on the Obtain Transaction Status Results page.


This section provides an example request to and response from the Anonymous SMS API.

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
Content-Type: application/json; charset=utf-8
Content-Length: 59

   "phone_number_1": "Put the first phone number here with country code and no special characters or spaces",
   "phone_number_2": "The phone number you connect to goes here with country code and no special characters or spaces",
   "validity_period": "Number of hours you want the connection to be valid for."
Example Response Structure for Anonymous SMS
  "reference_id": "B5862A14363C016C8832D53625270015",
  "session_data": {
    "message": "",
    "phone_number_1": {
      "complete_phone_number": "complete_number_with_no_special_characters_or_spaces",
      "country_code": "381",
      "country_iso2": "RS",
      "country_iso3": "SRB",
      "country_name": "Serbia",
      "sender_id": "381671111112 example only"
    "phone_number_2": {
      "complete_phone_number": "complete_number_with_no_special_characters_or_spaces",
      "country_code": "381",
      "country_iso2": "RS",
      "country_iso3": "SRB",
      "country_name": "Serbia",
      "sender_id": "38167111112 example only"
    "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

This section offers some suggestions for next steps to take.

  • Set up an Anonymous Session - Learn how to create your first anonymous SMS session.
  • Get Started with the SMS API - Take a look at one of TeleSign’s other SMS products. The SMS API lets you send SMSes for alerts, reminders, notifications, marketing messages or verification codes.