Reference Turnkey Applications Tutorials Visual Designer
Reference Turnkey Applications Tutorials Visual Designer
    • REST API
      • Overview
      • API Endpoint
      • Authentication
      • Requests
      • Responses
      • Paging
      • Reason Codes Dictionary
    • Management APIs
      • Accounts
      • Identity Access Management BETA
        • Identity Access Management Overview
        • Identity Access Management API
          • User Management
            • Create a User
            • Update a User
            • Retrieve a User
            • Delete a User
          • API Keys Management
            • Create an API Key
            • Update an API Key
            • Retrieve an API Key
            • Delete an API Key
      • Applications
      • Clients
        • Create a Client
        • Delete a Client
        • Change Client’s Password
        • Get a List of Available Clients
      • Incoming Phone Numbers
        • IncomingPhoneNumber Instance Resource
        • IncomingPhoneNumbers List Resource
        • Local IncomingPhoneNumber Factory Resource
        • Toll-Free IncomingPhoneNumber Factory Resource
        • Mobile IncomingPhoneNumber Factory Resource
        • Attach a phone number to an application
        • Enable Incoming MMS for an Application
        • Delete a phone number
        • List of Phone Numbers
        • Incoming Phone Number Regex Support
      • Notifications
      • Usage Records
      • Trace Records
    • Voice
      • Calls
        • Call List Resource URI
        • Making a Call
        • Modifying Live Calls
        • Examples
        • List Filter
        • Paging Information
      • Conference Management
        • Supported Operations
        • Conference List Resource URI
      • Conference Participants Management
        • Participants List Resource URI
      • Gather DTMF
      • Gather Speech
      • Say
      • Play
      • Hold
      • Recordings
      • Refers
        • Resource Properties
        • Supported Operations
        • Paging Information
      • Resume
      • SIP Refer Support
    • Messages API - BETA
      • Overview
      • Channel Identities
      • Send Message
      • Status Callback Parameters
      • Status Callback Events
      • Receive Message
        • Incoming Message Request Parameters
      • Get Message List
      • Get Single Message
      • Message Attributes
      • Status Description
    • SMS
      • Messages
        • Send SMS
        • Get SMS List
        • Get single SMS Information
        • SMS Attributes
      • Error Codes
    • Email
    • RCML
      • Overview
        • Interacting with Your Application
        • RCML Verbs
      • Dial
        • Client
        • Conference
        • Number
        • SIP
      • Email
      • Gather
      • Say
      • Play
      • SMS
      • Message - Beta
      • Hold
      • Resume
      • Hangup
      • Pause
      • Redirect
      • Record
      • Reject
      • Refer
    • Visual Designer API
      • List Application Templates
      • :List a Specific Application Template
      • Create a Visual Designer Application
      • Get Application Details
      • Save Application Changes
      • Create Application Parameters
      • List Application Parameters
      • Delete Application Parameters
      • Upload Application Media Files
      • List Application Media Files
      • Play Application Media Files
      • Delete Application Media Files
      • Get Application Logs
      • Delete Application Logs
      • Get Application Settings
      • Modify Application Settings
      • Rename an Application
      • Delete an Application
      • Get Visual Designer Configuration
    • Turnkey Apps APIs
      • Smart 2FA
        • Sending One-Time Passwords
        • Verifying One-Time Passwords
        • Cancel One-Time Passwords
        • Session Detail Record (SDR)
        • Get list of One-Time Passwords
        • Get a Single One-Time Password
        • Usage Record One-Time Passwords
        • Common Response Error Code
        • Limit
          • Create Limit
          • Update Limit
          • Delete Limit
          • Get List of Limits
      • Call Queuing
      • Auto Attendant
        • Users
        • Announcement
        • Auto Attendant System
        • Menu
        • Schedule
        • Phone Number
        • Usage Records
        • Third Party Integration
      • Number Masking
        • Application
        • Mask Number Pool
        • Context
        • Participants
        • Interactions
        • Usage Records
      • Task Router
docs 1.0
  • docs
    • 1.0
  • docs
  • Enterprise:Turnkey Apps APIs
  • Enterprise:Number Masking

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:

  • Application

  • Masked Number Pool

  • Context

  • Participants

  • Interactions

  • Usage Records

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.

Base Resource URI

\https://$DOMAIN

Create Application Resource URI

/numbermasking/applications

Supported Operations

HTTP POST: Create Application

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 0, which means unlimited time to live.

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 none.

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:
- message
- voice
- voiceandmessage

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”.

Base Resource URI

\https://$DOMAIN

Get List of Applications Resource URI

/numbermasking/applications/search

Supported Operations

HTTP GET: List Applications

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:

Sort Attributes
Parameter Description

name

Sort by name.

dateCreated

Sort by the date when the Business Customer was created.

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.

Base Resource URI

\https://$DOMAIN

Get Single Application Resource URI

/numbermasking/applications/search/{applicationSid}

Supported Operations

HTTP GET: Specific Application

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.

Base Resource URI

\https://$DOMAIN

Update Application Resource URI

/numbermasking/applications/{applicationSid}

Supported Operations

HTTP PUT: Update 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.

Base Resource URI

\https://$DOMAIN

Delete Application Resource URI

/numbermasking/applications/{applicationSid}

Supported Operations

HTTP DELETE: Delete Application

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.

Base Resource URI

\https://$DOMAIN

Get List of Available Phone Numbers Resource URI

/numbermasking/phonenumbers/search

Supported Operations

HTTP GET: List Phone Numbers

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

Result Parameters
Data Parameter Description

sid

Unique SID identifying this Phone Number

phoneNumber

Actual phone number

friendlyName

Friendly name of this phone number

capabilities

Capability of Phone number

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

Base Resource URI

\https://$DOMAIN

Get Single Available Phone Number Resource URI

/numbermasking/phonenumbers/search/{phoneNumberSid}

Supported Operations

HTTP GET: 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.

Base Resource URI

\https://$DOMAIN

Create Masked Phone Number Resource URI

/numbermasking/maskednumbers

Supported Operations

HTTP POST: Add phone number to number masked pool of an application

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.

Base Resource URI

\https://$DOMAIN

Get List of Masked Numbers Resource URI

/numbermasking/maskednumbers/search

Supported Operations

HTTP GET: List Masked Numbers

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:

Sort Attributes
Parameter Description

friendlyName

Sort by name

dateCreated

Sort by date when Masked Number was created

phoneNumber

Sort by Masked Numbers

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.

Base Resource URI

\https://$DOMAIN

Get Single Masked Number Resource URI

/numbermasking/maskednumbers/search/{maskNumberSid}

Supported Operations

HTTP GET: 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.

Base Resource URI

\https://$DOMAIN

Update Masked Number Resource URI

/numbermasking/maskednumbers/{maskNumberSid}

Supported Operations

HTTP PUT: Update Masked Number

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.

Base Resource URI

\https://$DOMAIN

Delete Masked Number Resource URI

/numbermasking/maskednumbers/{maskNumberSid}

Supported Operations

HTTP DELETE: Remove Masked Number

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.

Base Resource URI

\https://$DOMAIN

Create Context Resource URI

/numbermasking/contexts

Supported Operations

HTTP POST: Create Context

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:
- message
- voice
- voiceandmessage
The default value is voice.

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.

Base Resource URI

\https://$DOMAIN

Get List of Contexts Resource URI

/numbermasking/contexts/search

Supported Operations

HTTP GET: List Contexts

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:

Sort Attributes
Parameter Description

name

Sort by name

dateCreated

Sort by date when Context was created

status

Sort by status of Context

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

Base Resource URI

\https://$DOMAIN

Get Single Context Resource URI

/numbermasking/contexts/search/{contextSid}

Supported Operations

HTTP GET: 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.

Base Resource URI

\https://$DOMAIN

Update Context Resource URI

/numbermasking/context/{contextSid}

Supported Operations

HTTP PUT: Update 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:
- message
- voice
- voiceandmessage

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.

Base Resource URI

\https://$DOMAIN

Delete Context Resource URI

/numbermasking/contexts/{contextSid}

Supported Operations

HTTP DELETE: Delete Context

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.

Base Resource URI

\https://$DOMAIN

Create Participant Resource URI

/numbermasking/participants

Supported Operations

HTTP POST: Add Participant

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.

Base Resource URI

\https://$DOMAIN

Get List of Participants Resource URI

/numbermasking/participants/search

Supported Operations

HTTP GET: List Participants

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 participantPhoneNumber digits. This helps to find Participants in specific country

friendlyName

Optional. Only show Participants that match name text, partially or fully.

maskPhoneNumber

Optional. Only show Participants who have masked Phone Number starting with maskPhoneNumber digits.

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:

Sort Attributes
Parameter Description

friendlyName

Sort by name

participantPhoneNumber

Sort by date when Context was created

maskPhoneNumber

Sort by status of Context

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

Base Resource URI

\https://$DOMAIN

Get Single Participant Resource URI

/numbermasking/participants/search/{participantSid}

Supported Operations

HTTP GET: 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.

Base Resource URI

\https://$DOMAIN

Delete Participant Resource URI

/numbermasking/participants/{participantSid}

Supported Operations

HTTP DELETE: Remove Participant

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.

Base Resource URI

\https://$DOMAIN

Get List of Interactions Resource URI

/numbermasking/interactions/search

Supported Operations

HTTP GET: List Interactions

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 inboundParticipantPhoneNumber digits.

outboundParticipantPhoneNumber

Optional. Only show Interactions that have a Called Party PhoneNumber starting with outboundParticipantPhoneNumber digits.

inboundMaskPhoneNumber

Optional. Only show Interactions that have Called Masked Phone Number starting with inboundMaskPhoneNumber digits.

outboundMaskPhoneNumber

Optional. Only show Interactions that have a Calling Masked Phone Number starting with outboundMaskPhoneNumber digits.

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:

Sort Attributes
Parameter Description

dateCreated

Sort by date when Context was created

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

Base Resource URI

\https://$DOMAIN

Get Single Interaction Resource URI

/numbermasking/interactions/search/{interactionSid}

Supported Operations

HTTP GET: Specific Interaction

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

Base Resource URI

\https://$DOMAIN

Get Context Usage Resource URI

/numbermasking/contexts/usage/records

Supported Operations

HTTP GET: List usage records for Number Masking

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
- voice
- message
- voiceandmessage

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

Base Resource URI

\https://$DOMAIN

Get Mapping Usage Resource URI

/numbermasking/interactions/usage/records

Supported Operations

HTTP GET: List usage records for 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.
Platform

Programmable Voice

Programmable SMS

Turnkey Applications

Smart 2FA

Call Queue

Auto Attendant

Number Masking

Task Router

Campaign Manager

Learn

Terms And Conditions

About

ABOUT

CONTACT US

© 2020, All rights reserved.