Get Started with the Number Masking API

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

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

Contents of this page:

General Requirements

Request Requirements

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

Response Details

  • MIME Type: application/json

Actions

Create Masked Session for 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.

Reference Page: POST /v1/anonymous/session/sms

Create Masked Session for SMS or 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.

Reference Page: POST /v1/anonymous/session/sms_voice

Obtain Transaction Status Results

To get status for number masking transactions, you need to set up a notification service that TeleSign can send these results to. For more details on how to set up and use this service, see Obtain Transaction Status Results.

Example

This section provides an example request to and response from the Number Masking API.

Request
HTTPS
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)
application/json
{
  "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"
  }
}

Next Steps

Check out these related pages: