FMU overview

What is FMU?

Nowadays, almost all your employees have both a business fixed-line phone and a mobile phone. But that's not always easy to balance in practice. Which number should they give to external business contacts? On which number, on which phone and on which voicemail do they wish to be contactable for business calls? Moreover, as a company, you want to keep an eye on your costs and certain company rules on fixed line or mobile phone usage.

More information about Proximus Fixed Mobile Unification is available on our corporate website.

What can FMU customers do with the FMU API?

The FMU settings of your employees are managed via MyProximus by your Fleet manager. Your employees may as well use a mobile app to update their status and switch between Private or Professional profiles.

The FMU API makes it possible to automate this process from within your business processes, offering both convenience and avoiding human mistakes. As an example, using the FMU API makes it possible to switch FMU profiles based on GPS coordinates, or based on employees badging in and out of the company.

How to subscribe to the FMU API?

Important prerequisite

You can start using the FMU API only if you have a valid and active FMU option on your Proximus account. For new customers looking to subscribe to FMU you can contact us here.

Request the activation of your subscription via the "pricing" tab above. We will reach back you to complete the registration process.

Getting started

To work with the FMU API, you will need:

• the activated FMU option on your Proximus account
• a validated API subscription of FMU API's
• the FMU option activated on MSISDN
• the MSISDN (Mobile Station Integrated Services Digital Network) (mobile phone number) for which you want to get or change the status
• the OAuth2 access token from your API Solutions account

Get status detail for one number

Retrieving information about a specific mobile phone number (msisdn) is performed with the following API call on a synchronous way:

Sample request

curl -L -X GET 'https://api.enco.io/fmu/1.0.0/status?msisdn=32477121212' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer {your API Solutions OAUTH2 token}'

The API will return the latest status of the specific mobile phone number.

Sample answer

{ 
  "msisdn": "32477121212",
  "isError": false,
  "status": "PRIVATE"
}

Set status for one number

To set the status [PRIVATE,PROFESSIONAL,ON_DUTY] for a specific mobile phone number, use the following API call:

Sample request

curl -X PUT 'https://api.enco.io/fmu/1.0.0/status' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer {your API Solutions OAuth2 Access token}' \
 -d '{"msisdn": ["32471121212"], "status": "PRIVATE"}'

The API will put the status "PRIVATE" on your mobile so that the phone call to the business phone will not be forwarded to the private mobile number.

Sample answer

{
  "msisdn": "32477121212",
  "success": true
}

Get or change the status for multiple numbers

The /status API makes it also possible to request status changes for multiple mobile phone numbers (max 50) in one time. As the process becomes asynchronous, you will need to provide a callback URL to be able to trace back how the status changes are being applied to your numbers.

Defining a callback URL is done as follow and will be used for all asynchronous calls:

curl -X POST 'https://api.enco.io/fmu/1.0.0/register_callback' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer {your API Solutions OAuth2 token}' \
 -d '{"url": "http://feedback.com"}'

Note that this request doesn't return any specific payload.

It's also possible to provide a callback URL for a certain request only. This can be achieved by putting it in the payload of your request. See API definition for more information.

As an example, the following request will query the current profile status for 2 MSISDN and return the information to the given callback URL.

curl -X GET 'https://api.enco.io/fmu/1.0.0/status?msisdn=32471121212,32471121213&callback_url=https://callbackoptional.url' \
 -H "accept: application/json" \
 -H 'Authorization: Bearer {your API Solutions OAuth2 access token}'

API authentication

API Solutions uses OAuth2 to protect API resources. The OAuth2 specification has become the predominant standard for securing RESTful APIs and identity delegation.

In order to gain access to the resources exposed by your API assets, you will need to pass along a valid OAuth2 bearer access token. Here is how you can generate such a token.

Obtaining your OAuth2 Application Keys

Each project you create through the API Solutions Market will result in the creation of a unique pair of OAuth2 application keys. To retrieve your keys, proceed as follows:

• First, log in and visit your dashboard on the portal. Click the "TOKEN" menu.
• This will result in your application keys to be shown. These keys can be used to access API resources exposed by any API asset to which you subscribed, within the scope of the selected project.

Your application keys are sensitive information; keep them private at all time!

Make sure to store your application keys in a safe way, avoiding them to leak or be stolen by an unintended audience. They are quite sensitive, in that anyone obtaining them will be able to gain access to your assets. In case your application keys would become compromised, contact us through support and we'll revoke them to block access, and provide you with a new pair. This is also the reason why all API traffic should pass through secured HTTP, and why we do not support plain HTTP.

Generating a fresh bearer access token

A bearer access token is a self-contained unique identifier through which you can gain access to API resources. Before elaborating on how you can obtain such type of token, please note that these tokens are valid for a limited time span of 1 hour (or less, if explicitly revoked).

You can obtain a new token by issuing the following request against the server https://api.enco.io :

/token POST

Issue a request to https://api.enco.io/token, adding the following headers and body:

Request

curl -X POST \
  'https://api.enco.io/token?grant_type=client_credentials&scope=openid&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&Accept=application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' 

Response payload

{ 
  "scope": "openid", 
  "token_type": "Bearer", 
  "expires_in": {number}, 
  "access_token": {string}
}

The field accesstoken in the response contains your token. The field expiresin will show you the remaining validity of your token, in seconds.

Single active access token
Within the context of a single application, you will only have a single active access token at any time. If you would request a new token using the above request message while the previously issued token has not yet expired, you will get back the previous token. To obtain a new one, revoke the old token; then generate a new one.

Code Samples
To help you getting started on implementing this authentication in your code, you can find some samples on our Github.

Revoking an access token

This procedure should be used when your token has been compromised (leaked, stolen, etc.), or if you want to generate another token, but your old token is still valid.

/revoke POST

Issue a request to https://api.enco.io/revoke, adding the following headers and payload:

Request payload

token=<old-access-token-to-be-revoked>&client_id=<app-consumer-key>&client_secret=<app-consumer-secret>

Creating permanent token

You can create permanent tokens from the "TOKEN" menu of your profile's dashboard. Just click on "Add a new token" to create a new permanent token. Several permanent tokens can be created for the same account.

Your permanent token is sensitive information; keep it private at all time!

Make sure to store your permanent tokens in a safe way, avoiding them to leak or be stolen by an unintended audience. They are quite sensitive, in that anyone obtaining them will be able to gain access to your assets. In case a permanent token would become compromised or not needed anymore, delete this token from your "TOKEN" dashboard by clicking on the red cross next to it.

All set to call your API!

Once a valid access token has been generated, it should be added to request messages. The token should be passed in an HTTP header named Authorization, which should be assigned the value of Bearer, followed by a single space, and immediately followed by the access token. Note the single space between 'Bearer' and the token.

curl -i -X GET -H "Accept:application/json" -H "Authorization: Bearer <active-access-token>" https://api.enco.io/fmu/1.0.0/status?msisdn=32477121212