About the Number Masking API Reference

You use the Number Masking API to hide the true phone numbers of two callers. To do this, you:

  1. Create an application.
  2. Add phone numbers to your application in a phone number masking pool. These phone numbers are pulled as needed to mask caller phone numbers.
  3. You then create a context. A context is an interaction between two participants. For example, talking on the phone about where to meet for a delivery or ride pickup.
  4. You connect your contexts to applications as needed to handle calls.
  5. In each context, you add two participants. An exchange between the participants is an interaction. Mitto records each interaction so you can review it if need be.

The features of the API include:

  • Number masking for both callers.
  • Control of masked number assignment and use.
  • Search capabilities for masked numbers, applications, participants, contexts, and interactions.
  • The ability to update and delete numbers from a masked pool.
  • The ability to update and delete applications and contexts.

We divide the information about the Number Masking API into the following sections:

Number Masking API Endpoints

Create an Application

You must create an application and assign phone numbers to it made available by your service provider. This creates a pool of mask numbers that can be drawn from whenever you need to mask someone’s phone number in your application.

You create an application by sending a POST request to:
https://cpaas.mittoapi.com/numbermasking/applications

Get a List of Applications

To retrieve a list of your applications, you send a GET request to:
https://cpaas.mittoapi.com/numbermasking/applications/search

Get a Single Application

You can retrieve details about a specific application if you have the identification number for the application. Send a GET request to:
https://cpaas.mittoapi.com/numbermasking/applications/search/{ApplicationSid}

Update an Application

You can update details about an existing application. Send a PUT request to:
https://cpaas.mittoapi.com/numbermasking/applications/{ApplicationSid}

Delete Application

Delete any application you created by sending a DELETE request to:
https://cpaas.mittoapi.com/numbermasking/applications/{ApplicationSid}

Get List of Available Phone Numbers for Masking

You can see what phone numbers can be used for masking. Send a GET request to:
https://cpaas.mittoapi.com/numbermasking/phonenumbers/search

Get Single Available Phone Number

Retrieve a single, specific phone number for phone masking if it is available. Send a GET request to:
https://cpaas.mittoapi.com/numbermasking/phonenumbers/search/{phoneNumberSid}

Add Phone Number to an Application

You can add a phone number to a mask number pool for an application. Send a POST request to:
https://cpaas.mittoapi.com/numbermasking/maskednumbers

Get a List of Masked Numbers

Get a list of all the masked numbers for a particular application. Send a GET request to:
https://cpaas.mittoapi.com/numbermasking/maskednumbers/search

Get a Single Masked Number

Retrieve a specific masked number. Send a GET request to:
https://cpaas.mittoapi.com/numbermasking/maskednumbers/search/{MaskNumberSid}

Update a Masked Number

Update a masked number. Send a PUT request to:
https://cpaas.mittoapi.com/numbermasking/maskednumbers/{maskNumberSid}

Remove a Masked Number from an Application’s Masked Number Pool

Remove a masked number from an application’s masked number pool. Send a DELETE request to:
https://cpaas.mittoapi.com/numbermasking/maskednumbers/{maskNumberSid}

Create a Context

A context is a single instance of two individuals communicating. It belongs to an application and maps two participants. Create a context by sending a POST request to:
https://cpaas.mittoapi.com/numbermasking/contexts

Get a List of Contexts

To see what contexts you created under a particular application, send a GET request to:
https://cpaas.mittoapi.com/numbermasking/contexts/search

Get Single Context

Retrieve a specific context from an application. Send a GET request to:
https://cpaas.mittoapi.com/numbermasking/contexts/search/{ContextSid}

Update Context

Update an existing context with a PUT request to:
https://cpaas.mittoapi.com/numbermasking/contexts/{ContextSid}

Delete a Context

You can delete a context you created by sending a DELETE request to:
https://cpaas.mittoapi.com/numbermasking/contexts/{ContextSid}

Add Participants to a Context

Add participants to a context with a POST request to:
https://cpaas.mittoapi.com/numbermasking/participants

Retrieve a List of Participants

You can retrieve a list of participants in a context. Send a GET request to:
https://cpaas.mittoapi.com/numbermasking/participants/search

Get a Single Participant

Retrieve a single participant from a context. Send a GET request to:
https://cpaas.mittoapi.com/numbermasking/participants/search/{ParticipantSid}

Remove Participant

Remove a participant from a context. Send a DELETE request to:
https://cpaas.mittoapi.com/numbermasking/contexts/{ContextSid}

Get a List of Interactions

An interaction is a call detail record for a given context. Each interaction represents a single communication caller and called participant. Get a list of interactions with a GET request to:
https://cpaas.mittoapi.com/numbermasking/interactions/search

Get a Single Interaction

You can retrieve an individual interaction. Send a GET request to:
https://cpaas.mittoapi.com/numbermasking/interactions/search/{INteractionSid}

Create, Update, or Delete an Application Endpoint

You can create, update and delete applications with the applications endpoint.

Create

You must create an application in order to set up a number masking pool for phone numbers. This endpoint creates an application when you send a POST request to: https://cpaas.mittoapi.com/numbermasking/applications

When your request is a success, you receive a response containing an application ID. This ID is used to add and remove phone numbers in the number masking pool for the application, as well as handle contexts. A context is a single instance of two individuals communicating.

Update

You can also update an application by appending the application’s ID to the endpoint and sending a PUT request to: https://cpaas.mittoapi.com/numbermasking/applications/{ApplicationSid}

You may use any of the parameters available when you create an application.

Delete

You can delete an application by appending the application’s ID to the endpoint and sending a DELETE request to: https://cpaas.mittoapi.com/numbermasking/applications/{ApplicationSid}

Request Parameters for Creating, Updating, or Deleting an Application

This section provides request parameters for creating an application. POST requests are for creating an application. PUT requests are for updating an application. DELETE requests are for deleting an application.

Parameter Name Data Type Required Description
enterpriseSid string yes The unique identifier for your enterprise. If you do not know your ID, contact Mitto for assistance. This is for use with either updating or deleting an application. You can also append it to the end of the endpoint, as detailed in the introduction to this section.
name string yes A unique name for your application. If you use this with updating an application, you overwrite the existing name you entered when creating the application.
ttl string no Time to Live. The default amount of time for your application contexts to live. TTL is measured in seconds after a context’s last create date or interaction. If not passed, the default is 0, which is unlimited. If you use this with updating an application, it overwrites the previous value.
geoMatchLevel string no If a masked number must be located relative to the participant phone number, use this. 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.
callBackUrl string no URL to call when the interaction status changes. To unset the existing value pass an empty string like “”.
interceptCallbackUrl string no 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 “”.
outOfContextCallbackUrl string no 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. To unset an existing value pass an empty string like “”.

Response Parameters for Creating, Updating, or Deleting an Application

When you create, update or delete an application, the returned response contains the status code and message describing the success or failure of your request. Details about your application are also provided if your request was successful.

Response Description
code Sub-error code for response
message A message describing an error if an error occurred or a success message.
data
Response Description
sid The unique application ID. You can use this to delete or update your application
enterpriseSid Sid of your enterprise. It will match what you sent in your request.
name Unique name of application. The name should be unique within an Enterprise.
ttl The default time to live for a context created in an application. TTL is measured in seconds after the context’s last create date or interaction. If you do not pass one, the default value is 0 which is unlimited.
accountEmail The email associated with the account that created this application
dateCreated The timestamp showing when you created your application.
dateUpdated The timestamp showing when you updated your application.
url The absolute URL of the application.

Create Application Endpoint Error Codes

This section lists the error codes that can be returned if you create, update, or delete an application.

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 The application name is not unique. The application name is already in use. Create Application, Update Application
462 409 Application status not open Application cannot be modified or deleted as its status is not open Update Application, Delete Application

Get an Application

You can retrieve a complete list of applications you created. You are able to retrieve all of them, or an individual application if you have the application ID.

Send a GET request to https://cpaas.mittoapi.com/numbermasking/applications/search to return all applications.

Send a GET request to https://cpaas.mittoapi.com/numbermasking/applications/search/{ApplicationSid} to retrieve a specific application.

Request Parameters for Retrieving Applications

This section details available query parameters for retrieving applications.

Parameter Name Data Type Required Description
name string no Only show applications that match the name text, partially or fully. This can be used with the sortby query parameter – sortby=:.
startTime string no Only show applications created on this date/time or later. Use ISO-8601 format for the 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. When only a date is provided the time is assumed to be midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. This can be used with the sortby query parameter – sortby=:.
endTime string no Only show applications that were created on this date/time or earlier.Use ISO-8601 format for the 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. When only a date is provided the time is assumed to be midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. This can be used with the sortby query parameter – sortby=:.
page integer no Which page of application records to return, starting from 0. Default if not used is to return page 0.
pageSize integer no Number of records to return per page. Default if not used is to return 10 entries per page.

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:

  • name
  • dateCreated
  • status

Response Parameters for Retrieving an Application

Response Description
code The status code explaining the status of the request.
message A message describing the error code if an error occurred or a success code if the request was successful.
data
Response Description
sid The unique application ID. You can use this to delete or update your application
enterpriseSid Sid of your enterprise. It will match what you sent in your request.
name Unique name of application. The name should be unique within an Enterprise.
result
Response Description
ttl The default time to live for a context created in an application. TTL is measured in seconds after the context’s last create date or interaction. If you do not pass one, the default value is 0 which is unlimited.
accountEmail The email associated with the account that created this application
dateCreated The timestamp showing when you created your application.
dateUpdated The timestamp showing when you updated your application.
url The absolute URL of the 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 The starting offset of page
end The ending offset of page
firstPageUri The unique URI that you can call to get records in the First page.
nextPageUri The unique URI that you can call to get the records in the next page.
uri The unique URI that you can call to get records.

Get an Application Endpoint Error Codes

This section lists the error codes that can occur if something goes wrong when requesting applications.

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

Get Phone Numbers Endpoint

You can search for available phone numbers to add to masking pools for your applications. You can also search through contexts. A context is an instance of two people talking with one another.

You search for phone numbers with a GET request to:
https://cpaas.mittoapi.com/numbermasking/phonenumbers/search

You can retrieve details about a specific number with a GET request to:
https://cpaas.mittoapi.com/numbermasking/phonenumbers/search/{phoneNumberSid}

Request Parameters for Retrieving Phone Numbers

Parameter Name Data Type Required Description
page integer no Which page of records to return. If not used, the default page returned is 0.
pageSize integer no Number of records returned per page. If not used, the default number of records per page is 10.
enterpriseSid string no This parameter is mandatory for CSP_ADMIN users. For ENTERPRISE_ADMIN users, even if this parameter is passed, its ignored.
friendlyName string no Only show phone numbers that match the friendlyName text, partially or fully. You can use the SortBy query parameter with this. The format is SortBy=friendlyName:. Direction may be ‘asc’ for ascending or ‘desc’ for descending.
phoneNumber string no Only show the phone number that starts with the phoneNumber digits. This is useful if you want to search for numbers with a specific Country Code. You can use the SortBy query parameter with this. The format is SortBy=phoneNumber:. Direction may be ‘asc’ for ascending or ‘desc’ for descending.

Response Parameters for Retrieving Phone Numbers

This section lists the parameters returned in a response when you retrieve details about available phone numbers.

Response Description
code The error code or status code for the response
message The description of the error or status code.
data
Response Description
result
Response Description
sid Unique SID identifying this phone number
phoneNumber Actual phone number
friendlyName Friendly name of this phone number
capabilities Capability of the phone number
pageSize Number of records returned per page.
total The total number of records.
page Which page of records to return.
numPages The total number of pages.
start The starting offset of page.
end The ending offset of page.
firstPageUri Unique URI that you can call to get the records in the First page.
nextPageUri Unique URI that you can call to get the records in the next page.
uri A unique URI that you can call to get records.

Get Phone Numbers Endpoint Error Codes

This section details the error codes you might receive when doing a GET request for phone numbers.

Error Code HTTP Status Error Message Description Category
471 409 Phone Number not found Sid of the Phone Number is not found. Add Phone Number, Search Phone Number

Mask Numbers Endpoint

You can use the Mask Numbers endpoint to associate a phone number with an application.

To associate a phone number with an application, send a POST request to: https://cpaas.mittoapi.com/numbermasking/maskednumbers

Request Parameters for Mask Numbers Endpoint

This section lists the request parameters for masking numbers.

Parameter Name Data Type Required Description
applicationSid string yes The unique ID for the application that you want to add the phone number to.
phoneNumberSid string yes The unique ID for the incoming phone number. This is the number you want to mask. You must provide this or the incoming phone number. If you provide both, the phoneNumberSid takes precedence.
phoneNumber string no Actual phone number to be added to the masking pool. This is mandatory if the phoneNumberSid is not passed.
isReserved string no If true the new phone number should be reserved and not be assigned to a participant using proxy pool logic. By default, it means the application will use this number first in the number selection logic.

Response Parameters for Mask Numbers Endpoint

This section details the response parameters for the mask numbers endpoint.

Response Description
code The error or status code for the response.
message A message describing the error if one occurred, or the status message.
data
Response Description
sid The unique mask number identifier. You can use this later to delete or update the phone number in the mask number pool.
phoneNumberSid The unique ID of the incoming phone number used for masking.
applicationSid The unique application ID to which a phone number is added.
friendlyName A human readable descriptive text for this resource, up to 64 characters long.
phoneNumber The incoming phone number to be masked.
isReserved Whether the new phone number should be reserved and not be assigned to a participant using the applications number mask pool logic.
inUse The number of open contexts assigned to the number.
accountEmail The unique account email associated with this phone number.
dateCreated Timestamp when this context was created.
dateUpdated Timestamp when this context was updated.
url The absolute URL of the context.

Mask Numbers Endpoint Error Codes

This section details the error codes you can get if there’s an issue with your request.

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 is already in use. The phone number is already assigned to an application. Add Phone Number.
471 409 Phone number not found The unique ID of the phone number you wanted to add to the mask pool of an application is not found. Add Phone Number.

Retrieve Masked Numbers Endpoint

You can search for masked numbers by application they are associated with. You must have the application ID to do so. Send a GET request to: https://cpaas.mittoapi.com/numbermasking/maskednumbers/search

You can retrieve an individual number by sending a GET request to: https://cpaas.mittoapi.com/numbermasking/maskednumbers/search/{MaskNumberSid}

Request Parameters for Retrieve Masked Numbers Endpoint

This section provides the request parameters for retrieving masked numbers.

Parameter Data Type Required Description
page integer no Which page of numbers to return, starting with 0.
pageSize integer no The number of records returned per page.
enterpriseSid string no This parameter is used by users with the role CSP_ADMIN to get all the numbers in the masked pool belonging to that particular business customer.
applicationSid string yes Show masked numbers that belong to the application.
isReserved boolean no If true, only masked numbers marked reserved appear in the response. If false, only masked numbers that are not reserved appear in the response.
inUse boolean no If true, show masked numbers that have contexts currently in use. If false, show masked numbers that have no open contexts.
phoneNumber string no Only show masked numbers that start with the digits you provide. This is useful for searching masked numbers that belong to a specific country code. You can use the sortby GET query parameter to further sort the results. The format is SortBy=phoneNumber:. Direction may be ‘asc’ for ascending or ‘desc’ for descending.
startTime string no Only show masked numbers that were added to the application on this date/time or later. Use ISO-8601 format: YYYY-MM-DDTHH:MM:SS. For example: 2018-10-05T22:45:32 or, if you want to omit the time, YYYY-MM-DD. 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 the UTC timezone.
endTime string no Only show masked numbers that were added to the application on this date/time or earlier. Use ISO-8601 format: YYYY-MM-DDTHH:MM:SS. For example: 2018-10-05T22:45:32 or, if you want to omit the time, YYYY-MM-DD. 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 the UTC timezone.

Response Parameters for Retrieve Masked Numbers Endpoint

This section provides the response parameters for retrieving masked numbers.

Response Description
code The error or status code for the response.
message The message describing the error or status code.
data
Response Description
result
Response Description
sid The unique mask number identifier. You can use this later to delete or update the phone number in the mask number pool.
phoneNumberSid The unique ID of the incoming phone number used for masking.
applicationSid The unique application ID to which a phone number is added.
friendlyName A human readable descriptive text for this resource, up to 64 characters long.
phoneNumber The incoming phone number to be masked.
isReserved Whether the new phone number should be reserved and not be assigned to a participant using the applications number mask pool logic.
inUse The number of open contexts assigned to the number.
accountEmail The unique account email associated with this phone number.
dateCreated Timestamp when this context was created.
dateUpdated Timestamp when this context was updated.
url The absolute URL of the context.
pageSize The number of records returned per page.
total The 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 The unique URI that you can call to get the records from the First page.
nextPageUri The unique URI that you can call to get the records from the next page.
uri The unique URI that you can call to get records.

Retrieve Masked Numbers Endpoint Error Codes

This section details the error codes you can get if there’s an issue with your request.

Error Code HTTP Status Error Message Description Category
471 409 Phone number not found. Sid of Phone Number passed to add in Mask Pool of an application is not found. Add Phone Number, Search Phone Number

Update or Delete a Masked Number Endpoint

After you add a masked number to an application pool, you may want to update its status. You can mark masked numbers as reserved or not reserved. To update a masked number, send a PUT request to: https://cpaas.mittoapi.com/numbermasking/maskednumbers/{maskNumberSid}

You can also delete a masked number from an application pool. To delete a masked number, send a DELETE request to the same endpoint.

Request Parameters for Update or Delete a Masked Number Endpoint

Parameter Data Type Required Description
maskNumberSid string yes This is the unique ID that was generated by adding a phone number to an application.
isReserved boolean no If true, only show masked numbers marked reserved. If false, only show masked numbers that are not reserved.

Response Parameters for Update or Delete a Masked Number Endpoint

This section shows you the response parameters returned when you update or delete a masked number from an application’s masked number pool.

Response Description
code The error or status code for the response.
message A message describing the error if one occurred, or a success message.
data
Response Description
sid The unique mask number identifier. You can use this later to delete or update the phone number in the mask number pool.
phoneNumberSid The unique ID of the incoming phone number used for masking.
applicationSid The unique application ID to which a phone number is added.
friendlyName A human readable descriptive text for this resource, up to 64 characters long.
phoneNumber The incoming phone number to be masked.
isReserved Whether the new phone number should be reserved and not be assigned to a participant using the applications number mask pool logic.
inUse The number of open contexts assigned to the number.
accountEmail The unique account email associated with this phone number.
dateCreated Timestamp when this context was created.
dateUpdated Timestamp when this context was updated.
url The absolute URL of the context.

Update or Delete a Masked Number Endpoint Error Codes

This section displays the error codes you may receive if there is an issue with your request.

Error Code HTTP Status Error Message Description Category
471 409 Phone number not found. Sid of the phone number passed to add to a masked number pool was not found. Add Phone Number, Search Phone Number, Remove Phone Number
473 409 Mask number in use The masked number is already assigned to a participant. Remove Mask Number from Application

Create a Context Endpoint

A context is a single instance of two individuals communicating. It belongs to an application, and has two participants. An example of a context would be a taxi driver and a customer communicating. The participants would be the taxi driver and the customer. The context stays active for a predefined period of time or it can be deactivated by API call.

You create a context by sending a POST request to: https://cpaas.mittoapi.com/numbermasking/contexts

Request Parameters for Create a Context Endpoint

This section details the request parameters you can include in a request.

Parameter Data Type Required Description
applicationSid string yes The unique ID for the application you are creating a context for.
name string yes The unique name of the context within the application.
dateExpiry string no The ISO 8601 formatted date/time indicating when the context should expire. If you include this value here, it overrides what you set for ttl (time-to-live) or the default ttl.
ttl string no You can set the default time to live for the context. The ttl is measured in seconds after the context is created, or from the last interaction.
mode string no The mode of the session. It can be: message, voice, voiceandmessage. If you do not submit something, the default is voice-only.

Response Parameters for Create a Context Endpoint

This section displays the response parameters returned when you create a new context.

Response Description
code The error code or status code for the response.
message A description of the error code or status code.
data
Response Description
sid Unique context ID. This can be used to delete or update a context or add participants.
applicationSid An application ID that the context belongs to.
name The unique name of the context. The name should be unique within an application.
dateExpiry The ISO 8601 formatted date for when the context should expire.
ttl The default time to live for the context created in the application. The time to live is measured in seconds after the context’s creation, or last interaction.
mode The mode of the session. Can be: message, voice, or voiceandmessage.
status The status of the context. The status can be:

  • Open: If a context is open it means it hasn’t passed the expiry date or ttl.
  • In-Progress: There are active communications going on in this context. This is more meaningful for voice, where a context can remain in-progress until the call is completed by the participants.
  • Closed: The context either passed expiryDate or ttl. No more communication is possible in this state. The context can be in any of these states at any time.
dateLastInteraction The ISO 8601 formatted date when the context last had an interaction.
closedReason The reason the context was closed. Possible values are: expired, deleted.
accountEmail The unique email associated with your account.
dateCreated The timestamp when this context was created.
dateUpdated The timestamp when this context was updated.
url The absolute URL for the context.

Create a Context Endpoint Error and Status Codes

This section displays the error code that can occur if something goes wrong.

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

Retrieve Contexts Endpoint

After you create contexts, you may want to retrieve them to review them, either in a group or individually. You can retrieve contexts by sending a GET request to: https://cpaas.mittoapi.com/numbermasking/contexts/search

You can retrieve a specific context by sending a GET request to: https://cpaas.mittoapi.com/numbermasking/contexts/search/{ContextSid}

Request Parameters for the Retrieve Contexts Endpoint

This section details the parameters you can include in your request.

Parameter Data Type Required Description
page integer no Which page of context records to return, starting from 0.
pageSize integer no Number of records returned per page.
applicationSid string no Only show contexts that belong to a specific application.
enterpriseSid string no This parameter is used by users with the role CSP_ADMIN to get all the numbers in the masked pool belonging to that particular Business Customer.
name string no Only show contexts that match the name text, partially or fully. You can use the SortBy GET query parameter to sort. You can do ‘asc’ for ascending or ‘desc’ for descending. The format is SortBy=name:. If you don’t provide a direction parameter then the listing of calls is sorted in ascending order.
status string no Only show contexts that match the specified status. You can use the SortBy GET query parameter to sort. You can do ‘asc’ for ascending or ‘desc’ for descending. The format is SortBy=name:. If you don’t provide a direction parameter then the listing of calls is sorted in ascending order.

  • Open: If a context is open it means it hasn’t passed the expiry date or ttl.
  • In-Progress: There are active communications going on in this context. This is more meaningful for voice, where a context can remain in-progress until the call is completed by the participants.
  • Closed: The context either passed expiryDate or ttl. No more communication is possible in this state. The context can be in any of these states at any time.
startTime string no Only show contexts that were created on this date/time or later. The format is ISO-8601, such as YYYY-MM-DDTHH:MM:SS. For example: 2018-10-05T22:45:32. If you want to omit the time, you can use the format YYYY-MM-DD. When only a date is provided the time is assumed to be at midnight for the given date. Note that the given date/time is inclusive and i assumed to be in the UTC timezone.
endTime string no Only show contexts created on this date/time or earlier. The format is ISO-8601, such as YYYY-MM-DDTHH:MM:SS. For example: 2018-10-05T22:45:32. If you want to omit the time, you can use the format YYYY-MM-DD. When only a date is provided the time is assumed to be at midnight for the given date. Note that the given date/time is inclusive and i assumed to be in the UTC timezone.

Response Parameters for the Retrieve Contexts Endpoint

This section displays the parameters returned in a response to a request to retrieve contexts.

Response Description
code The error or status code for the request.
message The message describing the error if one occurred, or a success message.
data
Response Description
result
Response Description
sid Unique context ID. This can be used to delete or update a context or add participants.
applicationSid An application ID that the context belongs to.
name The unique name of the context. The name should be unique within an application.
dateExpiry The ISO 8601 formatted date for when the context should expire.
ttl The default time to live for the context created in the application. The time to live is measured in seconds after the context’s creation, or last interaction.
mode The mode of the session. Can be: message-only, voice-only, or voice-and-message and the default value is voice-only.
status The status of the context. The status can be:

  • Open: If a context is open it means it hasn’t passed the expiry date or ttl.
  • In-Progress: There are active communications going on in this context. This is more meaningful for voice, where a context can remain in-progress until the call is completed by the participants.
  • Closed: The context either passed expiryDate or ttl. No more communication is possible in this state. The context can be in any of these states at any time.
dateLastInteraction The ISO 8601 formatted date when the context last had an interaction.
closedReason The reason the context was closed. Possible values are: expired, deleted.
accountEmail The unique email associated with your account.
dateCreated The timestamp when this context was created.
dateUpdated The timestamp when this context was updated.
url The absolute URL for the context.
pageSize Number of records returned per page.
total The total number of records.
page Which page of records to return.
numPages The total number of pages.
start The starting offset of the page.
end The ending offset of the page.
firstPageUri The unique URI that you can call to get records from the First page.
nextPageUri The unique URI that you can call to get records from the next page.
uri The unique URI that you can call to get records.

Retrieve Contexts Endpoint Error Codes

Error Code HTTP Status Error Message Description Category
465 409 Context not found Context is not found Search Context, Update Context, Delete Context

Update or Delete a Context Endpoint

After you create a context, you may wish to update it or delete it. You can update a context by sending a PUT request to: https://cpaas.mittoapi.com/numbermasking/contexts/{ContextSid}

You can delete a context by sending a DELETE request to the same endpoint.

Request Parameters for the Update or Delete a Context Endpoint

This section details the parameters you can include in your request. If you are deleting a context, the only parameter you can use is ContextSid.

Parameter Data Type Required Description
contextSid string yes The context ID generated by creating a context.
status string no You can use this to change the status of the context. You can change:

  • Closed to Open
  • Open to Closed
  • In-Progress to Closed

In_progress cannot be set by you. It is set by application business logic when a call is in progress.
dateExpiry string no If the state of the context is closed and the expiry date is in the future, the state will be changed to open and the expiry date will be updated.

Response Parameters for the Update or Delete a Context Endpoint

This section shows you the response parameters that come back after you send a request.

Response Description
code The error or status code.
message The message describing the error or status code.
data
Response Description
sid Unique context ID. This can be used to delete or update a context or add participants.
applicationSid An application ID that the context belongs to.
name The unique name of the context. The name should be unique within an application.
dateExpiry The ISO 8601 formatted date for when the context should expire.
ttl The default time to live for the context created in the application. The time to live is measured in seconds after the context’s creation, or last interaction.
mode The mode of the session. Can be: message-only, voice-only, or voice-and-message and the default value is voice-only.
status The status of the context. The status can be:

  • Open: If a context is open it means it hasn’t passed the expiry date or ttl.
  • In-Progress: There are active communications going on in this context. This is more meaningful for voice, where a context can remain in-progress until the call is completed by the participants.
  • Closed: The context either passed expiryDate or ttl. No more communication is possible in this state. The context can be in any of these states at any time.
dateLastInteraction The ISO 8601 formatted date when the context last had an interaction.
closedReason The reason the context was closed. Possible values are: expired, deleted.
accountEmail The unique email associated with your account.
dateCreated The timestamp when this context was created.
dateUpdated The timestamp when this context was updated.
url The absolute URL for the context.

Error and Status Codes for the Update or Delete a Context Endpoint

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
467 409 Context status closed Context cannot be modified or deleted as its status is closed. Update Context, Delete Context

Participants Endpoint

After you create a context, you need to add participants. You can add a participant by sending a POST request to: https://cpaas.mittoapi.com/numbermasking/participants

If you want to delete a participant, you can by sending a DELETE request to: https://cpaas.mittoapi.com/numbermasking/participants/{ParticipantSid}

Request Parameters for the Add Participants Endpoint

This section displays the parameters you can include in your request.

Parameter Data Type Required Description
contextSid string yes The ID of the context that this participant should be added to.
participantPhoneNumber string yes The phone number of the participant.
friendlyName string no A friendly name you can assign to describe the participant. This value must be 255 characters or fewer.
maskPhoneNumberSid string no The ID of the masked phone number to use for the participant from the masked number pool for the application to which the context belongs. If not specified, the application will select a number from the pool.
maskPhoneNumber string no The actual masked phone number that is present in the masked phone numbers pool will be assigned to this participant. If both the maskPhoneNumberSid and the maskPhoneNumber are are passed, the maskPhoneNumberSid takes precedence.

Response Parameters for the Add Participants Endpoint

This section displays the parameters that can be returned.

Response Description
code The error or status code for the response.
message The message describing the error or status code.
data
Response Description
sid The unique participant ID. This can be used later to remove or update the participants.
applicationSid The application ID to which the context belongs. You add the participant to the context.
contextSid The context ID to which the participant is added.
participantPhoneNumber The phone number of the participant.
friendlyName The friendly name assigned to the participant.
maskPhoneNumber The masked phone number.
maskPhoneNumberSid The ID of the masked phone number.
accountEmail The email associated with the context creation.
dateCreated The timestamp when this participant was added to the context.
dateUpdated The timestamp when this participant was updated.
dateRemoved The timestamp when the participant was removed from the context.
uri The absolute URL of the participant.

Error and Status Codes for the Add Participants Endpoint

This table displays the error codes that can come back if something goes wrong.

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
467 409 Context is closed The context cannot be modified or deleted as its status is closed. Add Participant to Context
471 409 Phone number not found The ID of the phone number that you add in the masked pool of an application is not found. Or the masked phone number was added to the context but it is not present. Add Phone Number, Search Phone Number, Remove Phone Number, Add Participant to Context
480 409 Participant has already been added to context The participant was already added to the context. Add Participant to Context
481 409 Context already has 2 participants If Add Participant is called when the context already has two participants you will receive this error. Add Participant to Context
482 400 Participant not found ID of the participant passed is not found Search Single Participant
483 400 Participant already removed Trying to remove participant from a context that was already removed. Remove Participant

Request Parameters for Delete Participant

 

Parameter Data Type Required Description
ParticipantSid string yes The participant SID that was generated by calling the Add Participant API.

Response Parameters for Delete Participant

 

Parameter Description
code Sub-error code for the response.
message The message describing the error if an error occurred, otherwise a success message.
data
Response Description
sid The unique participant ID. This can be used later to remove or update the participants.
applicationSid The application ID to which the context belongs. You add the participant to the context.
contextSid The context ID to which the participant is added.
participantPhoneNumber The phone number of the participant.
friendlyName The friendly name assigned to the participant.
maskPhoneNumber The masked phone number.
maskPhoneNumberSid The ID of the masked phone number.
accountEmail The email associated with the context creation.
dateCreated The timestamp when this participant was added to the context.
dateUpdated The timestamp when this participant was updated.
dateRemoved The timestamp when the participant was removed from the context.
uri The absolute URL of the participant.

Error Codes for Delete a Participant

Error Code HTTP Status Error Message Description Category
482 400 Participant not found Sid of Participant passed is not found Search single participant
483 400 Participant already removed Trying to remove participant from context which was already removed. Remove Participant

Retrieve Participants Endpoint

You may want to check what participants are associated with a context. Each context can have a maximum of two participants. You can check by sending a GET request to: https://cpaas.mittoapi.com/numbermasking/participants/search

If you want to retrieve details for a single participant, you can do so with their ID by sending a GET request to: https://cpaas.mittoapi.com/numbermasking/participants/search/{ParticipantSid}

Request Parameters for Retrieve Participants Endpoint

This section displays the parameters you can send in a request to retrieve participants.

Parameter Data Type Required Description
page integer no Which page of participants records to return, starting from 0.
pageSize integer no Number of records returned per page.
applicationSid string no Only show participants under all contexts that belong to a given application.
contextSid string no Only show participants under the given context.
participantPhoneNumber string no Only show participants who have a phone number starting with the digits you choose. This helps you find participants in a specific country. You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction. Direction can be either ‘asc’ for ascending or ‘desc’ for descending sort ordering. The format is SortBy=participantPhoneNumber:.
friendlyName string no Only show participants that match name text, partially or fully. You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction. Direction can be either ‘asc’ for ascending or ‘desc’ for descending sort ordering. The format is SortBy=friendlyName:.
maskPhoneNumber string no Only show participants who have a masked phone number starting with the digits you choose. You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction. Direction can be either ‘asc’ for ascending or ‘desc’ for descending sort ordering. The format is SortBy=maskPhoneNumber:.
startTime string no Only show participants 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. You can also omit the time and use the format 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 string no Only show participants 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-05T22:45:32. You can also omit the time and use the format 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.

Response Parameters for Retrieve Participants Endpoint

This section displays the response you get back.

Response Description
code The error or status code for the response.
message The message describing the error if one occurred or the success message.
data
Response Description
result
Response Description
sid The unique participant ID. This can be used later to remove or update the participants.
applicationSid The application ID to which the context belongs. You add the participant to the context.
contextSid The context ID to which the participant is added.
participantPhoneNumber The phone number of the participant.
friendlyName The friendly name assigned to the participant.
maskPhoneNumber The masked phone number.
maskPhoneNumberSid The ID of the masked phone number.
accountEmail The email associated with the context creation.
dateCreated The timestamp when this participant was added to the context.
dateUpdated The timestamp when this participant was updated.
dateRemoved The timestamp when the participant was removed from the context.
uri The absolute URL of the participant.
pageSize Number of records returned per page.
total The total number of records.
page Which page of records to return.
numPage Total number of pages.
start Starting offset of page.
end Ending offset of page.
firstPageUri The unique URI that you can call to get records in the first page.
nextPageUri The unique URI that you can call to get records in the next page.
uri The unique URI that you can call to get records.

Error Codes for the Retrieve Participants Endpoint

This section contains error codes you may receive if something goes wrong.

Error Code HTTP Status Error Message Description Category
482 400 Participant not found ID of the participant passed is not found. Search Single Participant

Interactions Endpoint

Interactions are read-only call detail records (CDRs) for a given context. Each interaction represents a single communication caller and called participant. You can retrieve a list of interactions by sending a GET request to: https://cpaas.mittoapi.com/numbermasking/interactions/search

You can retrieve a single interaction by sending a GET request to: https://cpaas.mittoapi.com/numbermasking/interactions/search/{InteractionSid}

Request Parameters for the Interactions Endpoint

This section displays the parameters you can include in a request for information about an interaction.

Parameter Data Type Required Description
page integer no Which page of interactions records to return, starting from 0.
pageSize integer no The number of records returned per page
applicationSid string no Only show interactions under all contexts that belong to a given application.
contextSid string no Only show interactions under a given context.
inboundParticipantPhoneNumber string no Only show interactions that have a calling party phone number starting with the digits you choose.
inboundMaskPhoneNumber string no Mask phone number called by inboundParticipantPhoneNumber.
outboundParticipantPhoneNumber string no Only show interactions who have a called party phone number starting with the digits you choose.
outboundMaskPhoneNumber string no Mask phone number calling outboundParticipantPhoneNumber.</td
startTime string no Only show interactions that were added on this date/time or later, given as an ISO-8601 date/time string. For example: YYYY-MM-DDTHH:MM:SS (2018-10-05T22:45:32). If you want to omit the time, YYYY-MM-DD (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 string no Only show interactions that were added on this date/time or earlier, given as an ISO-8601 date/time string. For example: YYYY-MM-DDTHH:MM:SS (2018-10-05T22:45:32). If you want to omit the time, YYYY-MM-DD (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.

Response Parameters for the Interactions Endpoint

This section shows the parameters returned in the response to your request for interaction details.

Response Description
code The error or status code for the response.
message The message describing the error or status code.
data
Response Description
result
Response Description
sid Unique ID of the interaction
applicationSid The unique Application ID.
contextSid The unique Context ID.
inboundParticipantSid The unique ID for the inbound participant.
inboundTargetSid The unique ID of the inbound participant.
inboundParticipantPhoneNumber The phone number of the caller party.
outboundParticipantSid Sid of outbound participant.
outboundParticipantPhoneNumber Only show interactions that have a called party phone number starting with outboundParticipantPhoneNumber digits.
inboundMaskPhoneNumber The masked phone number used for the inbound participant’s phone number.
inboundChannelStatus The status of the channel for the inbound caller.
outboundParticipantSid The ID of the outbound participant.
outboundMaskPhoneNumber The masked phone number for the outboundParticipantPhoneNumber.
outboundChannelStatus The status of the channel for the outbound caller.
type The type of interaction it is. It can be message or voice.
duration A JSON string that includes call duration (when available) for a call.
accountEmail The unique email associated with your account.
dateCreated The timestamp for when the interaction was created.
dateUpdated The timestamp for when the interaction was updated.
url The absolute URL of the interaction.
pageSize The number of records returned per page.
total The total number of records.
page Which page of records to return.
numPages The total number of pages.
start The starting offset of the page.
end The ending offset of the page.
firstPageUri The unique URI that you can call to get records in the first page.
nextPageUri The unique URI that you can call to get records in the next page.
uri The unique URI that you can call to get records.

Error Codes for the Interactions Endpoint

This section displays error codes you may see if something goes wrong with an interaction request.

Error Code HTTP Status Error Message Description Category
490 400 Interaction not found. ID of the interaction passed is not found. Search a single interaction.