Number Masking - Get started

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

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

Number Masking 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.

General requirements

• Authentication: Basic (easiest to implement) or Digest
• Resource: https://rest-ww.telesign.com/v1/anonymous/session/
• Encoding: Accepts only UTF-8 unicode characters as inputs
• Accepts: application/json
• Required headers: Content-Type - application/json
• Responds with: application/json

Actions

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

• POST https://rest-ww.telesign.com/v1/anonymous/session/sms_voice - 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.

Obtain transaction status results

To get status for Number Masking transactions, you need to set up a callback service to which Telesign can send these results.
For more details on how to set up and use this service, see Number Masking - Callback service.

Example

Request

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": "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"
  }
}