How to create number masking sessions

📘

Pre-requisite

In order to create Number Masking sessions, one must possess a Number Masking Application on the Unifonic Console and have assigned a Caller ID to this Number Masking Application. This Caller ID is used for all of the Number Masking sessions. i.e. users that are masked in a session will make or receive calls from this Caller ID number.

There are two types of Number Masking sessions one can create:

i. Two-way: Tom and Mary's personal phone numbers will be masked using a masking number which they can call to reach each other. Any other parties outside of Tom and Mary that dial this DID number will not be able to reach either Tom or Mary.

curl --location --request POST 'https://voice.unifonic.com/v1/providers/masks' \
--header 'AppsId: XXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "from":"+966XXXXXXXX", //Tom
    "to": "+966YYYYYYYY" //Mary
}
'

ii. One-way:Tom's phone number will be masked using a DID number, anyone that dials this DID number will be able to reach Tom via this DID number.

curl --location --request POST 'https://voice.unifonic.com/v1/providers/masks' \
--header 'AppsId: XXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "to": "+966YYYYYYYY" //Tom
}
'

In return, you will get a Masking Number once you have created a session. You will be returned the following response:

{
    "maskId": "7233bb70-0883-43-9b64-14c469022b44",
    "callerId": "+966XXXXXXXXX", //masking number
    "secondaryCallerId": null,
    "status": "active",
    "timeCreation": "2022-12-20 10:43:01",
    "timeDeactivation": "2022-12-21 10:43:01",
    "requestBody": "MaskRequest(from=+966XXXXXXXXX, to=+966XXXXXXXXX)",
    "from": "+966XXXXXXXXX", //tom
    "to": "+966XXXXXXXX" //mary
}

The maskId represents the masking session and will remain active for 24 hours at a time. This means that Tom and Mary will be able to contact each other by simply dialling the masking number. In order to deactivate the masking session in advance, you may use the Delete/maskingSession API.

🚧

General Rules

1. There can be an unlimited number of active sessions on a Number Masking Application if they are all two-way sessions.
2. All users found in any sessions of the same Number Masking Application will use the same Masking number. Concurrent calls on the same masking number are possible. Users will still only connect to whomever they are paired with in a session.
3. if there is a need to mask a single user with many users, more Number Masking Applications are needed as one user's phone number can only appear once in each Number Masking Application.
4. There can only be 1 active one-way session on a Number Masking Application.

The below diagram serves to summarise the different rules.