Number Masking
Introduction
Number Masking exposes API to obfuscate called/calling parties. Both voice calls and messages (SMS) are supported
Number Masking allows users to create and manage:
Developers can create applications, for example Taxi Booking Application or Food Delivery Application, and for each application assign phone numbers made available by your service provider, to create a pool of masked numbers.Whenever a ride is booked by a customer, the developer will create a new Context and add Participants (driver and customer) to that Context.Number masking will automatically select the masked number from the pool and assign it to the participants.The masked number is shared with the respective participants.Whenever a participant calls the masked number, the other participant in the same Context will receive a call from their assigned masked number while keeping complete privacy.
There can be zero, one or many interactions between participants during the lifetime of a context.
Application
Application is a simple way to distinguish separate number masking applications.Applications have Context and each Context has Participants.Applications also have Numbers within it that are used for masking
Create Application
This endpoint will be used to create Application.On successful execution of API, returns the Application SID that can be used to lookup Application’s later and add Context, Numbers etc to it.
Request Parameters
| Parameter | Description | Type |
|---|---|---|
enterpriseSid |
Mandatory. Business Customer Sid. |
String |
name |
Mandatory. Unique name of application |
String |
ttl |
Optional. Default time to live for a context created in an application. TTL (time to live) is measured in seconds after Context’s last creation date or interaction. If not passed, it defaults to |
Integer |
geoMatchLevel |
Optional. Where a masked number must be located relative to the participant phone number. For example, if the participant’s number is “15713316943” and the masked number pool has a phone number starting with country code “1”, it will be selected. If not, an error will be returned. As of today only “country” is supported. The default value is |
String |
callBackUrl |
Optional. URL to call when interaction status changes. To unset existing value pass an empty string like “”. |
String |
interceptCallbackUrl |
Optional. The URL platform will call on each interaction. If the platform receives a 403 status, it blocks the interaction. Otherwise the interaction continues. To unset the existing value pass an empty string like “”. |
String |
outOfContextCallbackUrl |
Optional. The URL platform should call when an inbound call occurs on a closed or non-existent Context. If your server responds with valid RCML, the platform will process it. This means it is possible, for example, to play a message for a call, or redirect a call to another phone number. See the Out of Context Callback section for more information. To unset existing value, pass an empty string like “”. |
String |
Response Body
The response body will contain the code, corresponding message and data of the Application if it was successfully created. HTTP response will be 200 Created (OK).
The response returned is the JSON body as shown in the example below. Each parameters are as explained below
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Application data as explained in the Data Parameter below. |
Data Parameter
| Data Parameter | Description |
|---|---|
sid |
Unique Application Id. This can be later used to delete or update Application |
enterpriseSid |
Sid of the business customer. |
name |
Unique name of Application. Name should be unique within a business. |
ttl |
Default time to live for Context created in Application. TTL (time to live) is measured in seconds after Contexts last create date or interaction. If not passed, default is 0 which is unlimited. |
accountEmail |
Unique CPaaS Account that created this particular Application |
dateCreated |
Timestamp when this Application was created |
dateUpdated |
Timestamp when this Application was updated |
uri |
Absolute URL of Application |
Create Application API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, below are the error codes it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
461 |
409 |
Application name not unique |
Application name is already used for given Business Customer |
Create Application, Update Application |
Example
{
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"name": "MyTestApplication"
}From the bash terminal you can run the command below:
curl -X POST \
'https://yourcompany.com/numbermasking/applications' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"name": "MyTestApplication"
}'If creation of Context is successful, below is the response returned:
{
"code": 200,
"message": "OK",
"data": {
"sid": "NMAb6eb071d21124dbab20b095c25f1274f",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"name": "MyTestApplication",
"ttl": "0",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/applications/search/NMAb6eb071d21124dbab20b095c25f1274f"
}
}If creation fails, below response is returned with corresponding HTTP Error Code
{
"errorCode": "461",
"message": "Application name not unique",
"data": {
"name": "App4",
"enterpriseSid": "EN995ef31d1ae64ef48f45685cb67dca1f"
}
}Out of Context Callback
A Masked Number can often receive calls that are not from Participants in an Open Context, or are from valid Participants but from Closed Context. In that case if your Application has outOfContextCallbackUrl defined, then a URL request with a payload will be made.
Your business logic can respond with either of below two responses.
-
Valid RCML with Content-Type response header set to “application/xml”. All the RCML verbs are supported
-
For example see below payload to be sent.
-
<Response>
<Say>Welcome to Acme. The party you are calling is not present any more.</Say>
</Response>| For more information about RCML please check out the RCML documentation |
-
Valid Auto-create Context JSON, with the Content-Type response header set to
application/json
Example Payload
{
"participantIdentifier": "1xxxxxxxxxx",
"name": "Cantext-timestamp-1594897729787",
"ttl": "600"
}Auto-create Context
If business logic determines, based on the information included in the callback payload, that the caller should be connected to a particular Agent, you can respond with json that tells Application to create a Context between the caller/sender and Agent. Application will create the Context and Participants and will then proceed as if the caller/sender had reached an open Context.
Parameters
Parameter |
Description |
name |
Mandatory. Unique name for Context. |
mode |
Optional. Context Mode. Possible values are: |
ttl |
Optional. The time, in seconds, when the Context will expire. The time is measured from the last Context create or the Context’s last Interaction. Default is 0 which means Context never expires |
dateExpiry |
Optional. Date/Time at which Context should expire, if any. If this value is present, it overrides the ttl value. Default is not set which means Context never expires |
participantIdentifier |
Mandatory. Real Phone Number of the second Participant (e.g., your agent) |
participantMaskIdentifier |
Optional. Mask Identifier to use for second Participant (e.g., a Reserved Number from your pool) Application will choose a non-Reserved number from the pool if not specified. |
Example of Call Back Payload
All callback parameters will be submitted as form parameters (application/x-www-form-urlencoded). Each call back will pass specific parameters as shown below with their example values.
callBackUrl
To understand the meaning of each of these headers please look at Interactions Data Parameters.
Header |
Value examples |
inboundParticipantSid |
PT70fc31025aa84031bb3400edf52079d5 |
inboundTargetSid |
IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAda85d7935b96454983154e7feb5d75ad |
inboundChannelStatus |
ringing |
inboundChannelType |
Call |
interactionAccountSid |
AC1a85c065d5ba4f4fc4ddb96469e88e4d |
interactionApplicationSid |
APP0582af44b3f04325a0f948d471f083cd |
interactionContextSid |
CTXef986543fc0b429ea16aedb28bc29336 |
interactionData |
|
interactionDateCreated |
2020-07-15T08:59:14+0000 |
interactionDateUpdated |
2020-07-15T08:59:14+0000 |
interactionSid |
IN0bbcf93d3d5d453692eecf6a3b60ec09 |
interactionType |
VOICE |
interceptCallbackUrl
Header |
Value Example |
inboundParticipantSid |
PT70fc31025aa84031bb3400edf52079d5 |
inboundTargetSid |
IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAda85d7935b96454983154e7feb5d75ad |
inboundChannelStatus |
ringing |
inboundChannelType |
Call |
interactionAccountSid |
AC1a85c065d5ba4f4fc4ddb96469e88e4d |
interactionApplicationSid |
APP0582af44b3f04325a0f948d471f083cd |
interactionContextSid |
CTXef986543fc0b429ea16aedb28bc29336 |
interactionData |
|
interactionDateCreated |
2020-07-15T08:59:14+0000 |
interactionDateUpdated |
2020-07-15T08:59:14+0000 |
interactionSid |
IN0bbcf93d3d5d453692eecf6a3b60ec09 |
interactionType |
VOICE |
callBackUrl
Header |
Value Example |
inboundParticipantSid |
PT70fc31025aa84031bb3400edf52079d5 |
inboundTargetSid |
IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAda85d7935b96454983154e7feb5d75ad |
inboundChannelStatus |
ringing |
inboundChannelType |
Call |
interactionAccountSid |
AC1a85c065d5ba4f4fc4ddb96469e88e4d |
interactionApplicationSid |
APP0582af44b3f04325a0f948d471f083cd |
interactionContextSid |
CTXef986543fc0b429ea16aedb28bc29336 |
interactionData |
{"duration":35} |
interactionDateCreated |
2020-07-15T08:59:14+0000 |
interactionDateUpdated |
2020-07-15T08:59:14+0000 |
interactionSid |
IN0bbcf93d3d5d453692eecf6a3b60ec09 |
interactionType |
VOICE |
outboundParticipantSid |
PT5f88ad573052477d845bb4d658774958 |
outboundTargetSid |
IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CA7cee4bb9cd37483d822832f591835fff |
outboundChannelStatus |
completed |
outboundChannelType |
VOICE |
Get list of Applications
List Applications API allows users to list all the applications created under that “Business Customer”.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of Applications records to return, starting from 0. |
pageSize |
Number of records returned per page |
| If search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call. |
Filtering
Following filtering parameters are supported
| Query Parameter | Description |
|---|---|
name |
Optional parameter. Only show Application that match name text, partially or fully. |
startTime |
Optional parameter. Only show Applications that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
endTime |
Optional parameter. Only show Applications that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
Sorting Information
You can use the sortBy GET query parameter to determine which attribute you want to sort by and in which direction. Direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: sortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:
Response Parameters
Search Applications API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code.
The response returned is the JSON body as shown in the example below. Each parameters are as explained below
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
data of search as explained in Data parameters below |
Data parameters
| Data Parameter | Description |
|---|---|
result |
Applications data as explained in Data Parameter |
pageSize |
Number of records returned per page |
total |
Total Number of records |
page |
Which page of records to return |
numPages |
Total number of pages |
start |
Starting offset of page |
end |
Ending offset of page |
firstPageUri |
Unique URI that you can call to get records in First page |
nextPageUri |
Unique URI that you can call to get records in next page |
uri |
Unique URI that you can call to get records |
Example
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/applications/search?pageSize=2&page=0' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"data": {
"result": [
{
"sid": "NMAb6eb071d21124dbab20b095c25f1274f",
"name": "MyTestApplication",
"ttl": "0",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"uri": "/numbermasking/applications/search/NMAb6eb071d21124dbab20b095c25f1274f"
},
{
"sid": "NMAb6eb071d21124dbab20b095c25f1274e",
"name": "DeliveryApplication",
"ttl": "0",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-23 09:53:51",
"dateUpdated": "2019-07-23 09:53:51",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"uri": "/numbermasking/applications/search/NMAb6eb071d21124dbab20b095c25f1274e"
}
],
"pageSize": 2,
"total": 3,
"page": 0,
"numPages": 2,
"start": 0,
"end": 1,
"firstPageUri": "/messageexchange/enterprise/search/?pageSize=2&page=0",
"nextPageUri": "/messageexchange/enterprise/search/?pageSize=2&page=1",
"uri": "/messageexchange/enterprise/search/?pageSize=2&page=0"
},
"code": 200,
"message": "OK"
}Get Single Application
Single Application search API allows users to retrieve specific Application created under that “Business Customer” which means under that Communication Provider.
Response Parameters
Search Business Customer API will return an error code and corresponding HTTP error as mentioned in the Common Response Error Code section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
460 |
409 |
Application not found |
Application is not found. |
Create Context, Add Number, Update Application, Search Application, Delete Application |
Example
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/applications/search/NMAb6eb071d21124dbab20b095c25f1274f' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"data": {
"sid": "NMAb6eb071d21124dbab20b095c25f1274f",
"name": "MyTestApplication",
"ttl": "0",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b",
"uri": "/numbermasking/applications/search/NMAb6eb071d21124dbab20b095c25f1274f"
},
"code": 200,
"message": "OK"
}Update Application
Update Application allows you to update existing Application.
Request Parameters
| Parameter | Description | Type |
|---|---|---|
applicationSid |
Mandatory. Application SID that was generated by calling create |
String |
Create Application API |
Rest all request parameters are optional and are the same as explained in the Request Parameters of Create Application section. Please note if enterpriseSid is passed, it will be ignored. |
As mentioned in the Request Parameters Type of Create Application. |
Response Body
Response Body will carry Code, corresponding message and data of Application if it was successfully Updated. HTTP response will be 200 OK.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Application data as explained in the table Data Parameter of Create Application section |
Response Parameters
Create Business Customer API will return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition below are the errors it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
Error Code |
HTTP Status |
Error Message |
Description |
Category |
460 |
409 |
Application not found |
Application is not found |
Create Context, Add Number, Update Application, Search Application, Delete Application |
461 |
409 |
Application name not unique |
Application name is already used for given Business Customer |
Create Application, Update Application |
Example
{
"ttl" : "600"
}From the bash terminal you can run the command below:
curl -X PUT \
'https://yourcompany.com/numbermasking/applications/NMAb6eb071d21124dbab20b095c25f1274f' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"ttl" : "600"
}'If update of Application is successful, below is the response returned:
{
"data": {
"sid": "NMAb6eb071d21124dbab20b095c25f1274f",
"name": "MyTestApplication",
"ttl": "600",
"numberSelectionBehavior": "avoid-sticky",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/applications/search/NMAb6eb071d21124dbab20b095c25f1274f"
},
"code": 200,
"message": "OK"
}If the update of an Application fails, a corresponding error code and message is returned along with HTTP Error Response.
{
"errorCode": "461",
"message": "Application name not unique",
"data": {
"name": "MyTestApplication"
}
}Delete Application
Delete Application will delete the underlying Application. The status of Application is changed to Deleted. All open Context’s are closed and if there are ongoing calls, those are allowed to get over, but no new calls can be made. All the Masked Phone Numbers assigned will be released and are available to be assigned to other applications.
Request Parameters
| Parameter | Description | Type |
|---|---|---|
ApplicationSid |
Application SID that was generated by calling create Application API |
String |
Response Body
Response Body will carry Code, corresponding message and data of Application if it was successfully deleted ,HTTP response will be 200 OK.
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Application data as explained in the table 3.1.5.1 Data Parameter |
Response Parameters
Delete Application API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section. In addition, below are the error codes it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
460 |
409 |
Application not found |
Application is not found |
Create Context, Add Number, Update Application, Search Application, Delete Application |
Example
From the bash terminal you can run the command below:
curl -X DELETE \
'https://yourcompany.com/numbermasking/applications/NMAb6eb071d21124dbab20b095c25f1274f' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \If delete of Application is successful, below is the response returned:
{
"data": {
"sid": "APPb6eb071d21124dbab20b095c25f1274f",
"dateUpdated": "2022-06-13T14:57:13+0000",
"dateCreated": "2022-06-13T08:21:27+0000",
"accountSid": "AC771490cad8887b86327b7a185e2c4df5",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/numbermasking/applications/search/APPb6eb071d21124dbab20b095c25f1274f",
"name": "MyTestApplication",
"ttl": "600",
"enterpriseSid": "EN56aeaff5a63b473f96f1911ae68abb53"
},
"code": 200,
"message": "OK"
}If delete fails, below response is returned with corresponding HTTP Error Code
{
"code": 460,
"message": "Application not found",
"data": {
"sid": "NMAb6eb071d21124dbab20b095c25f1274f",
"name": "MyTestApplication",
"ttl": "600",
"numberSelectionBehavior": "avoid-sticky",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-08-22 09:53:51",
"uri": "/numbermasking/applications/search/NMAb6eb071d21124dbab20b095c25f1274f"
}
}Phone Numbers
Communications Provider would have reserved phone numbers for Business Customer to use.Only these numbers can be used for Number Masking.To see all Phone Numbers available for your Business Customer please call Get list of Available Phone Numbers API.
Get list of Available Phone Numbers
List Available Phone Numbers API allows users to list all the phone numbers that are allocated by Communication Provider for your Business Customer.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of Phone Numbers records to return, starting from 0. |
pageSize |
Number of records returned per page |
| If the search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call. |
Filtering
Following filtering parameters are supported
| Query Parameter | Description |
|---|---|
friendlyName |
Optional. Only show Phone Numbers that match the name text, partially or fully. |
phoneNumber |
Optional. Only show the Phone Number that starts with phoneNumber digits. This is useful to search Phone Numbers that belong to specific Country Code. |
enterpriseSid |
Optional. This parameter is mandatory for CSP_ADMIN role users. For ENTERPRISE_ADMIN users, even if this parameter is passed, its ignored. |
Sorting Information
You can use the sortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: sortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:
Sorting Attributes
| Parameter | Description |
|---|---|
friendlyName |
Sort by name |
phoneNumber |
Sort by Masked Numbers |
Response Parameters
Search Phone Number API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section.
The response returned is the JSON body as shown in the example below. Each parameters are as explained below
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
data of search as explained in Data parameters table below |
Data parameters
| Data Parameter | Description |
|---|---|
result |
Applications data as explained in Result Parameter below |
pageSize |
Number of records returned per page |
total |
Total Number of records |
page |
Which page of records to return |
numPages |
Total number of pages |
start |
Starting offset of page |
end |
Ending offset of page |
firstPageUri |
Unique URI that you can call to get records in First page |
nextPageUri |
Unique URI that you can call to get records in next page |
uri |
Unique URI that you can call to get records |
Example
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/phonenumbers/search?pageSize=2&page=0' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"data": {
"result": [
{
"sid": "PN0b4201c6c87749f29367e6cf000686cb",
"friendlyName": "Test Number",
"phoneNumber": "12013507693",
"capabilities": {
"voice_capable": true,
"sms_capable": false,
"mms_capable": false,
"fax_capable": false
},
"applicationSid": "xxx",
"uri": "/numbermasking/phonenumbers/search/PN0b4201c6c87749f29367e6cf000686cb"
},
{
"sid": "PN0b4201c6c87749f29367e6cf000686ce",
"friendlyName": "Masked Number 2",
"phoneNumber": "12012444945",
"capabilities": {
"voice_capable": true,
"sms_capable": false,
"mms_capable": false,
"fax_capable": false
},
"uri": "/numbermasking/phonenumbers/search/PN0b4201c6c87749f29367e6cf000686ce"
}
],
"pageSize": 2,
"total": 3,
"page": 0,
"numPages": 2,
"start": 0,
"end": 1,
"firstPageUri": "/numbermasking/phonenumbers/search/?pageSize=2&page=0",
"nextPageUri": "/numbermasking/phonenumbers/search/?pageSize=2&page=1",
"uri": "/numbermasking/phonenumbers/search/?pageSize=2&page=0"
},
"code": 200,
"message": "OK"
}Get Single Available Phone Number
Single Available Number search API allows users to retrieve specific Phone Number
Response Parameters
Search Context API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
471 |
409 |
Phone Number not found |
Sid of a phone number passed to be added in masked pool of an application is not found |
Add Phone Number, Search Phone Number |
Example
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/phonenumbers/search/PN0b4201c6c87749f29367e6cf000686cb' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"data": {
"sid": "PN0b4201c6c87749f29367e6cf000686cb",
"friendlyName": "Test Number",
"phoneNumber": "12013507693",
"capabilities": {
"voice_capable": true,
"sms_capable": false,
"mms_capable": false,
"fax_capable": false
},
"uri": "/numbermasking/phonenumbers/search/PN0b4201c6c87749f29367e6cf000686cb"
},
"code": 200,
"message": "OK"
}Masked Numbers
For Number Masking to work you have to associate at least one phone number with an application.Once a number is added to the application, it is called a masked number.All added numbers go into a masked number pool associated with a given application.Once a phone number is associated with an application, it cannot be assigned to another one.
Phone numbers can be marked as reserved.Reserved numbers will not be included in the list of numbers an application can choose from for a participant, but they can be manually assigned as masked numbers for participants.
Add Phone Number to Application
This endpoint will be used to add a phone number to a masked number pool for an application. If executed successfully the API returns the masked number SID that can be used to lookup details of the number or remove it from the masked pool.
Request Parameters
| Parameter | Description | Type |
|---|---|---|
applicationSid |
Mandatory. SID of Application that this Phone Number should be added to. |
String |
phoneNumberSid |
Mandatory. Sid of Incoming Phone number as explained in sid of List Phone Number API. It’s mandatory to pass the phoneNumberSid or phoneNumber as explained below. If both are passed, phoneNumberSid takes preference. |
String |
phoneNumber |
Optional. Actual phone number to be added to the masked pool. phoneNumber is Mandatory if phoneNumberSid is not passed. |
String |
isReserved |
Optional If true, the new phone number should be reserved and not be assigned to a participant using proxy pool logic. See Reserved Phone Numbers for more information. By default it is false. That means an application will use this number in number selection logic. |
Boolean |
Response Body
The Response Body will contain code, corresponding message and data of the phone number if it was successfully added to the masked number pool of an application. HTTP response will be 200 Created (OK).
The response is returned in the JSON body as shown in the example below. All parameters are listed below.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Phone Number data as explained in the below. |
Data Parameter
| Data Parameter | Description |
|---|---|
sid |
Unique Masked Number Sid. This can be later used to delete or update Phone Number in Masked Number Pool. |
phoneNumberSid |
Sid of CPaaS Incoming Phone number. |
applicationSid |
Application Sid to which Phone Number is added. |
friendlyName |
A human readable descriptive text for this resource, up to 64 characters long. By default, the FriendlyName is a nicely formatted version of the phone number. |
phoneNumber |
The incoming phone number. e.g., +16175551212 (E.164 format). |
capabilities |
This is a set of boolean properties that indicate whether a phone number can receive calls or messages. Possible capabilities are Voice, SMS, and MMS with each having a value of either true or false. |
isReserved |
Whether the new phone number should be reserved and not be assigned to a participant using Applications Masked Number Pool logic. |
inUse |
The number of open Context assigned to the number. |
accountEmail |
Unique CPaaS Account that added this particular Phone Number. |
dateCreated |
Timestamp when this Context was created. |
dateUpdated |
Timestamp when this Context was updated. |
uri |
Absolute URL of Masked Number. |
Add Phone Number API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, below are the error codes it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
460 |
409 |
Application not found |
Application is not found |
Create Context, Add Number, Update Application, Search Application, Delete Application |
470 |
409 |
Phone Number already in use |
Phone number is already assigned to an Application |
Add Phone Number |
471 |
409 |
Phone number not found |
Sid of the phone number passed to be added in masked pool of an application is not found |
Add Phone Number |
Example
{
"applicationSid": "APPb6eb071d21124dbab20b095c25f1274f",
"sid": "PN67b2dddf3636497ca3d62a7719c696ed"
}From the bash terminal you can run the command below:
curl -X POST \
'https://yourcompany.com/numbermasking/maskednumbers' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"applicationSid": "APPb6eb071d21124dbab20b095c25f1274f",
"sid": "PN67b2dddf3636497ca3d62a7719c696ed"
}'If addition of Phone Number is successful, below is the response returned:
{
"code": 200,
"message": "OK",
"data": {
"sid": "PHMb6eb071d21124dbab20b095c25f8944a",
"phoneNumberSid": "PN67b2dddf3636497ca3d62a7719c696ed",
"applicationSid": "APPb6eb071d21124dbab20b095c25f1274f",
"phoneNumber": "12013507693",
"isReserved": "false",
"inUse": 0,
"accountEmail": "jane.doe@yourcompany.com",
"accountSid":"AC85789a8353757d7d69c881155c91baee",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/maskednumbers/search/PHMb6eb071d21124dbab20b095c25f8944a"
}
}If creation fails, below response is returned with corresponding HTTP Error Code.
{
"errorCode": "470",
"message": "Phone Number already in use",
"data": {
applicationSid: "APPd77b6e1379684d048d6ee04844fed49c",
phoneNumber: "66396337999999",
inUse: 0
}
}Get list of Masked Numbers
List Masked Numbers API allows users to list all the phone numbers that are assigned to masked number pool for a given Business Customer.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of Masked Numbers records to return, starting from 0. |
pageSize |
Number of records returned per page |
| If search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call. |
Filtering
Following filtering parameters are supported
| Query Parameter | Description |
|---|---|
applicationSid |
Optional. Only show masked numbers that belong to a given application. |
enterpriseSid |
Optional. This parameter is used by users with role CSP_ADMIN to get all the numbers in the masked pool belonging to that particular Business Customer. |
isReserved |
Optional. If true, only show Masked Numbers that are marked reserved. If false, only show Masked Numbers that are not marked reserved. |
inUse |
Optional. Only show Masked Numbers that have an inUse number of Open Contexts. |
phoneNumber |
Optional.Only show Masked Number that start with phoneNumber digits. This is useful to search Masked Numbers that belong to specific Country Code. |
startTime |
Optional parameter. Only show Masked Numbers that were added to an application on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
endTime |
Optional parameter. Only show Masked Numbers that were added to an application on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
Sorting Information
You can use the sortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: sortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:
Response Parameters
Search Masked Number API will return an error code, and a corresponding HTTP error as mentioned in the Common Response Error Codes section.
The response returned is the JSON body as shown in the example below. Each parameters are as explained below
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
data of search as explained in Data parameterstable below |
Data parameters
| Data Parameter | Description |
|---|---|
result |
Masked Numbers data as explained in Data Parameter of Add Phone numbers to Application |
pageSize |
Number of records returned per page |
total |
Total Number of records |
page |
Which page of records to return |
numPages |
Total number of pages |
start |
Starting offset of page |
end |
Ending offset of page |
firstPageUri |
Unique URI that you can call to get records in first page |
previousPageUri |
Unique URI that you can call to get records in previous page |
nextPageUri |
Unique URI that you can call to get records in next page |
uri |
Unique URI that you can call to get records |
Example
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/maskednumbers/search?pageSize=2&page=0' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"data": {
"result": [
{
"sid": "PH1d0c934f9bed411484d36a63067e345d",
"dateUpdated": "2020-05-11T10:37:23+0000",
"dateCreated": "2020-05-05T06:09:11+0000",
"accountEmail": "entpuser2@testent2.com",
"accountSid":"AC85789a8353757d7d69c881155c91baee",
"uri": "/numbermasking/maskednumbers/search/PH1d0c934f9bed411484d36a63067e345d",
"applicationSid": "APP56dd5e389aa64e90846be68645288b6b",
"phoneNumberSid": "PNbaa25148dc0d469f8050847439ba77fb",
"phoneNumber": "19713316943",
"isReserved": false,
"inUse": 1
},
{
"sid": "PHccf45a3855274b01acf8172d62630881",
"dateUpdated": "2020-05-11T07:39:42+0000",
"dateCreated": "2020-05-05T06:00:54+0000",
"accountEmail": "entpuser2@testent2.com",
"accountSid":"AC85789a8353757d7d69c881155c91baee",
"uri": "/numbermasking/maskednumbers/search/PHccf45a3855274b01acf8172d62630881",
"applicationSid": "APP56dd5e389aa64e90846be68645288b6b",
"phoneNumberSid": "PN197e742df4d54efea2e70d82cdd435cd",
"phoneNumber": "15713316943",
"isReserved": false,
"inUse": 0
}
],
"pageSize": 2,
"total": 5,
"page": 0,
"numPages": 3,
"start": 0,
"end": 1,
"firstPageUri": "/numbermasking/maskednumbers/search/?enterpriseSid=ENf625475702d44d29a8d605f28aaf7d3e&pageSize=2&page=0",
"uri": "/numbermasking/maskednumbers/search/?enterpriseSid=ENf625475702d44d29a8d605f28aaf7d3e&pageSize=2&page=1"
},
"code": 200,
"message": "OK"
}Get Single Masked Number
Single Masked Number search API allows users to retrieve a specific masked number.
Response Parameters
Search Masked Number API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
472 |
409 |
Masked number Sid passed was not found in the system |
Sid of Masked Number passed to be found in masked pool of an application is not found |
Add Phone Number, Search Phone Number |
Example
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/maskednumbers/search/PHMb6eb071d21124dbab20b095c25f8944a' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"data": {
"sid": "PHfb6eb071d21124dbab20b095c25f8944a",
"phoneNumberSid": "PN67b2dddf3636497ca3d62a7719c696ed",
"applicationSid": "APPb6eb071d21124dbab20b095c25f1274f",
"phoneNumber": "12013507693",
"isReserved": "false",
"inUse": 1,
"accountEmail": "jane.doe@company.com",
"accountSid":"AC85789a8353757d7d69c881155c91baee",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/maskednumbers/search/PHfb6eb071d21124dbab20b095c25f8944a"
},
"code": 200,
"message": "OK"
}Update Masked Number
Update Masked Number allows you to update existing masked number in the pool.
Request Parameters
| Parameter | Description | Type |
|---|---|---|
maskNumberSid |
Mandatory. Masked Number SID that was generated by calling create Add Phone Number to an application. |
String |
isReserved |
Optional. If true, the updated Masked Number should not be assigned to a participant using Applications Masked Number Pool logic. |
Boolean |
Response Body
The response body will contain code, corresponding message and data of masked number if successfully updated. HTTP response will be 200 OK.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Masked Number data as explained in the table Data Parameter of Add Phone Number to Application section. |
Response Parameters
Update Masked Number API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section. In addition, below are the error codes it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
472 |
409 |
Masked number Sid passed was not found in the system |
The Sid of a Masked Number passed to be updated in the masked pool of an application is not found |
Add Phone Number, Search Phone Number |
Example
{
"isReserved" : true
}From the bash terminal you can run the command below:
curl -X PUT \
'https://yourcompany.com/numbermasking/maskednumbers/PHdb6eb071d21124dbab20b095c25f8944a' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"isReserved" : true
}'If update of Masked Number is successful, below is the response returned:
{
"data": {
"sid": "PHdb6eb071d21124dbab20b095c25f8944a",
"phoneNumberSid": "PN67b2dddf3636497ca3d62a7719c696ed",
"applicationSid": "APPb6eb071d21124dbab20b095c25f1274f",
"phoneNumber": "12013507693",
"isReserved": true,
"inUse": 0,
"accountEmail": "jane.doe@yourcompany.com",
"accountSid":"AC85789a8353757d7d69c881155c91baee",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/maskednumbers/search/PHdb6eb071d21124dbab20b095c25f8944a"
},
"code": 200,
"message": "OK"
}If update of Masked Number fails, corresponding error code and message is returned along with HTTP Error Response.
{
"errorCode": "472",
"message": "Masked number Sid passed was not found in the system",
"data": {
"sid": "PHd18e4d5dff2d4d40bda8200000000000",
"inUse": 0
}
}Remove Masked Number from Application Masked Number Pool
Remove API will remove the corresponding Masked Number from the pool. Once a Masked Number is removed from the pool, the Phone Number is available to be added in other Applications Masked Pool.
Request Parameters
| Parameter | Description | Type |
|---|---|---|
maskNumberSid |
Mandatory. Masked Number SID that was generated by calling create Add Phone Number to Application. |
String |
Response Body
Response Body will carry Code, corresponding message and data of Masked Number if it was successfully removed, HTTP response will be 200 OK.
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Masked Number data as explained in the table Data Parameter of Add Phone Number to Application section. |
Response Parameters
Remove Masked Number API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section. In addition, below are the error codes it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
472 |
409 |
Masked number Sid passed was not found in the system |
The Sid of a phone number passed to be added in the masked pool of an application is not found |
Add Phone Number, Search Phone Number, Remove Phone Number |
473 |
409 |
Masked Number in use |
Masked Number is assigned to Participant |
Remove Masked Number from Application |
Example
From the bash terminal you can run the command below:
curl -X DELETE \
'https://yourcompany.com/numbermasking/maskednumbers/PHdb6eb071d21124dbab20b095c25f8944a' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \If Remove Masked Number is successful, below is the response returned:
{
"data": {
"sid": "PHab6eb071d21124dbab20b095c25f8944a",
"phoneNumberSid": "PN67b2dddf3636497ca3d62a7719c696ed",
"applicationSid": "APPb6eb071d21124dbab20b095c25f1274f",
"phoneNumber": "12013507693",
"isReserved": false,
"inUse": 0,
"accountEmail": "jane.doe@yourcompany.com",
accountSid: "AC37112b209069e37c0cf4d296a76308c9",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/maskednumbers/search/PHdb6eb071d21124dbab20b095c25f8944a"
},
"code": 200,
"message": "OK"
}If delete fails, below response is returned with corresponding HTTP Error Code
{
"errorCode": "472",
"message": "Masked number Sid passed was not found in the system",
"data": {
"sid": "PHd18e4d5dff2d4d40bda8200000000000",
"inUse": 0
}
}Context
A Context is a single instance of two individuals communicating. It belongs to an Application and maps two Participants. A Context can be set for example between Taxi Driver and Customer and it can be active till a predefined period of time or can be deactivated upon request via API call.
Context State
Context can be in below states at any given point of time.
OPEN: The Context has not yet passed the expiry date or ttl, and there are no active communications in it.
IN_PROGRESS: The Context has active communications going in it. This is more meaningful for Voice where Context can remain In-Progress till the call is ongoing between participants.
CLOSED: The Context has either been actively closed or passed the expiry date or ttl. No more communication is possible in this state.
Create Context
This endpoint will be used to create Context within an Application. On successful execution of API, returns the Context SID that can be used to lookup Contexts later and add Participants to it.
Request Parameters
| Parameter | Description | Type |
|---|---|---|
applicationSid |
Mandatory. SID of Application that this Context belongs to. |
String |
name |
Mandatory. Unique name of Context within Application. |
String |
dateExpiry |
Optional. The ISO 8601 date when Context should expire. If this value is present, it overrides the ttl. |
Date |
ttl |
Optional. Default time to live for Context. TTL (time to live) is measured in seconds after Contexts last create or interaction. If not passed, default is taken from Application. |
Integer |
mode |
Optional. The Mode of the Session. Can be: |
String |
Response Body
The Response Body will carry Code, corresponding message and data of Context if it was successfully created. HTTP response will be 200 Created (OK).
The response returned is the JSON body as shown in the example below. Each parameters are as explained below
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Context data as explained below |
Data Parameter
| Data Parameter | Description |
|---|---|
sid |
Unique Context Sid. This can be later used to delete or update Context or add Participants. |
applicationSid |
Application SID to which Context belongs. |
name |
Unique name of Context. Name should be unique within an Application. |
dateExpiry |
The ISO 8601 date when Context should expire. |
ttl |
Default time to live for Context created in Application. TTL (time to live) is measured in seconds after Contexts last create or interaction. If not passed, default is from Application. |
mode |
The Mode of the Session. Can be: message, voice, or voice and message. The default value is voice. |
status |
Status of this Context as explained in Context State. When Context is newly created, by default it is in an Open state. |
dateLastInteraction |
The ISO 8601 date when the Context last had an interaction. |
closedReason |
The reason Context was closed. Possible values are: EXPIRED: Context expired due to ttl or dateExpiry has passed; API: Context was Closed via API call; |
accountEmail |
Unique CPaaS Account that created this particular Context. |
dateCreated |
Timestamp when this Context was created. |
dateUpdated |
Timestamp when this Context was updated. |
uri |
Absolute URL of Context. |
Create Context API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, below are the error codes it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
491 |
460 |
Application not found |
Application is not found |
Create Context, Add Number, Update Application, Search Application, Delete Application |
Example
{
"applicationSid": "APPb6eb071d21124dbab20b095c25f1274f",
"name": "TestSession1"
}From the bash terminal you can run the command below:
curl -X POST \
'https://yourcompany.com/numbermasking/contexts' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"applicationSid": "APPb6eb071d21124dbab20b095c25f1274f",
"name": "TestSession1"
}'If creation of Context is successful, below is the response returned:
{
"code": 200,
"message": "OK",
"data": {
"sid": "CTXb6eb071d21124dbab20b095c25f8932x",
"applicationSid": "APPb6eb071d21124dbab20b095c25f1274f",
"name": "TestSession1",
"mode": "voice",
"status": "OPEN",
"accountEmail": "jane.doe@yourcompany.com",
"accountSid": "AC47d4d4e6878497bfb134508c88f2d7d4",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"dateExpiry": "2019-08-22 08:30:34",
"dateLastInteraction": "2019-07-22 10:53:51",
"uri": "/numbermasking/contexts/search/CTXb6eb071d21124dbab20b095c25f8932x"
}
}If creation fails, below response is returned with corresponding HTTP Error Code
{
"errorCode": "460",
"message": "Application not found",
"data": "APP0088803a42d24a64bba89669a02e991aaa"
}Get list of Contexts
List Contexts API allows users to list all the Contexts created under a given Enterprise.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of Contexts records to return, starting from 0. |
pageSize |
Number of records returned per page |
| If search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call. |
Filtering
Following filtering parameters are supported
| Query Parameter | Description |
|---|---|
enterpriseSid |
Optional. Only show Contexts that belong to a given Business Customer. This parameter can be used only by the CSP_ADMIN role. |
applicationSid |
Optional. Only show Contexts that belongs to given Application |
name |
Optional parameter. Only show Contexts that match name text, partially or fully. |
status |
Optional parameter. Only show Contexts that match status. Possible values are explained in Context State. |
startTime |
Optional parameter. Only show Contexts that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
endTime |
Optional parameter. Only show Contexts that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
Sorting Information
You can use the sortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: sortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:
Response Parameters
Search Contexts API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section.
The response returned is the JSON body as shown in the example below. Each parameters are as explained below
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
data of search as explained in Data parameters below |
Data parameters
| Data Parameter | Description |
|---|---|
result |
Context data as explained in Data Parameter |
pageSize |
Number of records returned per page |
total |
Total Number of records |
page |
Which page of records to return |
numPages |
Total number of pages |
start |
Starting offset of page |
end |
Ending offset of page |
firstPageUri |
Unique URI that you can call to get records in First page |
nextPageUri |
Unique URI that you can call to get records in next page |
uri |
Unique URI that you can call to get records |
Example
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/contexts/search?pageSize=2&page=0' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"data": {
"result": [
{
"sid": "CTXb6eb071d21124dbab20b095c25f8932x",
"accountSid": "ACcd56013ac307ac13cfdb98cc95ff8060",
"applicationSid": "NMAb6eb071d21124dbab20b095c25f1274f",
"name": "TestSession1",
"ttl": "600",
"mode": "voice",
"status": "OPEN",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateExpiry": "2019-07-23 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/contexts/search/NMCb6eb071d21124dbab20b095c25f8932x"
},
{
"sid": "CTXb6eb071d21124dbab20b095c25f1234q",
"accountSid": "ACcd56013ac307ac13cfdb98cc95ff8060",
"applicationSid": "NMAb6eb071d21124dbab20b095c25f1274f",
"name": "TestSession2",
"ttl": "3600",
"mode": "voice",
"status": "OPEN",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateExpiry": "2019-07-23 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"dateLastInteraction": "2019-07-22 10:53:51",
"uri": "/numbermasking/contexts/search/NMCb6eb071d21124dbab20b095c25f1234q"
}
],
"pageSize": 2,
"total": 3,
"page": 0,
"numPages": 2,
"start": 0,
"end": 1,
"firstPageUri": "/numbermasking/contexts/search/?pageSize=2&page=0",
"nextPageUri": "/numbermasking/contexts/search/?pageSize=2&page=1",
"uri": "/numbermasking/contexts/search/?pageSize=2&page=0"
},
"code": 200,
"message": "OK"
}Get Single Context
Single Context search API allows users to retrieve specific Context
Response Parameters
Search Context API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
465 |
409 |
Context not found |
Context is not found |
Search Context, Update Context, Delete Context |
Example
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/contexts/search/NMCb6eb071d21124dbab20b095c25f8932x' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"data": {
"sid": "CTXb6eb071d21124dbab20b095c25f8932x",
"accountSid": "ACcd56013ac307ac13cfdb98cc95ff8060",
"applicationSid": "NMAb6eb071d21124dbab20b095c25f1274f",
"name": "TestSession1",
"ttl": "600",
"mode": "voice",
"status": "OPEN",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateExpiry": "2019-07-23 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/contexts/search/NMCb6eb071d21124dbab20b095c25f8932x"
},
"code": 200,
"message": "OK"
}Update Context
Update Context allows you to update existing Context.
Request Parameters
| Parameter | Description | Type |
|---|---|---|
contextSid |
Mandatory. Context SID that was generated by calling create Create Context API |
String |
name |
Optional. CUnique name of Context within an Application. |
String |
ttl |
Optional. Default time to live for a Context. TTL (time to live) is measured in seconds after Contexts last create or interaction. |
Integer |
status |
Optional. Change status of Context. Context can be changed from: Closed to Open, Open to Closed, In_progress to Closed. However once Closed, via update API it can only be changed to Open. In_progress state can be only set by Application business logic when the call is in progress. |
String |
dateExpiry |
Optional. If state of Context is Closed and expiry date is in future, state will be changed to Open and expiry date will be updated. Rest all request parameters are optional and are the same as explained in Request Parameters of Create Context section except applicationSid cannot be changed. |
Date |
mode |
Optional. The Mode of the Session. Can be: |
String |
Response Body
Response Body will carry Code, corresponding message and data of Application if it was successfully Updated. HTTP response will be 200 OK.
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Context data as explained in the table Data Parameter of Create Context section |
Response Parameters
Update Context API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section. In addition, below are the error codes it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
465 |
409 |
Context not found |
Context is not found |
Search Context, Update Context, Delete Context |
466 |
409 |
Context name not unique |
Context name is already used for given Application |
Create Context, Update Context |
487 |
409 |
A participant with the same participant phone number and masked phone number already exists in the system. |
Participant with the same participant phone number and masked phone already exists on another Context |
Create Context, Update Context |
489 |
409 |
Context expiration time must be in the future |
Context expiration time must be in the future |
Create Context, Update Context |
Example
{
"ttl" : "3600"
}From the bash terminal you can run the command below:
curl -X PUT \
'https://yourcompany.com/numbermasking/contexts/NMCb6eb071d21124dbab20b095c25f8932x' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"ttl" : "3600"
}'If update of Context is successful, below is the response returned:
{
"data": {
"sid": "NMCb6eb071d21124dbab20b095c25f8932x",
"applicationSid": "NMAb6eb071d21124dbab20b095c25f1274f",
"name": "TestSession1",
"ttl": "3600",
"mode": "voice",
"status": "OPEN",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/contexts/search/NMCb6eb071d21124dbab20b095c25f8932x"
},
"code": 200,
"message": "OK"
}If update of Context fails, corresponding error code and message is returned along with HTTP Error Response
{
"errorCode": "466",
"message": "Context name not unique",
"data": {
"name": "TestSession1"
}
}Delete Context
Delete Context will delete Context. If there are ongoing calls, those are allowed to get over, but no new calls can be made.
Request Parameters
| Parameter | Description | Type |
|---|---|---|
contextSid |
Context SID that was generated by calling create Context API Create Context |
String |
Response Body
Response Body will carry Code, corresponding message and data of Context if it was successfully deleted ,HTTP response will be 200 OK.
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Application data as explained in the table Data Parameter |
Response Parameters
Delete Context API will return an error code, and a corresponding HTTP error as mentioned in the Common Response Error Codes section. In addition, below are the error codes it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
465 |
409 |
Context not found |
Context is not found |
Search Context, Update Context, Delete Context |
Example
From the bash terminal you can run the command below:
curl -X DELETE \
'https://yourcompany.com/numbermasking/contexts/NMCb6eb071d21124dbab20b095c25f8932x' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \If delete of Context is successful, below is the response returned:
{
"data": {
"sid": "CTXb6eb071d21124dbab20b095c25f8932x",
"dateUpdated": "2022-06-13T15:49:20+0000",
"dateCreated": "2022-06-13T15:49:07+0000",
"accountSid": "AC3cb7543d961092eca203768a188f1d69",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/numbermasking/contexts/search/CTXb6eb071d21124dbab20b095c25f8932x",
"name": "TestSession1",
"dateExpiry": "2022-06-14T01:49:07",
"mode": "voice",
"status": "OPEN",
"applicationSid": "APPb6eb071d21124dbab20b095c25f1274f",
"dateLastInteraction": "2022-06-13T15:49:07+0000"
},
"code": 200,
"message": "OK"
}If delete fails, below response is returned with corresponding HTTP Error Code
{
"code": 465,
"message": "Context not found",
"data": {
"sid": "NMAb6eb071d21124dbab20b095c25f1274f",
"name": "MyTestApplication",
"status": "CLOSED",
"ttl": "600",
"numberSelectionBehavior": "avoid-sticky",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-08-22 11:53:51",
"uri": "/numbermasking/applications/search/NMAb6eb071d21124dbab20b095c25f1274f"
}
}Participants
A Participant is a single individual communicating in a Context.There is a limit of two Participants per Context.
You can create a Participant in two ways:
By specifying the private Phone Number of the Participant (participantPhoneNumber) and relying on Number Masking to select an appropriate Phone Number from the Masked Number pool.The Masked Number returned (maskPhoneNumber) is the Phone Number that the Participant should call to reach the other party.
By specifying both the participantPhoneNumber and the maskPhoneNumber.In this case, Number Masking will attempt to use the specified Masked Phone Number provided.
| The Masked Phone Number specified must already be added to the Masked Number pool in order to be accepted. |
Add Participants
This endpoint will be used to add Participants to a Context within an Application. On successful execution of API, returns the Participant SID that can be used to lookup Participant later and update or remove it.
Request Parameters
| Parameter | Description | Type |
|---|---|---|
contextSid |
Mandatory. SID of Context that this Participant should be added to |
String |
participantPhoneNumber |
Mandatory. Phone number of Participant (called or calling party) |
String |
friendlyName |
Optional. Friendly name assigned to describe the participant. This value must be 255 characters or fewer |
String |
maskPhoneNumberSid |
Optional. Sid of the masked phone number (received by adding Masked Number as explained in Add Phone Number to Application) to use for the Participant from Pool assigned to Application to which this Context belongs. If not specified, Application will select a number from the pool. |
String |
maskPhoneNumber |
Optional. Actual masked phone number that is present in the masked phone numbers pool will be assigned to this Participant. If both maskPhoneNumberSid and maskPhoneNumber are passed, maskPhoneNumberSid takes preference. |
String |
Response Body
Response Body will carry Code, corresponding message and data of participant if it was successfully added. HTTP response will be 200 Created (OK).
The response returned is the JSON body as shown in the example below. Each parameters are as explained below
| Parameter | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Participant data as explained in the below. |
Data Parameter
| Data Parameter | Description |
|---|---|
sid |
Unique Participant Sid. This can be later used to remove or update Participants |
applicationSid |
Application SID to which Context belongs to which Participant is added |
contextSid |
Context SID to which Participant is added |
participantPhoneNumber |
Phone number of Participant |
friendlyName |
Friendly name assigned to the participant. |
maskPhoneNumber |
Masked phone number |
maskPhoneNumberSid |
Sid of the masked phone number |
accountEmail |
Unique CPaaS Account that created this particular Context |
dateCreated |
Timestamp when this Participant was added to Context |
dateUpdated |
Timestamp whenParticipant was updated |
dateRemoved |
Timestamp when Participant was removed from Context |
uri |
Absolute URL of Participant |
Add Participant API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, below are the error codes it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
465 |
409 |
Context not found |
Context is not found |
Search Context, Update Context, Delete Context, Add Participant |
471 |
409 |
Phone Number not found |
The Sid of a phone number passed to be added in the masked pool of an application is not found. Or Masked Phone number is been added to Context but Masked Number is not present |
Add Phone Number, Search Phone Number, Remove Phone Number, Add Participant to Context |
472 |
409 |
Random masked number was not found! |
Masked number was not provided on add Participant request and no random Masked number was found |
Add Phone Number, Search Phone Number, Remove Phone Number, Add Participant to Context |
481 |
409 |
Context already have 2 Participants |
If Add participant is called while context already have 2 of them. Max allowed is 2 |
Add Participant to Context |
484 |
409 |
Can not add participants to a closed context |
Context cannot be modified or deleted as its status Closed |
Add Participant to Context |
487 |
409 |
A participant with the same phone number already exists in the same context |
Participant is already added in this Context |
Add Participant to Context |
487 |
409 |
A participant with the same participant phone number and masked phone number already exists in the system |
Participant is already added in another Context |
Add Participant to Context |
Example
{
"contextSid": "NMCb6eb071d21124dbab20b095c25f8932x",
"participantPhoneNumber": "15713316943"
}From the bash terminal you can run the command below:
curl -X POST \
'https://yourcompany.com/numbermasking/participants' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"contextSid": "NMCb6eb071d21124dbab20b095c25f8932x",
"participantPhoneNumber": "15713316943"
}'If addition of Participant is successful, below is the response returned:
{
"code": 200,
"message": "OK",
"data": {
"sid": "NMPb6eb071d21124dbab20b095c25f1111d",
"applicationSid": "NMAb6eb071d21124dbab20b095c25f1274f",
"contextSid": "NMCb6eb071d21124dbab20b095c25f8932x",
"participantPhoneNumber": "15713316943",
"friendlyName": "Amit Mobile",
"maskPhoneNumber": "12013507693",
"maskPhoneNumberSid": "NMMb6eb071d21124dbab20b095c25f8944a",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/participants/search/NMPb6eb071d21124dbab20b095c25f1111d"
}
}If addition fails, below response is returned with corresponding HTTP Error Code
{
"errorCode": "465",
"message": "Context not found",
"data": {
"sid": "CTXd6ecc4d93e804024a8c211b76391df97a"
}
}Get list of Participants
List Participants API allows users to list all the Participants added under that Enterprise. As of today max 2 Participants can be added under a Context.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of Participants records to return, starting from 0. |
pageSize |
Number of records returned per page |
|
If search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call. |
Filtering
Following filtering parameters are supported
| Query Parameter | Description |
|---|---|
enterpriseSid |
Optional. Only show Participants that belong to the passed enterpriseSid. This is used by user with role CSP_ADMIN |
applicationSid |
Optional. Only show Participants under all Contexts that belongs to given Application |
contextSid |
Optional. Only show Participants under given Context |
participantPhoneNumber |
Optional. Only show Participants who have PhoneNumber starting with |
friendlyName |
Optional. Only show Participants that match name text, partially or fully. |
maskPhoneNumber |
Optional. Only show Participants who have masked Phone Number starting with |
startTime |
Optional parameter. Only show Participant that were added on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
endTime |
Optional parameter. Only show Contexts that were added on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
Sorting Information
You can use the sortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: sortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:
Response Parameters
Search Contexts API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section.
The response returned is the JSON body as shown in the example below. Each parameters are as explained below
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
data of search as explained in Data parameters below |
Data parameters
| Data Parameter | Description |
|---|---|
result |
Participant data as explained in Data Parameter |
pageSize |
Number of records returned per page |
total |
Total Number of records |
page |
Which page of records to return |
numPages |
Total number of pages |
start |
Starting offset of page |
end |
Ending offset of page |
firstPageUri |
Unique URI that you can call to get records in First page |
nextPageUri |
Unique URI that you can call to get records in next page |
uri |
Unique URI that you can call to get records |
Example
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/participants/search?pageSize=2&page=0' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"data": {
"result": [
{
"sid": "NMPb6eb071d21124dbab20b095c25f1111d",
"applicationSid": "NMAb6eb071d21124dbab20b095c25f1274f",
"contextSid": "NMCb6eb071d21124dbab20b095c25f8932x",
"participantPhoneNumber": "15713316943",
"friendlyName": "Amit Mobile",
"maskPhoneNumber": "12013507693",
"maskPhoneNumberSid": "NMMb6eb071d21124dbab20b095c25f8944a",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/participants/search/NMPb6eb071d21124dbab20b095c25f1111d"
},
{
"sid": "NMPb6eb071d21124dbab20b095c25f2222e",
"applicationSid": "NMAb6eb071d21124dbab20b095c25f1274f",
"contextSid": "NMCb6eb071d21124dbab20b095c25f8932x",
"participantPhoneNumber": "15713316944",
"friendlyName": "Amit Mobile2",
"maskPhoneNumber": "12012444945",
"maskPhoneNumberSid": "NMMb6eb071d21124dbab20b095c25f8955b",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/participants/search/NMPb6eb071d21124dbab20b095c25f2222e"
}
],
"pageSize": 2,
"total": 3,
"page": 0,
"numPages": 2,
"start": 0,
"end": 1,
"firstPageUri": "/numbermasking/participants/search/?pageSize=2&page=0",
"nextPageUri": "/numbermasking/participants/search/?pageSize=2&page=1",
"uri": "/numbermasking/contexts/participants/?pageSize=2&page=0"
},
"code": 200,
"message": "OK"
}Get Single Participant
Single Participant search API allows users to retrieve specific Participant
Response Parameters
Search Participant API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
482 |
409 |
Participant not found |
Sid of Participant passed is not found |
Search Single Participant |
Example
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/participants/search/NMPb6eb071d21124dbab20b095c25f1111d' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"data": {
"sid": "NMPb6eb071d21124dbab20b095c25f1111d",
"applicationSid": "NMAb6eb071d21124dbab20b095c25f1274f",
"contextSid": "NMCb6eb071d21124dbab20b095c25f8932x",
"participantPhoneNumber": "15713316943",
"friendlyName": "Amit Mobile",
"maskPhoneNumber": "12013507693",
"maskPhoneNumberSid": "NMMb6eb071d21124dbab20b095c25f8944a",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/participants/search/NMPb6eb071d21124dbab20b095c25f1111d"
},
"code": 200,
"message": "OK"
}Remove Participant
Remove Participant API will remove Participant from Context. If there are ongoing calls, those are allowed to get over, but no new calls can be made.
Request Parameters
| Parameter | Description | Type |
|---|---|---|
participantSid |
Participant SID that was generated by calling Add Participant API |
String |
Response Body
Response Body will carry Code, corresponding message and data of Participant if it was successfully removed ,HTTP response will be 200 OK.
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
Participant data as explained in the table Data Parameter |
Response Parameters
Remove Participant API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section. In addition, below are the error codes it can return.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
482 |
409 |
Participant not found |
Sid of Participant passed is not found |
Search Single Participant |
Example
From the bash terminal you can run the command below:
curl -X DELETE \
'https://yourcompany.com/numbermasking/participants/NMPb6eb071d21124dbab20b095c25f1111d' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \If remove of Participant is successful, below is the response returned:
{
"data": {
"sid": "PTb6eb071d21124dbab20b095c25f1111d",
"dateUpdated": "2022-06-12T06:28:16+0000",
"dateCreated": "2022-06-12T06:28:16+0000",
"accountSid": "ACcec457624bcb789e490d0b00e66d67ca",
"accountEmail": "jane.doe@yourcompany.com",
"uri": "/numbermasking/applications/search/PTb6eb071d21124dbab20b095c25f1111d",
"contextSid": "CTXb6eb071d21124dbab20b095c25f8932x",
"participantPhoneNumber": "15713316943",
"applicationSid": "APPb6eb071d21124dbab20b095c25f1274f",
"friendlyName": "Amit Mobile",
"maskPhoneNumberSid": "PNb6eb071d21124dbab20b095c25f8944a",
"maskPhoneNumber": "12013507693"
},
"code": 200,
"message": "OK"
}If remove fails, below response is returned with corresponding HTTP Error Code
{
"code": 482,
"message": "Participant already removed",
"data": {
"sid": "NMPb6eb071d21124dbab20b095c25f1111d",
"applicationSid": "NMAb6eb071d21124dbab20b095c25f1274f",
"contextSid": "NMCb6eb071d21124dbab20b095c25f8932x",
"participantPhoneNumber": "15713316943",
"friendlyName": "Amit Mobile",
"maskPhoneNumber": "12013507693",
"maskPhoneNumberSid": "NMMb6eb071d21124dbab20b095c25f8944a",
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"dateRemoved": "2019-07-22 11:53:51",
"uri": "/numbermasking/participants/search/NMPb6eb071d21124dbab20b095c25f1111d"
}
}Interactions
Interactions are read-only Call Detail Records of a given Context.Each Interaction represents a single communication Caller and Called Participant.
“From Number” Masking point of view its two legs of call, one in coming call leg and other outgoing call leg.
Get list of Interactions
List Interactions API allows users to list all the Interactions that have happened over the past 6 months. After 6 months, data is purged and you need to contact Support to get data.
Paging
The following paging parameters are supported
| Query Parameter | Description |
|---|---|
page |
Which page of Interactions records to return, starting from 0. |
pageSize |
Number of records returned per page |
| If the search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call. |
Filtering
Following filtering parameters are supported
| Query Parameter | Description |
|---|---|
applicationSid |
Optional. Only show Interactions under all Contexts that belongs to given Application |
contextSid |
Optional. Only show Interactions under given Context |
inboundParticipantPhoneNumber |
Optional. Only show Interactions that have a Calling Party PhoneNumber starting with |
outboundParticipantPhoneNumber |
Optional. Only show Interactions that have a Called Party PhoneNumber starting with |
inboundMaskPhoneNumber |
Optional. Only show Interactions that have Called Masked Phone Number starting with |
outboundMaskPhoneNumber |
Optional. Only show Interactions that have a Calling Masked Phone Number starting with |
startTime |
Optional parameter. Only show Interactions that were added on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
endTime |
Optional parameter. Only show Interactions that were added on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
Sorting Information
You can use the sortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: sortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:
Response Parameters
Search Contexts API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section.
The response returned is the JSON body as shown in the example below. Each parameters are as explained below
| Code | Description |
|---|---|
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
data |
data of Interactions as explained in Data parameters below |
Data parameters
| Data Parameter | Description |
|---|---|
result |
Interactions data as explained in Interaction Data Parameter |
pageSize |
Number of records returned per page |
total |
Total Number of records |
page |
Which page of records to return |
numPages |
Total number of pages |
start |
Starting offset of page |
end |
Ending offset of page |
firstPageUri |
Unique URI that you can call to get records in First page |
nextPageUri |
Unique URI that you can call to get records in next page |
uri |
Unique URI that you can call to get records |
Interactions Data Parameter
| Data Parameter | Description |
|---|---|
sid |
Unique Sid of Interaction |
applicationSid |
Application Sid |
contextSid |
Context Sid |
inboundParticipantSid |
Sid of Inbound Participant |
inboundTargetSid |
Target sid of this leg of interaction in CPaaS platform |
inboundParticipantPhoneNumber |
Phone number of Caller party (Participant Phone Number) |
inboundMaskPhoneNumber |
Mask Phone Number called by inboundParticipantPhoneNumber |
inboundChannelStatus |
Status of Channel for inbound leg. |
outboundParticipantSid |
Sid of Outbound Participant |
outboundTargetSid |
Target Sid of this leg of interaction in CPaaS platform |
outboundParticipantPhoneNumber |
Phone number of Called party (Participant Phone Number) |
outboundMaskPhoneNumber |
Mask Phone Number calling outboundParticipantPhoneNumber |
outboundChannelStatus |
Status of Channel for outbound leg |
type |
The Type of the Interaction. Can be: MESSAGE, VOICE. As of today only Voice is supported. |
data |
A JSON string that includes call duration (when available) of a call (e.g. {"duration": "5"}). |
accountEmail |
Unique CPaaS Account that created this particular Interaction |
dateCreated |
Timestamp when Interaction was created |
dateUpdated |
Timestamp when Interaction was updated |
uri |
Absolute URL of Interaction |
Example
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/interactions/search?pageSize=2&page=0' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"data": {
"result": [
{
"sid": "NMIb6eb071d21124dbab20b095c25f0007k",
"applicationSid": "NMAb6eb071d21124dbab20b095c25f1274f",
"contextSid": "NMCb6eb071d21124dbab20b095c25f8932x",
"inboundParticipantSid": "NMPb6eb071d21124dbab20b095c25f1111d",
"inboundTargetSid": "ID308543a39dfd49b7a7231df9622763d8-CAf397453213fc43208e4d238e79809e99",
"inboundParticipantPhoneNumber": "15713316943",
"inboundMaskPhoneNumber": "12013507693",
"inboundChannelStatus": "completed",
"outboundParticipantSid": "NMPb6eb071d21124dbab20b095c25f2222e",
"outboundTargetSid": "ID1f2a2222772f4195948d040a2ccc648c-CA019d4b96e188484caec75b8b906ceb51",
"outboundParticipantPhoneNumber": "15713316944",
"outboundMaskPhoneNumber": "12012444945",
"outboundChannelStatus": "completed",
"type": "VOICE",
"data": {
"duration": "28"
},
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 09:53:51",
"dateUpdated": "2019-07-22 09:53:51",
"uri": "/numbermasking/interactions/search/NMIb6eb071d21124dbab20b095c25f0007k"
},
{
"sid": "NMIb6eb071d21124dbab20b095c25f0008p",
"applicationSid": "NMAb6eb071d21124dbab20b095c25f1274f",
"contextSid": "NMCb6eb071d21124dbab20b095c25f8932x",
"inboundParticipantSid": "NMPb6eb071d21124dbab20b095c25f1111d",
"inboundTargetSid": "ID308543a39dfd49b7a7231df9622763d8-CAf397453213fc43208e4d238e79809e97",
"inboundParticipantPhoneNumber": "15713316943",
"inboundMaskPhoneNumber": "12013507693",
"inboundChannelStatus": "completed",
"outboundParticipantSid": "NMPb6eb071d21124dbab20b095c25f2222e",
"outboundTargetSid": "ID1f2a2222772f4195948d040a2ccc648c-CA019d4b96e188484caec75b8b906ceb52",
"outboundParticipantPhoneNumber": "15713316944",
"outboundMaskPhoneNumber": "12012444945",
"outboundChannelStatus": "completed",
"type": "VOICE",
"data": {
"duration": "294"
},
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated": "2019-07-22 11:53:51",
"dateUpdated": "2019-07-22 11:53:51",
"uri": "/numbermasking/interactions/search/NMIb6eb071d21124dbab20b095c25f0008p"
}
],
"pageSize": 2,
"total": 3,
"page": 0,
"numPages": 2,
"start": 0,
"end": 1,
"firstPageUri": "/numbermasking/interactions/search/?pageSize=2&page=0",
"nextPageUri": "/numbermasking/interactions/search/?pageSize=2&page=1",
"uri": "/numbermasking/interactions/participants/?pageSize=2&page=0"
},
"code": 200,
"message": "OK"
}Get Single Interaction
Single Interaction search API allows users to retrieve specific Participant
Response Parameters
Search Interaction API will return an error code and a corresponding HTTP error as mentioned in the Common Response Error Codes section.
| Error Code | HTTP Status | Error Message | Description | Category |
|---|---|---|---|---|
490 |
400 |
Interaction not found |
Sid of Interaction passed is not found |
Search Single Interaction |
Example
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/interactions/search/NMIb6eb071d21124dbab20b095c25f0007k' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"data": {
"sid": "NMIb6eb071d21124dbab20b095c25f0007k",
"applicationSid": "NMAb6eb071d21124dbab20b095c25f1274f",
"contextSid": "NMCb6eb071d21124dbab20b095c25f8932x",
"inboundParticipantSid": "NMPb6eb071d21124dbab20b095c25f1111d",
"inboundTargetSid": "ID308543a39dfd49b7a7231df9622763d8-CAf397453213fc43208e4d238e79809e99",
"inboundParticipantPhoneNumber": "15713316943",
"inboundMaskPhoneNumber": "12013507693",
"inboundChannelStatus": "completed",
"outboundParticipantSid": "NMPb6eb071d21124dbab20b095c25f2222e",
"outboundTargetSid": "ID1f2a2222772f4195948d040a2ccc648c-CA019d4b96e188484caec75b8b906ceb51",
"outboundParticipantPhoneNumber": "15713316944",
"outboundMaskPhoneNumber": "12012444945",
"outboundChannelStatus": "completed",
"type": "VOICE",
"data": {
"duration": "28"
},
"accountEmail": "jane.doe@yourcompany.com",
"dateCreated":"2019-07-22 09:53:51",
"dateUpdated":"2019-07-22 09:53:51",
"uri": "/numbermasking/interactions/search/NMIb6eb071d21124dbab20b095c25f0007k"
},
"code": 200,
"message": "OK"
}Usage Records
The Usage record REST resource provides a simple API to retrieve usage made by your Number Masking during any time period and by any Mode (Voice, Message or VoiceAndMessage).This makes it easy to build reporting and analytics tools for your application.
Usage Records for Number Masking consists of Contexts created, Voice minutes including number of calls, and SMS Units.
| Usage Records data is collected every 15 minutes. So there is possibility that once Context/Interaction is completed, it may take maximum 15 minutes to be reflected in the Usage Records. |
Context
Filtering
Usage filters will return usage records for the passed filter. Following filtering parameters are supported.
| Query Parameter | Description |
|---|---|
category |
Optional. Only include Usage records for specific Category. - all If not passed, default is “all” which includes Contexts created for every mode. |
startTime |
Only include usage that has occurred on or after this date. Format is YYYY-MM-DD. All dates are in GMT. As a convenience, you can also specify offsets to today. For example, StartDate=-30days will make StartDate be 30 days before today. |
endTime |
Only include usage that has occurred on or before this date. Format is YYYY-MM-DD. All dates are in GMT. As a convenience, you can also specify offsets to today. For example, EndDate=+30days will make EndDate be 30 days from today. |
organisationSid |
Mandatory for SUPPORT_ADMIN users. Only include Usage records for Specific Organisation. Only users with SUPPORT_ADMIN role can pass this parameter. If users with any other role passes this parameter, it’s ignored. |
enterpriseSid |
Optional. Only include Usage records for specific Business Customer. If CSP_ADMIN is calling this API and enterpriseSid is not passed, Usage Records for the entire Organisation are retrieved. For ENTERPRISE_ADMIN use this parameter is ignored. |
applicationSid |
Optional. Only include Usage records for Specific Application. If ENTERPRISE_ADMIN is calling this API and applicationSid is not passed, Usage Records for that Business Customer are retrieved. |
Example Usage:
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/contexts/usage/records?startDate=2019-07-01&endDate=2019-07-23' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"usageRecords": [
{
"category": "voice",
"description": "Total Contexts created",
"startDate": "2019-07-01",
"endDate": "2019-07-23",
"count": "2123",
"countUnit": "Contexts",
"usage": "2123",
"usageCount": "Contexts",
"uri": "/numbermasking/contexts/usage/record?startDate=2019-07-01&endDate=2019-07-23"
}
]
}Request Subresource
The main UsageRecords list resource supports a variety of convenience subresources. In general these take the form:
/numbermasking/contexts/usage/records/{subResource}
Supported subresources are:
| Subresource | Description |
|---|---|
daily |
Return Usage record on a daily basis. If no date filter is passed, last 30 days usage is retrieved. |
monthly |
Return Usage record on a monthly basis. If no date filter is passed, last 12 months usage is retrieved |
yearly |
Return Usage record on yearly basis. If no date filter is passed, only this year and previous year usage is retrieved. |
today |
Return Usage record today. |
yesterday |
Return Usage record yesterday. |
thismonth |
Return Usage record this month. |
lastmonth |
Return Usage record last month. |
Filters mentioned in the Phone Numbers Filtering section can also be passed.
Example
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/contexts/usage/records/daily?startDate=2019-07-21&endDate=2019-07-23' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"usageRecords": [
{
"category": "voice",
"description": "Total Contexts created",
"startDate": "2019-07-21",
"endDate": "2019-07-21",
"count": "101",
"countUnit": "Contexts",
"usage": "101",
"usageUnit": "Contexts",
"uri": "/numbermasking/usage/records/daily?startDate=2019-07-21&endDate=2019-07-21"
},
{
"category": "voice",
"description": "Total Contexts created",
"startDate": "2019-07-22",
"endDate": "2019-07-22",
"count": "134",
"countUnit": "Contexts",
"usage": "134",
"usageUnit": "Contexts",
"uri": "/numbermasking/usage/records/daily?startDate=2019-07-22&endDate=2019-07-23"
}
]
}In the above example if you don’t pass “startDate”and “endDate” parameters, 30 records will be shown.
Interactions
Filtering
Usage filters will return usage records for the passed filter. Following filtering parameters are supported.
| Query Parameter | Description |
|---|---|
category |
Only include Usage records for specific Mode. Possible values are: voice, message and voiceandmessage. Default one is voice. |
startTime |
Only include usage that has occurred on or after this date. Format is YYYY-MM-DD. All dates are in GMT. As a convenience, you can also specify offsets to today. For example, StartDate=-30days will make StartDate be 30 days before today. |
endTime |
Only include usage that has occurred on or before this date. Format is YYYY-MM-DD. All dates are in GMT. As a convenience, you can also specify offsets to today. For example, EndDate=+30days will make EndDate be 30 days from today. |
organisationSid |
Mandatory for SUPPORT_ADMIN users. Only include Usage records for Specific Organisation. Only users with SUPPORT_ADMIN role can pass this parameter. If users with any other role pass this parameter, it’s ignored. |
enterpriseSid |
Optional. Only include Usage records for specific Business Customer. If CSP_ADMIN is calling this API and enterpriseSid is not passed, Usage Records for the entire Organisation are retrieved. For ENTERPRISE_ADMIN use this parameter is ignored. |
applicationSid |
Optional. Only include Usage records for Specific Application. If ENTERPRISE_ADMIN is calling this API and applicationSid is not passed, Usage Records for that Business Customer are retrieved. |
Example Voice Usage
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/interactions/usage/records?startDate=2019-07-01&endDate=2019-07-23?category=voice' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"usageRecords": [
{
"category": "voice",
"description": "Total Voice mins and Counts",
"enterpriseSid": "ACae6e420f425248d6a26948c17a9e2acf",
"startDate": "2019-07-01",
"endDate": "2019-07-23",
"count": "2123",
"countUnit": "calls",
"usage": "1777369.00000",
"usageUnit": "minutes",
"uri": "/numbermasking/interactions/usage/record?startDate=2019-07-01&endDate=2019-07-23"
}
]
}Example Message Usage
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/interactions/usage/records?startDate=2019-07-01&endDate=2019-07-23?category=message' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"usageRecords": [
{
"category": "message",
"description": "Total Message Counts",
"enterpriseSid": "ACae6e420f425248d6a26948c17a9e2acf",
"startDate": "2019-07-01",
"endDate": "2019-07-23",
"count": "2123",
"countUnit": "messages",
"usage": "2534.00000",
"usageUnit": "messages",
"uri": "/numbermasking/interactions/usage/record?startDate=2019-07-01&endDate=2019-07-23"
}
]
}Request Subresource
The main Usage Records list resource supports a variety of convenience subresources. In general these take the form:
/numbermasking/interactions/usage/records/{Subresource}
Supported subresources are:
| Subresource | Description |
|---|---|
daily |
Return Usage record on a daily basis. If no date filter is passed, last 30 days usage is retrieved. |
monthly |
Return Usage record on a monthly basis. If no date filter is passed, last 12 months usage is retrieved |
yearly |
Return Usage record on yearly basis. If no date filter is passed, only this year and previous year usage is retrieved. |
today |
Return Usage record today. |
yesterday |
Return Usage record yesterday. |
thismonth |
Return Usage record this month. |
lastmonth |
Return Usage record last month. |
| The filters mentioned in Phone Numbers Filtering section can also be passed. |
Example:
From the bash terminal you can run the command below:
curl -X GET \
'https://yourcompany.com/numbermasking/interactions/usage/records/daily?startDate=2019-07-21&endDate=2019-07-23' \
--user '{your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \Below is the response returned:
{
"usageRecords": [
{
"category": "voice",
"description": "Total Voice mins and Counts",
"enterpriseSid": "ACae6e420f425248d6a26948c17a9e2acf",
"startDate": "2019-07-21",
"endDate": "2019-07-21",
"count": "101",
"countUnit": "calls",
"usage": "177.00000",
"usageUnit": "minutes",
"uri": "/numbermasking/interactions/usage/records/daily?startDate=2019-07-21&endDate=2019-07-21"
},
{
"category": "voice",
"description": "Total Voice mins and Counts",
"enterpriseSid": "ACae6e420f425248d6a26948c17a9e2acf",
"startDate": "2019-07-22",
"endDate": "2019-07-22",
"count": "134",
"countUnit": "calls",
"usage": "197.00000",
"usageUnit": "minutes",
"uri": "/numbermasking/interactions/usage/records/daily?startDate=2019-07-22&endDate=2019-07-23"
}
]
}| If you don’t pass “startDate” and “endDate” parameters, 30 records will be shown. |