How PIN-based authentication works

To see how number masking works, suppose you have a web or a mobile application with which you want to connect two participants in a voice call.

1. The application collects the phone numbers of the two parties whose numbers you wish to mask.
   
2. The application makes a Number Masking API request to Plivo with the phone numbers and authentication parameters as mentioned in the session object reference.
   
3. Plivo creates a number masking session and assigns to it a virtual phone number from your Plivo account.
   
4. Both parties receive the virtual phone number, along with unique PIN codes that both parties will use to enter the call if calling from an unknown number.
   
5. If either party calls the virtual phone number from a registered number, they will automatically be connected. The caller ID is set to the virtual phone number, masking the real phone numbers of both parties from each other.
   
6. If either party dials the virtual phone number from an unknown number, they will be prompted to enter the PIN. Once the authentication is successful, they will be connected.
   

Prerequisites

A Plivo account is required — sign up with your work email address if you don’t have one already. You must have a voice-enabled Plivo phone number to create number masking sessions. You can rent numbers from the Numbers page of the Plivo console, or by using the Numbers API.

Create a PIN-based session

Here’s a sample cURL request to create a number masking session with PIN authentication.

1
2
3
4
5
6
7
8
9
10
11
curl -X POST "https://api.plivo.com/v1/Account/{Auth ID}/Masking/Session" \
-H "Content-Type: application/json" \
-d '{
  "first_party": "+919003459XXX",
  "second_party": "+919840037XXX",
  "is_pin_authentication_required": true,
  "first_party_pin": "1234",
  "second_party_pin": "4321",
  "pin_prompt_play": "https://play.s3.eu-north-1.amazonaws.com/pin_prompt.wav",
  "incorrect_pin_play": "https://play.s3.eu-north-1.amazonaws.com/incorrect_pin.wav"
}'

Set is_pin_authentication_required to true if PIN authentication is needed for calls coming from unknown numbers to the virtual number. Include the following required parameters: first_party_pin, second_party_pin, pin_prompt_play, and incorrect_pin_play. Further details about these attributes can be found in the session object description.

Plivo will provide a virtual number from your account that your application can utilize to host the masked session. When either party dials the virtual number from a registered number, Plivo will seamlessly connect the call to the other party. However, if a call originates from an unknown number, Plivo will connect the call to the other party after PIN authentication. Below is a sample response.

{
  "api_id": "ae245217-f78e-4939-bc48-d4b8ef05cf66",
  "session_uuid": "4189591e-d004-4801-abdf-8893c15e5dcd",
  "virtual_number": "+912269947011",
  "message": "Session created",
  "session": {
    "first_party": "919003459XXX",
    "second_party": "919840037XXX",
    "virtual_number": "912269947011",
    "status": "active",
    "initiate_call_to_first_party": false,
    "first_party_pin": "1234",
    "second_party_pin": "4321",
    "is_pin_authentication_required": true,
    "generate_pin": false,
    "generate_pin_length": 4,
    "pin_ prompt_play": "https://play.s3.eu-north-1.amazonaws.com/pin_prompt.wav",
    "pin_retry": 1,
    "pin_retry_wait": "5",
    "incorrect_pin_play": "https://play.s3.eu-north-1.amazonaws.com/incorrect_pin.wav",
    "session_uuid": "4189591e-d004-4801-abdf-8893c15e5dcd",
    "callback_url": "https://webhook.site/0ece3c18-f1e4-48a8-98fe-b8f651e53eef",
    "callback_method": "POST",
    "created_time": "2024-01-03 13:35:51 +0000 UTC",
    "modified_time": "2024-01-03 13:35:51 +0000 UTC",
    "expiry_time": "2024-01-03 14:05:51 +0000 UTC",
    "duration": 1800,
    "amount": 0,
    "call_time_limit": 14400,
    "ring_timeout": 45,
    "first_party_play_url": "https://play.s3.eu-north-1.amazonaws.com/agent.wav",
    "second_party_play_url": "https://play.s3.eu-north-1.amazonaws.com/customer.wav",
    "record": false,
    "record_file_format": "mp3",
    "recording_callback_url": "",
    "recording_callback_method": "POST",
    "interaction": null,
    "total_call_amount": 0,
    "total_call_count": 0,
    "total_call_billed_duration": 0,
    "total_session_amount": 0,
    "last_interaction_time": ""
  }
}