Number Masking - Get started



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:
  • Encoding: Accepts only UTF-8 unicode characters as inputs
  • Accepts: application/json
  • Required headers: Content-Type - application/json
  • Responds with: application/json


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.



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"