What is the Mitto Number Masking API?

Mitto’s Number Masking API lets you enable communication between two parties without revealing their phone numbers to one another. With this API you can:

• Assign numbers to number masking pools for individual applications.
• Reserve or release numbers in masking pools for your application.
• Delete numbers from a masking pool.
• Search for numbers to add to your number masking pools.
• Track and review interactions between application users.

Documentation Organization

We organize our documentation as follows:

Get Started with Mitto Number Masking

This section provides general information about the Mitto Numer Masking API such as endpoints, methods, and response format.

Sign up for a Mitto Account

To get started with Mitto, do the following:
1. Sign up for a Mitto account at https://www.mitto.ch/contact/ or write to info@mitto.ch.
2. Submit the IPs you want to use for requests. They must be whitelisted on Mitto’s system.
3. Mitto will respond with your API key and confirmation that your IP addresses and callback URL are configured.

Request Requirements

The Number Masking API has multiple 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}

Response Format and Content

The response and content varies slightly by endpoint. The general format is to return a status code, message, any pagination information, and then a data dictionary. Here’s an example without pagination:


{
"data": {
"sid":"NMPb6eb071d21124dbab20b095c25f1111d",
"applicationSid":"NMAb6eb071d21124dbab20b095c25f1274f",
“contextSid”:”NMCb6eb071d21124dbab20b095c25f8932x”,
“participantPhoneNumber”:”15555556943”,
“friendlyName”:”My Mobile”,
“maskPhoneNumber”:”12013507693”,
“maskPhoneNumberSid”:”NMMb6eb071d21124dbab20b095c25f8944a”,
“accountEmail”:"email@company.com,
"dateCreated":"2019-07-22 09:53:51",
"dateUpdated":"2019-07-22 09:53:51",
"url":/numbermasking/participants/search/NMPb6eb071d21124dbab20b095c25f1111d"
},
"code": 200,
"message": "OK"
}


For more details, refer to the Number Masking Use Cases section.

Authentication

Mitto’s Number Masking API uses basic authentication for each request. Basic authentication is a simple authentication method that’s built into the HTTP protocol. You send HTTP requests with an Authorization header formatted like so:
Authorization: Basic base64(accountID:API key)

In the example, you would replace base64(accountID:API key) with a base64-encoded string where the string consisted of “accountID:API key”.

For examples of requests using basic authentication, refer to Number Masking Use Cases.