Skip to main content

Number Masking

  • Does Plivo offer a dedicated number pool for number masking?

    Currently, we don't provide a dedicated number pool specifically for number masking. However, you can allocate numbers to a subaccount and create sessions by specifying the subaccount auth details. This ensures that virtual number allocation is aligned with the subaccount used in the session. Plivo will exclusively access and use the numbers associated with the specified subaccount. 


    curl -X POST "{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": "",
      "geomatch": true,
      "subaccount": "SAOWRKMGU3YZCTZJXXX",
      "incorrect_pin_play": ""

    The above request will create a number masking session with the virtual number that belongs to the subaccount auth ’SAOWRKMGU3YZCTZJXXX’.

  • What is number masking?

    Number masking helps protect the privacy of communication by anonymizing the original phone numbers of the parties involved. It uses an intermediary virtual number that masks the actual numbers during the call. Plivo's Number Masking API is designed to seamlessly manage both the assignment of virtual numbers and the entire call flow process. To initiate a masked session, simply send an API request including the real phone numbers of the call participants. In response, Plivo allocates a virtual number from your account that facilitates the masked session.

    For more information, please refer to our detailed documentation.

  • How can I integrate with Plivo’s number masking solution?

    Integrating with Plivo's robust number masking solution can be accomplished through our packaged API or by utilizing our Software Development Kits (SDKs). Plivo offers SDKs in a wide range of programming languages, including Python, Ruby, Java, Node.js, .NET, PHP, and Go.

  • What is a Number Masking session?

    A number masking session is a unique instance facilitated by Plivo, initiated for every combination of first party and second party phone numbers. Within this session, multiple masked phone calls can be made by the parties involved. 

    Each session is represented by a Session object, containing attributes such as a unique session identifier, the phone numbers of the parties involved, and a virtual number provided by Plivo to connect them.

    As an example, consider a scenario within a ride-hailing app, where a driver and a rider need to connect to coordinate a ride. When the driver initiates contact with the rider, Plivo creates a unique number masking session for their interaction. Within this session, the driver and rider can make multiple calls to coordinate the ride without revealing their personal phone numbers to each other. Each call is part of the same session until it expires or is terminated.

    For more information, please visit our number masking concepts section.

  • Can I create a number masking session with more than two parties involved?

    Plivo’s Number Masking solution facilitates private communications between two parties by concealing actual phone numbers. 

    In scenarios requiring involvement of more than two parties in a single session, such as conference calls or group discussions, Plivo offers a separate solution known as the Multi-party solution. This solution is designed to facilitate multiparty calls and conferences, catering to scenarios where multiple participants need to interact simultaneously. However, this solution does not offer phone number masking. 

    Number Masking and Multiparty Calls serve distinct purposes. Number Masking focuses on privacy by concealing phone numbers, while Multiparty Calls cater to situations requiring interactions among multiple participants in a conference setting.

    To learn more about the Multiparty solutions, please refer to the API documentation

  • What is a Number Masking interaction?

    A number masking interaction refers to a specific call between two parties within a number masking session. In a session, there can be multiple interactions.

    Each interaction is represented by a unique Interaction object, which is nested within the corresponding session. The Interaction object includes attributes related to a particular interaction, such as the URL of the call-leg resource created for both the first party and the second party involved in the conversation.

    As an example, consider a scenario within a ride-hailing app, where a driver and a rider need to connect to coordinate a ride. During the session, each time the driver initiates a call to the rider or vice versa, a new interaction object is created. Multiple interactions can occur within the same session as the driver and rider communicate back and forth to finalize ride details. Each interaction represents a distinct call between the driver and rider within the overall ride-hailing session.

    For more information, please visit our number masking concepts section.

  • Can I terminate a number masking session after the interaction?

    Yes, you can end a number masking session at any time following the interaction by using the expire session API. Terminating a session means that the parties can no longer connect using the virtual number. 

    For more details, refer to our expire session API.

  • How long can a number masking session be active?

    By default, the session expiry time is set to 3600 seconds (1 hour). However, you can set session_expiry to a maximum of 24 hours, which is 86400 seconds.

  • How do I track the interactions for a specific session?

    Each interaction within a number masking session is tracked and associated with its respective session. By utilizing commands like get all session or get details of a single session, you can easily retrieve information about the various interactions that occurred within any given session.

  • Does Plivo offer PIN-based authentication?

    Yes, Plivo supports PIN-based authentication to securely connect calls from unregistered numbers of designated users to their intended sessions. This feature is particularly beneficial when users make calls from unknown or secondary numbers that were not registered during the session creation. Callers are prompted to authenticate themselves by entering a unique PIN, effectively mapping unregistered numbers to sessions.

  • How many attempts does Plivo allow for entering a PIN?

    Plivo offers flexibility by allowing one retry for an incorrect PIN entry by default. Should your application require it, this retry limit can be increased up to five attempts.

  • How does virtual number allocation work?

    We have detailed documentation on how virtual number allocation works. Please refer to the virtual number allocation logic.

  • Can I configure a custom message for callers from unknown numbers?

    Absolutely. Plivo allows for the customization of messages for callers dialing from unrecognized numbers, tailored to fit your specific business needs and scenarios. You can set up your preferred message in the unknown_caller_play parameter, in either .mp3 or .wav format. When a call from an unknown number reaches the virtual number and is_pin_authentication_required is set to false, Plivo will play the configured message.

  • Can I configure a custom message for callers asking them to enter the PIN?

    Yes, you can configure a custom prompt for callers from unknown numbers to enter their PIN. This message should be set up in the pin_prompt_play parameter, in formats such as .mp3 or .wav. If a call from an unrecognized number is received and is_pin_authentication_required is set to true, Plivo plays this custom prompt, guiding the caller to authenticate themselves by entering the PIN.

  • Are there any charges for creating a number masking session?

    Creating a number masking session with Plivo incurs no additional charges. The standard voice API inbound and outbound charges as well as the number rental charges will apply for the interactions taking place through the virtual number.

  • Can the number masking session call be recorded?

    Yes, calls within a number masking session are automatically recorded. Recordings are available in .mp3 or .wav format and are securely stored on Plivo's infrastructure. You have the option to disable recording by setting the record attribute to false.

    As an added benefit, Plivo offers complimentary storage for these recordings for up to 90 days. Should you require extended storage, it is available for a nominal fee of $0.0004 per minute per month, after the initial 90-day period.

  • What happens when someone calls from a number that is not part of the number masking session?

    In cases where a call to the virtual number is made from a phone number not recognized as part of the ongoing number masking session there are three options to handle this situation:

    1. PIN-based authentication (recommended): Plivo ensures secure communication by requiring a PIN to enter the session. The caller receives a unique PIN and must enter it to connect. This maintains session integrity. Enable PIN-based authentication by setting is_pin_authentication to true during the session creation. (default is false).
    2. Unknown caller prompt (optional): If PIN authentication is disabled, use the unknown_caller_play parameter (optional) to play a message instructing the caller to use their registered number. This parameter only accepts .mp3 or .wav files.
    3. Call failure (default): If neither PIN authentication nor the unknown caller prompt is enabled, the call will fail.

    Please review our quickstart guide and API reference to understand how PIN authentication works.

  • How can I avoid being charged for number masking call recording storage beyond 90 days?

    To avoid incurring charges for recording storage beyond 90 days, you will need to disable the ‘Recording Storage’ feature from the Plivo console. Navigate to the Plivo console → Voice → Other Settings → Recording Storage and set this option to Disabled.



  • Can the number masking session call be transcribed?

    Unfortunately, Plivo currently does not support the transcription of calls within number masking sessions. Transcription services are only available for standard voice calls.

  • What is the role of the geomatch attribute?

    The geomatch attribute plays a crucial role in the allocation of a virtual number at the beginning of a session. When geomatch is set to true, Plivo allocates a virtual number that matches the country code of the initiating caller's number (the first-party number).


    Attribute  Datatype  Description




    Specifies if the country of the virtual number used for session allocation must match the first_party number.

    When the geomatch parameter is enabled, Plivo searches for a virtual number that matches with the country code of the first_party number from the number pool.

    Default: true

    Possible values: true/false

  • Can I update the geomatch parameter for an active session?

    No. Updating the geomatch parameter is not allowed for an existing active session.

  • What is the error message returned if there are no matching country numbers?

    If no matching country numbers are found, session creation will fail, returning the following response:


    Error: 404

    Status: “No compatible virtual numbers found for country code {iso2}. Please check the number masking reserved virtual numbers pool” 

  • I can’t find virtual numbers for the countries I want to use for my number masking session. What should I do?

    Plivo endeavors to collaborate with worldwide vendors to acquire numbers. If you cannot locate the virtual number through Plivo’sconsole or API, please contact our support team for further assistance.