Number Masking API

Introduction

Telestax Number Masking exposes white label API to obfuscate called/calling parties. To find out more about that please visit the General documentation.

Below API explains how Communication Provider can manage Business Customers and add Users under Business Customer.

Whenever Communication Provider adds a new Business Customer, it asks for a mandatory User under that Business Customer. This User gets created under Restcomm as a Sub-Account of Communication Provider Organisation. Communication Provider should provision all the Phone Numbers under this Sub-Account in Restcomm as explained in documentation here. These phone numbers are available to Business Customer to create a Masked Number Pool for any Application.

It is expected that Communication Provider will not share newly created User credentials with Business Customers. Communication Provider should create more Users via User Management API and only share newly created credentials. This is because the first User created for Business Customer will have all the Phone Numbers provisioned and Communication Provider wouldn’t want Business Customers to make any changes to those numbers.
The API(s) described in this document are only available for communication providers. In addition, communication providers also have access to API(s) exposed to business customers. Please sign in here the see the API(s) available to business customers.

Terminology

As part of this documentation, the following terms will be used to describe specific individuals, concepts, and organizations.

Communications Provider

Communications Provider generally refers to any organization providing communications products, applications, capabilities, or services. The term can refer to operators, carriers, providers, suppliers, or any other entity that delivers communications capabilities to enterprise or business customers.

Business Customer

An enterprise or business customer that relies on a Communications Provider to deliver communications products, capabilities, or services to customers or end users.

Business Customer

Communication Provider’s can create, manage, delete Business Customers. This is logical grouping of Communication Provider customers and helps to easily manage billing/invoices for Business Customer.

Create Business Customer

This endpoint will be used to create an Business Customer in the Number Masking. Create Business Customer will add unique Business Customer name for given Communication Provider.

Base Resource URI

https://your_custom_domain.com

Create Business Customer Resource URI

/numbermasking/enterprises

Supported Operations

HTTP POST: Create Business Customer

Request Parameters

Parameter Description Type

enterpriseAdmin

Business Customer User data explained in the table below that will be assigned as the admin of this Business Customer. An account will be created on restcomm with these values.

String

name

Mandatory name of Business Customer. Name must be unique within the given Communication Provider Organisation.

String

configuration

Optional. Accepts JSON Body in the following format:

{
"numberMasking":{
"concurrentMaskNumberLimit":"10"
}
}


In how many concurrent sessions masked number can be used simultaneously. Minimum value can be 1. If the Business Customer tries to use masked number in more sessions than the the number set in “concurrentMaskNumberLimit” , the application will throw an error code 474 “Masked Numbers are not available”.

The default "concurrentMaskNumberLimit" is 100.

JSON
Business Customer Admin Parameters:
Business Customer Admin data Parameter Description

password

Business Customer Admin password

name

Friendly name of the Business Customer admin

emailId

Business Customer’s Admin User email Id

Response Body

The response body will contain code, corresponding message and data of Business Customer if it was successfully created. The HTTP response will be 201 Created (OK).

The response returned is the JSON body as shown in the example below. All parameters are listed below.

Parameter Description

data

Business Customer data as explained in the Data Parameter below.

code

Sub-error code for response

message

Message describing error if error occurred or success message
Data Parameter
Data Parameter Description

enterpriseAdminSid

Restcomm Account sid created under Restcomm for Business Customer Admin user

sid

Unique Business Customer Id

accountEmail

Unique Restcomm Account that created this particular Business Customer

dateCreated

Timestamp when this Business Customer was created

dateUpdated

Timestamp when this Business Customer was updated

name

Name of this Business Customer

uri

Unique URI that you can call to get only this specific Business Customer

enterpriseAdminEmail

Email id of Business Customer Admin

Response Parameters

Create Business Customer API can also return an error code and a corresponding HTTP error as mentioned in the Common Response Error Code section. In addition, below are the error codes it can return

Error Code HTTP Status Error Message Description Category

477

400

Error in creating an account on Restcomm

Error while creating am account in restcomm

Create Business Customer, Update Business Customer

475

400

Business Customer name not unique

Business Customer name already exists in the database

Create Business Customer, Update Business Customer

476

400

User not unique

User already exists

Create Business Customer, Update Business Customer

Example:

{
  "name": "test Enterprise",
  "enterpriseAdmin": {
    "emailId": "Testenterprise@telestax.com",
    "password": "Telestax@123",
    "name": "test user"
  }
}

From the bash terminal you can run the command below:

curl -X POST \
  https://cloud.restcomm.com/numbermasking/enterprises \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "test Enterprise",
  "enterpriseAdmin": {
    "emailId": "Testenterprise@telestax.com",
    "password": "Telestax@123",
    "name": "test user"
  }
}’

If creation of Business Customer is successful, below is the response returned:

{
  "data": {
    "sid": "EN54e3389b5bf34896876b86e139cca614",
    "dateUpdated": "2020-01-27T11:14:10+0000",
    "dateCreated": "2020-01-27T11:14:10+0000",
    "accountEmail": "subhahu.reddy@telestax.com",
    "uri": "/numbermasking/enterprises/search/EN54e3389b5bf34896876b86e139cca614",
    "name": "test Enterprise",
    "enterpriseAdminEmail": "Testenterprise@telestax.com",
    "enterpriseAdminSid": "RCSe107da10db554ef79934fd7aa6a97f71"

  },
  "code": 200,
  "message": "OK"
}

If creation fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "460",
    "message": "Enterprise name not unique",
    "data": {
        "name": "test Enterprise",
        "enterpriseAdmin": {
            "emailId": "Testenterprise@telestax.com",
            "password": "Telestax@123",
            "status": "ACTIVE",
            "name": "test user"
        }
    }
}

Get list of Business Customer

This API allows users to list all the Business Customers created under that “Organisation” which means under that Communication Provider.

Base Resource URI

https://your_custom_domain.com

Get List of Business Customer Resource URI

/numbermasking/enterprises/search

Supported Operations

HTTP GET: List Business Customer

Paging

The following paging parameters are supported

Query Parameter Description

pageSize

Number of records returned per page

page

Which page of Business Customer records to return, starting from 0.
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

endTime

Optional parameter. Only show Business Customers 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.

Name

Optional parameter. Only show Business Customers that match name text, partially or fully.

startTime

Optional parameter. Only show Business Customer 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.

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 Business Customer was created.

name

Sort by name

Response Parameters

Search Business Customer API will return an error code and a corresponding HTTP Error as mentioned in Common Response Error Code section.

The response returned is JSON body as shown in the example below. Each SDR parameters are as explained below

Code Description

data

data of search as explained in table below

code

Sub-error code for response

message

Message describing error if error occured or success message
Data parameters
Data Parameter Description

uri

Unique URI that you can call to get records

result

list of Business Customer data as explained in the table 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

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://cloud.restcomm.com/numbermasking/enterprises/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": "EN838bcdf35f9d421fad3ab516195b873b",
                "dateUpdated": "2020-01-21T13:35:19+0000",
                "dateCreated": "2020-01-21T13:35:16+0000",
                "accountEmail": "derick.adams@acme.com",
                "uri": "/numbermasking/enterprises/search/EN838bcdf35f9d421fad3ab516195b873b",
                "name": "Enterprise2",
"enterpriseAdminSid": "RCSe107da10db554ef79934fd7aa6a97f72",
                "enterpriseAdminEmail": "testbg@acme-ent2.com"
            },
            {
                "sid": "ENc4a6ddacbea548f7b7b2dca120d5ff20",
                "dateUpdated": "2020-01-15T05:36:10+0000",
                "dateCreated": "2020-01-15T05:36:09+0000",
                "accountEmail": "derick.adams@acme.com",
                "uri": "/numbermasking/enterprises/search/ENc4a6ddacbea548f7b7b2dca120d5ff20",
                "name": "Enterprise1",
"enterpriseAdminSid": "RCSe107da10db554ef79934fd7aa6a97f71",
                "enterpriseAdminEmail": "testbg@acme-ent1.com"
            }
        ],
        "pageSize": 10,
        "total": 2,
        "page": 0,
        "numPages": 1,
        "start": 0,
        "end": 1,
        "firstPageUri": "/numbermasking/enterprises/search/?pageSize=10&page=0",
        "uri": "/numbermasking/enterprises/search/?pageSize=10&page=0"
    },
    "code": 200,
    "message": "OK"
}

Get Single Business Customer

Single Business Customer search API allows users to retrieve specific Business Customer created under that “Organisation” which means under that Communication Provider.

Base Resource URI

https://your_custom_domain.com

Get Single Business Customer Resource URI

/numbermasking/enterprises/search/{EnterpriseId}

Supported Operations

HTTP GET: Specific Business Customer

Response Parameters

Search Business Customer API will return an error code and a corresponding HTTP Error as mentioned in Common Response Error Code section.

Error Code HTTP Status Error Message Description Category

478

400

Business Customer not found

Business Customer is not found.

Update Business Customer, Search Business Customer, Delete Business Customer

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://cloud.restcomm.com/numbermasking/enterprises/search/EN838bcdf35f9d421fad3ab516195b873b \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
    "data": {
        "sid": "EN838bcdf35f9d421fad3ab516195b873b",
        "dateUpdated": "2020-01-21T13:35:19+0000",
        "dateCreated": "2020-01-21T13:35:16+0000",
        "accountEmail": "derick.adams@acme.com",
        "uri": "/numbermasking/enterprises/search/EN838bcdf35f9d421fad3ab516195b873b",
        "name": "Enterprise2",
        "enterpriseAdminSid": "RCSe107da10db554ef79934fd7aa6a97f71",
        "enterpriseAdminEmail": "testbg@acme.com"
    },
    "code": 200,
    "message": "OK"
}

Update Business Customer

This endpoint will be used to update an existing Business Customer.

Base Resource URI

https://your_custom_domain.com

Update Business Customer Resource URI

/numbermasking/enterprises/{enterpriseSid}

Supported Operations

HTTP PUT: Update Business Customer

Request Parameters

Parameter Description Type

name

Name must be unique within the given Communication Provider Organisation.

String

enterpriseSid

Unique Id of the Business Customer

String

Response Body

Response Body will carry Code, corresponding message and data of Enterprise if it was successfully updated. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

data

Business Customer data as explained in the table Data Parameter.

code

Sub-error code for response

message

Message describing error if error occurred or success message

Update Business Customer API can also return an error code and a corresponding HTTP error as mentioned in the Common Response Error Code section. In addition, below are the error codes it can return

Error Code HTTP Status Error Message Description Category

478

400

Business Customer not found

Business Customer Id not found

Create Business Customer, Update Business Customer

475

400

Business Customer name not unique

Business Customer name already exists in database

Create Business Customer, Update Business Customer

Example

{
    "name" : "Enterprise3"
}

From the bash terminal you can run the command below:

curl -X PUT \
  https://cloud.restcomm.com/numbermasking/enterprises/EN54e3389b5bf34896876b86e139cca614  \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "name" : "Enterprise3"
}’

If updating of Business Customer is successful, below is the response returned:

{
  "data": {
    "sid": "EN54e3389b5bf34896876b86e139cca614",
    "dateUpdated": "2020-01-27T11:14:10+0000",
    "dateCreated": "2020-01-27T11:14:10+0000",
    "accountEmail": "subhahu.reddy@telestax.com",
    "uri": "/numbermasking/enterprises/search/EN54e3389b5bf34896876b86e139cca614",
    "name": "Enterprise3",
    "enterpriseAdminEmail": "Testenterprise@telestax.com"
  },
  "code": 200,
  "message": "OK"
}

If the update of the Business Customer fails, below is the response returned. Exact error code and message will depend on error occurred

{
    "errorCode": "478",
    "message": "Business Customer not found",
    "data": {
        "sid": "EN838bcdf35f9d421d3ab516195b873b"
    }
}

Delete Business Customer

This endpoint will be used to delete an existing Business Customer.

If you Delete a Business Customer, all the users under that Business Customer will be “Suspended” under Restcomm. If you want to “Close” these accounts, please sign in using Restcomm Console and mark these Accounts as closed.

Base Resource URI

https://your_custom_domain.com

Delete Business Customer Resource URI

/numbermasking/enterprises/{enterpriseSid}

Supported Operations

HTTP Delete: Delete Business Customer

Request Parameters

Parameter Description Type

enterpriseSid

SID to uniquely identify a Business Customer

String

Response Body

The response body will contain code, corresponding message and data of Business Customer if it was successfully deleted. HTTP response will be 200 OK.

The response returned is the JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

data

Business Customer data as explained in the table Data Parameter

code

Sub-error code for response

message

Message describing error if error occurred or success message

Response Parameters

Delete Business Customer API can also return an error code and a corresponding HTTP error as mentioned in the Common Response Error Code section. In addition, below are the error codes it can return

Error Code HTTP Status Error Message Description Category

479

409

Business Customer has Applications assigned to it

Business Customer has active Applications

Delete Business Customer

478

400

Business Customer not found

Business Customer SID doesn’t exist in the system

Update Business Customer, Delete Business Customer, Get Business Customer

Example

the bash terminal you can run the command below:

curl -X DELETE \
  https://cloud.restcomm.com/numbermasking/enterprises/ENb6eb071d21124dbab20b095c25f1274f   \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

If deletion of Business Customer is successful, below is the response returned:

{
    "data": {
        "sid": "EN54e3389b5bf34896876b86e139cca614",
        "dateUpdated": "2020-01-27T11:14:14+0000",
        "dateCreated": "2020-01-27T11:14:10+0000",
        "accountEmail": "subhahu.reddy@telestax.com",
        "uri": "/numbermasking/enterprises/search/EN54e3389b5bf34896876b86e139cca614",
        "name": "test Enterprise",
        "enterpriseAdminEmail": "Testenterprise@telestax.com"
    },
    "code": 200,
    "message": "OK"
}

If delete fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "478",
    "message": "Business Customer not found",
    "data": {
        "sid": "EN54e3389b5bf34896876b86e139cca614"
    }
}

Users

Create User

This endpoint will be used to create user depending on role as explained below

  • SUPPORT: Role for Telestax Support

    • CRUD another user with role SUPPORT

    • Read all Business Customers and within Business Customer

      • Read all Users

      • Read all Applications and within Application

        • Read all Contexts

        • Read Masked Pool Numbers

        • Read Participants

        • Read Interactions

      • Read all available Phone Numbers

      • Read Usage Records

  • CSP_ADMIN: Role for Communication Provider Admin (Admin Account in Restcomm).

    • Can create Business Customer and within Business Customer

      • CRUD users with role ENTERPRISE_ADMIN

      • CRUD Phone Numbers available for Number Masking. These numbers will be provisioned in top level ENTERPRISE_ADMIN sub-account under Restcomm

      • CRUD Applications and within Application

        • CRUD all Contexts

        • CRUD Masked Pool Numbers

        • CRUD Participants

        • CRUD Interactions

      • Read Usage Records

  • ENTERPRISE_ADMIN: Role for Business Customer users

    • CRUD users with role ENTERPRISE_ADMIN

    • Read Phone Numbers available for Number Masking.

    • CRUD Applications and within Application

      • CRUD all Contexts

      • CRUD Masked Pool Numbers

      • CRUD Participants

      • CRUD Interactions

    • Read Usage Records

Base Resource URI

https://your_custom_domain.com

Add User Resource URI

/numbermasking/users

Supported Operations

HTTP POST: Add User

Request Parameters

Parameter Description Type

enterpriseSid

Sid of the Business Customer the user belongs to.

String

name

Optional. Full name of the user being added

String

emailId

Required. Email Id of the user

String

password

Password associated with this user.

String

role

Required. Possible values are:
- SUPPORT (This is specifically for Telestax Support)
- CSP_ADMIN
- ENTERPRISE_ADMIN

String

status

Optional. Will be set to active if not passed. Possible values are:
- ACTIVE
- SUSPENDED
- DELETED

String
If Sub-Account was already added in Restcomm-console, adding the same user as ENTERPRISE_ADMIN is possible by specifying the same emailId. The password passed will not be changed in Restcomm and users can still sign in with existing credentials.

Response Body

Response Body will carry the Code, corresponding message and data of the User if it was successfully created. HTTP response will be 200 Created (OK).

The response returned is JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

data

User data as explained in the table below.

code

Sub-error code for response

message

Message describing error if error occured or success message
Data Parameter
Data Parameter Description

uri

Unique URI that you can call to get only this specific user

sid

Unique User Id

accountEmail

Unique Restcomm Account that created this particular user

dateCreated

Timestamp when this User was created

dateUpdated

Timestamp when this User was updated

name

Name of this user

emailId

Email Id of the user created

role

Role of the user

status

Status of the user (ACTIVE/SUSPENDED)

Response Parameters

Create User API can also return an error code and a corresponding HTTP error as mentioned in the Common Response Error Code section. In addition, below are the error codes it can return

Error Code HTTP Status Error Message Description Category

501

409

Restcomm am account belongs to a different Admin account

user id is already sub account to different account

Create User, Update User

499

400

Error in creating an account on Restcomm

Error while creating an account in restcomm(password fail)

Create User, Update User

478

409

Business Customer not found

Business Customer for which user is to be added is not found.

Create User, Update User

500

409

User not unique

A user already exists in the DB with provided emailId

Create User, Update User

Example

{
   "status":"ACTIVE",
   "name":"Test BG 2",
   "enterpriseSid":"EN838bcdf35f9d421fad3ab516195b873b",
   "emailId":"testbgadmin2@telestax.com",
   "password":"W31Comet0@@!",
   "role":"ENTERPRISE_ADMIN"
}

From the bash terminal you can run the command below:

curl -X POST \
  https://cloud.restcomm.com/numbermasking/users  \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
   "status":"ACTIVE",
   "name":"Test BG 2",
   "enterpriseSid":"EN838bcdf35f9d421fad3ab516195b873b",
   "emailId":"testbgadmin2@telestax.com",
   "password":"W31Comet0@@!",
   "role":"ENTERPRISE_ADMIN"
}’

If creation of User is successful, below is the response returned

{
    "data": {
        "sid": "RCS31e4303c3d06409a9e7a847fc7221bd0",
        "dateUpdated": "2020-01-27T05:50:02+0000",
        "dateCreated": "2020-01-27T05:50:02+0000",
        "accountEmail": "subhahu.reddy@telestax.com",
        "uri": "/numbermasking/users/search/RCS31e4303c3d06409a9e7a847fc7221bd0",
        "emailId": "testbgadmin2@telestax.com",
        "status": "ACTIVE",
        "role": "ENTERPRISE_ADMIN",
        "name": "Test BG 2"
    },
    "code": 200,
    "message": "OK"
}

If creation fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "499",
    "message": "Error in creating an account on Restcomm",
    "data": {
        "emailId": "testbgadmin2@telestax.com",
        "password": "W31Comet0@@!",
        "status": "ACTIVE",
        "role": "ENTERPRISE_ADMIN",
        "name": "Test BG 2",
        "enterpriseSid": "EN838bcdf35f9d421fad3ab516195b873b"
    }
}

Get list of Users

This endpoint will be used to get a list of users.

Base Resource URI

https://your_custom_domain.com

Get User list Resource URI

/numbermasking/users/search

Supported Operations

HTTP GET: Get User list

Paging

The following paging parameters are supported

Query Parameter Description

pageSize

Number of records returned per page

page

Which page of Users records to return, starting from 0.
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

endTime

Optional parameter. Only show users 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.

name

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

emailId

Optional parameter. Only show Users that match email text, partially or fully.

role

Optional parameter. Only show users that have this particular role.

enterpriseSid

Optional Parameter. Only show users for this particular Business Customer.

status

Optional parameter. Only show users that have this particular status.

startTime

Optional parameter. Only show users 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.

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 created date

name

Sort by name

email

Sort by email

Response Body

The response body will contain code, corresponding message and data of User if it was successfully fetched. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Each parameters are as explained below

Code Description

data

data of search as explained in table below

code

Sub-error code for response

message

Message describing error if error occured or success message
Data parameters
Data Parameter Description

uri

Unique URI that you can call to get records

result

list of Users data as explained in the table 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

Example

From the bash terminal you can run the command below:

curl -X GET \
  https://cloud.restcomm.com/numbermasking/users/search?enterpriseSid=EN54e3389b5bf34896876b86e139cca614 \
--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": "RCS6de60a360c75453893b5b6d1503b7276",
        "dateUpdated": "2020-01-27T11:14:14+0000",
        "dateCreated": "2020-01-27T11:14:14+0000",
        "accountEmail": "subhahu.reddy@telestax.com",
        "uri": "/numbermasking/users/search/RCS6de60a360c75453893b5b6d1503b7276",
        "emailId": "Testenterprise@telestax.com",
        "status": "ACTIVE",
        "role": "ENTERPRISE_ADMIN",
        "name": "testbg"
      }
    ],
    "pageSize": 10,
    "total": 1,
    "page": 0,
    "numPages": 1,
    "start": 0,
    "end": 0,
"firstPageUri": "/numbermasking/users/search/?enterpriseSid=EN54e3389b5bf34896876b86e139cca614&pageSize=10&page=0",
"uri": "/numbermasking/users/search/?enterpriseSid=EN54e3389b5bf34896876b86e139cca614&pageSize=10&page=0"
  },
  "code": 200,
  "message": "OK"
}

Get Single User

Single User search API allows users to retrieve specific User.

Base Resource URI

https://your_custom_domain.com

Get Single User Resource URI

/numbermasking/users/search/{userId}

Supported Operations

HTTP GET: Specific User

Response Parameters

Search User API will return an error code and a corresponding HTTP Error as mentioned in Common Response Error Code section.

Error Code HTTP Status Error Message Description Category

502

409

User not found.

User is not found.

Delete User, Update User, Get User

Example:

From the bash terminal you can run the command below:

curl -X GET \
  https://cloud.restcomm.com/numbermasking/users/search/AAEb6eb071d21124dbab20b095c25f1274f \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Below is the response returned:

{
         "code":”200”,
         "message":"OK",
         “data”:
{
        “sid":"AAEb6eb071d21124dbab20b095c25f1274f",
        “accountEmail”:”jane.doe@yourcompany.com”,
        "dateCreated":"2019-07-22 09:53:51",
        "dateUpdated":"2019-07-22 09:53:51",
          "name" : "test",
          “emailId”:”test@telestax.com”,
           “role”: “ENTERPRISE-ADMIN”,
           “enterpriseSid”: “ EN801e792d86504368a9385314e8c5c4d6”,
        "uri":/numbermasking/users/search/ AAEb6eb071d21124dbab20b095c25f1274f "
}
 }

Update User

This endpoint will be used to update existing users.

  • SUPPORT can make changes to all users irrespective of role.

  • CSP_ADMIN can make changes to all users with role ENTERPRISE_ADMIN of all Businesses within an Organisation.

  • ENTERPRISE_ADMIN cannot make any changes to other users.

Base Resource URI

https://your_custom_domain.com

Update User Resource URI

/numbermasking/users/{UserSid}

Supported Operations

HTTP PUT: Update User

Request Parameters

Parameter Description Type

enterpriseSid

Optional Enterprise id. If user wants to move user from one business to another, pass the enterpriseId of the target business customer.

String

UserSid

Mandatory. Unique id of the user

String

status

Optional. Status of the user, could be one of the following:
- ACTIVE
- SUSPENDED
- DELETED

String

name

Optional. Name of user to be updated.

String

Response Body

The response body will contain code, corresponding message and data of User if it was successfully updated. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

data

User data as explained in the table Data Parameter

code

Sub-error code for response

message

Message describing error if error occured or success message

Response Parameters

Update User API can also return an error code and a corresponding HTTP error as mentioned in the Common Response Error Code section. In addition, below are the error codes it can return

Error Code HTTP Status Error Message Description Category

502

400

User Id not found

User Id not found

Update User

478

400

Business Customer not found

Business Customer for which user is to be added is not found.

Create User, Update User

501

400

Restcomm account belongs to a different Admin account

user id is already sub account to different account

Create User, Update User

Example

{
"status":"SUSPENDED"
}

From the bash terminal you can run the command below:

curl -X PUT \
  https://cloud.restcomm.com/numbermasking/users/RCSb4ba60022d87407db2134146e3bd4ceb \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
"status":"SUSPENDED"
}’

If User update is successful, below is the response returned:

{
    "data": {
        "sid": "RCSb4ba60022d87407db2134146e3bd4ceb",
        "dateUpdated": "2020-01-29T05:21:28+0000",
        "dateCreated": "2020-01-21T13:35:19+0000",
        "accountEmail": "derick.adams@acme.com",
        "uri": "/numbermasking/users/search/RCSb4ba60022d87407db2134146e3bd4ceb",
        "emailId": "testbg@acme-ent2.com",
        "status": "SUSPENDED",
        "role": "ENTERPRISE_ADMIN",
        "name": "Ent2 Test Admin"
    },
    "code": 200,
    "message": "OK"
}

If updating fails, below response is returned with corresponding HTTP Error Code

{
    "errorCode": "502",
    "message": "User Id not found",
    "data": {
        "sid": "RCSb4ba60022d87407db2134146e3bd4c"
    }
}

Delete User

This endpoint will be used to delete an existing user. In Restcomm, users will be DELETED. To find out more about account deletion, please refer to the documentation here.

Base Resource URI

https://your_custom_domain.com

Delete User Resource URI

/numbermasking/users/{UserSid}

Supported Operations

HTTP DELETE: Delete User

Request Parameters

Parameter Description Type

UserSid

SID of the user to be deleted

String

Response Body

The response body will contain code, corresponding message and data of User if it was successfully deleted. HTTP response will be 200 OK.

The response returned is JSON body as shown in the example below. Each parameters are as explained below

Parameter Description

data

User data as explained in the table Data Parameter.

code

Sub-error code for response

message

Message describing error if error occured or success message

Response Parameters

Delete User API can also return an error code and a corresponding HTTP error as mentioned in the Common Response Error Code section. In addition, below are the error codes it can return

Error Code HTTP Status Error Message Description Category

503

400

The user is a business customer admin

The user is a business customer admin

Delete user

502

500

User Id not found

User SID doesn’t exist in the system

Update User
Delete user
Get User

Example

From the bash terminal you can run the command below:

curl -X DELETE \
  https://cloud.restcomm.com/numbermasking/users/RCS31e4303c3d06409a9e7a847fc7221bd0	 \
--user  ' {your_account_SID}:{your_account_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'

If User delete is successful, below is the response returned:

{
    "data": {
        "sid": "RCS31e4303c3d06409a9e7a847fc7221bd0",
        "dateUpdated": "2020-01-27T05:50:02+0000",
        "dateCreated": "2020-01-27T05:50:02+0000",
        "accountEmail": "subhahu.reddy@telestax.com",
        "uri": "/numbermasking/users/search/RCS31e4303c3d06409a9e7a847fc7221bd0",
        "emailId": "testbgadmin2@telestax.com",
        "status": "ACTIVE",
        "role": "ENTERPRISE_ADMIN",
        "name": "Test BG 2"
    },
    "code": 200,
    "message": "OK"
}

If delete fails, below response is returned with corresponding HTTP Error Code

{
  "code":502,
  "message":"User not found",
   “data”:{
   	          "sid”:” RCS31e4303c3d06409a9e7a847fc7221bd0”
}
}