Rented numbers


The rented numbers API is a solution that allows you to book temporary numbers and assign them to any real number. You can then expose or publish the temporary number online or offline while the real number remains hidden. The API can be used in the context of online transactions when a seller wants to keep his phone private while still being able to receive phone calls from potential buyers. Another example could be in the context of a field technician who would need to be reachable by a customer before or after an intervention while keeping his real number hidden.

Add feature

Add feature

Booking a temporary number

The API consists mainly of operations around the booking of temporary numbers. To create a temporary number and assign it to the hidden number, you can use the POST HTTP method on the /bookings endpoint. You will need to specify the destination (the hidden number), the usage plan (“SMALL”, “MEDIUM” or “LARGE”) and a callback. If the callback is valid, you will get the following information in return: id, service, endTime, secondsRemaining, callsRemaining and destination.

  • id is the id of the booking that can be used to retrieve booking details
  • service is the temporary number that was assigned to the booking in question and linked to the destination number
  • endTime is the time at which the booking will no longer be active and calls can no longer be placed of that number
  • secondsRemaining is the number of seconds that are still available in the usage plan linked to the booking. You can get information on the usage plans and their limits on the price page of the “rented numbers” asset.
  • callsRemaining is the amount of calls that still be made on the temporary number. You can get information on the usage plans and their limits on the price page of the “rented numbers” asset.
  • destination is the hidden number to which all the calls are redirected.
  • usagePlan is the usage plan that is linked to the booking. You can get information on the usage plans and their limits on the price page of the “rented numbers” asset.
  "id": "string",
  "service": "string",
  "endTime": "string",
  "minutesRemaining": 0,
  "destination": "string",
  "usagePlan": "SMALL"


Callbacks are used to be notified of events happening on the temporary number. If a call on the temporary number is successful, then the callback provides details about the call in the following format:

  "id": "string",
  "timestamp": "string",
  "duration": 0,
  "source": "string",
  "destination": "string",
  "bookingId": "string"

If a call is made on an expired booking, then the callback provides information about the failed call:

  "timestamp": "string",
  "source": "string",
  "destination": "string",
  "bookingId": "string",
  "message": "Incoming call for expired booking"

Grace period

The grace period is a period which starts when the booking has expired, and calls are no longer possible. The grace period is currently 1 week for all usage plans. After the grace period the booking no longer exists and the number attached to it is quarantined and recycled.

Manage your bookings

List your bookings

You can get a list of all your bookings by using the HTTP GET method on the /bookings endpoint. You can only get the list of bookings that are not expired or include the expired ones that are in their grace period by using the includeExpired parameter. The bookings that are out of the grace period do not longer exists and numbers attached to them are no longer available. The information containing your bookings is paginated. You can use the pagination to go through your whole list of bookings.

Update a booking

If a booking has expired you may want to update a booking by using the HTTP PUT method. You can update the booking minutes, calls or expiry date by using the adequate usage plan (“SMALL”, “MEDIUM”, “LARGE”). You can use any usage plan when updating a booking regardless of which plan you were previously on. If you had any minutes or calls left on your current plan, the new minutes and calls are added to the remaining amounts. The expiry date is also updated taking into account the amount of days left to your usage plan.

Delete a booking

It is possible to delete a booking in case you want to immediately cease the service on a given temporary number. This can be useful if an end user is getting spammed on the temporary number. However, note that this action is irreversible, and the number linked to that booking will be gone.


The /cdr (call details record) endpoint allows you to get information on the calls received on your various temporary numbers. You can also get the details for a specific call with /cdr/{id}. Note that these calls are not linked to a booking id as some bookings may no longer exist. If you need to create call reports based on the booking id (or the service parameter), we suggest that you store the response of the callbacks which contains the service and booking id. This may be useful if you need to create a report specifically on a temporary number.

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