Voice Callout API

Voice Call-out API Overview

Our Voice Call-out API allows you to make a call between 2 phone numbers. The first number is one of your Proximus numbers which will be used as the origin of the call and the second number is the destination number.

The main benefits of the Voice Call-Out solution are in its simplicity and the fact that you can reuse your Proximus numbers and pre-existing tariff plans. If you have a fixed voice product with Proximus, all you have to do is subscribe to the service on Proximus EnCo at no extra costs. Any of the voice traffic generated through the API will be using your current voice infrastructure as if it were just a normal voice call.

This service is ideal if you're thinking about your digital transformation and how to automate some of your business processes. Because the solution is so simple you can easily implement proof of concepts around voice call automation.

Use cases

  • CRM integration: You can automate voice calling from you CRM system. For example, when a specific action is taken for a customer such as closing a case or when a phone appointment is scheduled, your CRM system can automatically generate a call between your customer and his account manager.

  • Call reminders / call me back: Off-load some of your inbound calling flows by letting your customers request a "call back". These callbacks can then be picked up from the callback queue by agents that are available.

  • Calendar and contact integration: Let your calendar application generate calls at the right time with the right person by integrating the voice calls with your contact list and your agenda. You can also make sure that your official company numbers are always displayed and reserve direct mobile numbers for more personal interactions.

Using the Voice Call-out API

Call flow

Let's assume the following: the voice call-out API is used for a call to be generated between an account manager with number A (a Proximus number) and his customer with number B (the destination number).

Example flow for VCA API Call


  • Call automation and integration to third-party applications such as CRM, ERP, ticketing.
  • Masked number
  • Reuse your existing Proximus numbers, voice infrastructure, tariff plans at no extra cost
  • Legal compliance such as lawful intercept
  • API Security: anti-spoofing, Oauth based authentication, Proximus account check

Request details

Call request

The API request is a HTTP POST with a JSON body that contains different parameters. Origin and destination are mandatory parameters. "CLI", "presentation" and "callback" is optional. The response if successful is always a sessionId. The sessionId is reserved for future use but can already help for potential support issues.

  • origin (aka "A number"): That is the number that will be called first. It must be a fixed Proximus number owned by the account making the call request. It should be in the E.164 format (although we autocorrect some known formats, we strongly recommend the use of E.164). Note that if a call forward is enabled on the A number, the service will still work.

  • destination (aka "B number"): That is the number that will be called if the first call to the A number is answered. It can be any number (fixed national, mobile, international…) with some restrictions towards special numbers like emergency services . Like the origin number, the number format should be E.164. Note that the current solution does not support any call barring that would be in place. Should you want to implement any call barring logic, this should be part of your application logic.

  • cli (aka "Caller Line Identity"): If provided, this is the number shown to the B party, the "call flow" stays the same. Just as the origin number, it must be a fixed Proximus number owned by the account making the call request.

  • presentation: That optional parameter determines if the A/CLI number should be displayed to the B party. The value of this parameter is defaulted to "ALLOWED" if not present or empty. The other authorized value for "presentation" is "RESTRICTED". If "RESTRICTED" is used, the first call will still show the A number to A, but will mask the A number to B.

  • callback: Optional parameter where you provide your HTTP(s) endpoint on where you want to receive the CDR info when the call has finished.

Request example:

curl -X POST \
-H 'Authorization: Bearer <YourToken>' \
-H 'Content-Type: application/json' \
-d '{
        "origin": "+3228160257", 
        "destination": "+32468373901", 
        "presentation": "ALLOWED"

Response body example:

{"sessionId": "123456"}

CDR (Call Detail Record) retrieval

This API request enables you to retrieve a list of CDR's or a single CDR and can be used for all your reporting/statistics needs.

Filtering can be done by specifying a "from" and/or a "till" datetime. A paged result will be returned (to avoid very large JSON), all this meta info is available in the response.

If no filter parameters are provided, all CDR's are returned.

  • from (optional): Date after which to return CDR's
  • till (optional): Date before which to return CDR's
  • page (optional): If multiple pages are available, provide this parameter to retrieve a certain page
  • limit (optional): If provided, the amount of items per page is limited (default 100)

Request example:

curl -X GET '' \
-H 'Authorization: Bearer <YourToken>'

Response body example:

  "items": [
      "sessionId": "61146645",
      "origin": "32xxxxxxxx",
      "destination": "32xxxxxxxx",
      "presentation": "allowed",
      "requestTime": "2021-10-19T14:13:57Z",
      "callOneRelease": "2021-10-19T14:13:57Z",
      "callOneSetup": "2021-10-19T14:13:57Z",
      "callDuration": 0,
      "callReleaseInfo": "Leg1-404-NotFound received",
      "webRTC": false
      "sessionId": "61168475",
      "origin": "32xxxxxxxx",
      "destination": "32xxxxxxxx",
      "presentation": "allowed",
      "requestTime": "2021-10-25T07:31:20Z",
      "callOneRelease": "2021-10-25T07:31:20Z",
      "callOneSetup": "2021-10-25T07:31:20Z",
      "callDuration": 0,
      "callReleaseInfo": "Leg1-404-NotFound received",
      "webRTC": false
  "meta": {
    "currentPage": 0,
    "totalElements": 2,
    "lastPage": 0

Never miss a thing

Stay informed on offers, promotions and platform updates by e-mail. You can unsubscribe at any time.

Proximus logo

All rights reserved. © 2020 Proximus | Cookie policy

This site was created and is managed in accordance with Belgian law.

Proximus API Solutions - powered by ClearMedia NV. Merksemsesteenweg 148, B-2100 Deurne.

BE 0831.425.897