Number Entitlements
To use the service, you do not only need licenses like SIP trunk channels or MS Teams users, you also need phone numbers. To get numbers, you can either select numbers from our number inventory or you can port in numbers from another service providers
In order to be able to select numbers from our number inventory, you need to have number entitlements. Number entitlements are licenses that determine how many numbers you can select of a given number type and country. Entitlements are linked to a subscription and are typically ordered together with licenses (e.g. 1 MS Teams seat = 1 MS Teams user license + 1 number entitlement)
This set of APIs allows the API consumer to do CRUD operations on the number entitlements of a subscription.
Geographical regions
Geographically numbers are typically bound to a geographical region within a country. Certain governments impose that you can only get numbers of a certain geographic area if and only if you have a physical presence (a site with an address) in that area. Therefore it is possbile to associate an entitlement to 1 or more geographical areas. A customer will only be allowed to select numbers in those areas for which he/she is entitled.
List all number entitlements of a subscription
Use this endpoint to retrieve all number entitlements currently assigned to a subscription. For each entitlement, the API provides in formation on the actual usage as well as a count of the numbers that were reserved or previsously assigned but now disconnected/quarantained.
Request
Endpoint
GET /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/entitlements
Authorization
Required role
tenants.instance.subscriptions.entitlements.list
Path Parameters
| Parameter | Type | Description |
|---|---|---|
draas_instance | string | See common parameters |
uuid | string | A system generated unique ID (UUID) identifying the tenant to which the subscription belongs |
sub_id | integer | Index of the subscription for which you want to list the licenses |
URL/Query parameters
N/A
Response
Status codes
| Parameter | Description |
|---|---|
200 | One or more entitlements found |
400 | Error while processing the request |
403 | The API consumer doesn't have sufficient rights to perform this action |
500 | Uncatched error on server side |
Success
Body
| Parameter | Type | Description | Conditional? |
|---|---|---|---|
entitlements | array | List containing all entitlement objects for the tenant | no |
Entitlement Object
| Parameter | Type | Description | Conditional? |
|---|---|---|---|
id | integer | Index of the entitlement | no |
name | string | Name of the entitlement | no |
countryCode | string | Country code for which this entitlement is valid | no |
isoCode | string | Two characters ISO 3166 country code | yes |
numberType | string | Type of numbers for which this entitlement is valid | no |
serviceCapabilities | string | Not relevant in this context | no |
entitlement | string | Amount of numbers that can be selected | no |
vanityType | string | Vanity numbers are numbers that look nice (e.g. end with 0000) | no |
addressRequired | Boolean | Indicates whether or not you need a physical address in a geographical region in order to be able to select a number under this entitlement | no |
regions | array | List of geographical regions for which this entitlement is valid. This list depends on the locations added for this account. | no |
assigned | string | Amount of numbers that are assigned under this entitlement. This value will never be higher than entitlement. The value is only returned when at least 1 number is assigned. | yes |
reserved | string | Amount of numbers that are reserved for this subscription and that match the conditions of this entitlement. This value can be higher than entitlement. The value is only returned when at least 1 number is reserved. | yes |
disconnected | string | Amount of numbers that are in quarantine for this subscription and that match the conditions of this entitlement. This value can be higher than entitlement. The value is only returned when at least 1 number is in quarantine. | yes |
Example
{
"entitlements": [
{
"id": 7,
"name": "Belgium - geographical numbers",
"countryCode": "+32",
"isoCode": "BE",
"numberType": "geo",
"serviceCapabilities": "*",
"entitlement": 10,
"vanityType": null,
"addressRequired": true,
"regions": [
"Borgloon",
"Brussels"
],
"assigned": 2,
"reserved": 20,
"disconnected": 3
},
{
"id": 8,
"name": "Belgium - tollfree numbers",
"countryCode": "+32",
"isoCode": "BE",
"numberType": "tollfree",
"serviceCapabilities": "*",
"entitlement": 10,
"vanityType": null,
"addressRequired": false,
"regions": []
}
]
}Create a new entitlement
Use this endpoint to associate a new entitlement to a subscription
Request
Endpoint
POST /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/entitlements
Authorization
Required role
tenants.instance.subscriptions.entitlements.create
Path Parameters
| Parameter | Type | Description |
|---|---|---|
draas_instance | string | See common parameters |
uuid | string | A system generated unique ID (UUID) identifying the tenant to which the subscription belongs |
sub_id | integer | Index of the subscription to which you want to add an entitlement |
URL/Query parameters
N/A
Body
| Parameter | Type | Description | Required |
|---|---|---|---|
licenseModelId | string | ID of the entitlement type that for which you want to add an entitlement to this subscription. All available entitlement types, please refer to our reference data section | yes |
entitlement | integer | The quantity of numbers of this type that the customer is allowed to use. If not provided, it will be set to 0. | no |
externalReference | string | Optional parameter that could be used to save the reference given to this product in an external - typically billing - platform | no |
Example
{
"licenseModelId": 27
}Response
Status codes
| Parameter | Description |
|---|---|
200 | The entitlement was created successfully |
400 | Error while creating the entitlement |
403 | The API consumer doesn't have sufficient rights to perform this action |
500 | Uncatched error on server side |
Success
Body
| Parameter | Type | Description | Conditional |
|---|---|---|---|
id | integer | Index of the created entitlement | no |
Example
{
"id": 542
}Modify an existing entitlement
Use this endpoint to modify an existing entitlement for a subscription. Main use case of the API is to update the allowed quantities, i.e. grant a customer more or less numbers of a given type.
:::Warning If entitlement is equal to assigned The API allows to increase/decrease the value of the entitlement. However, you can of course not lower the entitlement below the amount of numbers that is already assigned to the customer. However, you can lower the entitlement below the current amounts of disconnected and reserved numbers. Reserved and disconnected numbers are not considered when enforcing entitlements. :::
Request
Endpoint
PUT /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/entitlements/{id}
Authorization
Required role
tenants.instance.subscriptions.entitlements.instance.update
Path Parameters
| Parameter | Type | Description |
|---|---|---|
draas_instance | string | See common parameters |
uuid | string | A system generated unique ID (UUID) identifying the tenant for which you want to modify the entitlement |
sub_id | integer | Index of the subscription for which you want to update a number entitlement |
id | integer | Index of the customer entitlement you want to update. Note that this is not the licenseModelId but the ID of the entitlement object linked to the subscription |
URL/Query parameters
N/A
Body
| Parameter | Type | Description | Required |
|---|---|---|---|
entitlement | integer | The quantity of numbers of this type that the customer is allowed to use | no |
externalReference | string | Optional parameter that could be used to save the reference given to this product in an external - typically billing - platform | no |
Example
{
"entitlement": 5
}Response
Status codes
| Parameter | Description |
|---|---|
200 | The entitlement was updated successfully |
400 | Error while updating the entitlement |
403 | The API consumer doesn't have sufficient rights to perform this action |
404 | The entitlement does not exist |
500 | Uncatched error on server side |
Success
Body
| Parameter | Type | Description | Conditional |
|---|---|---|---|
id | integer | Index of the modified entitlement | no |
Example
{
"id": 543
}Delete an entitlement
Use this endpoint to delete an existing entitlement for a tenant on the platform.
WARNING
You can only delete an entitlement if currently no numbers are assigned to the subscription under that entitlement.
Request
Endpoint
DELETE /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/entitlements/{id}
Authorization
Required role
tenants.instance.subscriptions.entitlements.instance.delete
Path Parameters
| Parameter | Type | Description |
|---|---|---|
draas_instance | string | See common parameters |
uuid | string | A system generated unique ID (UUID) identifying the tenant that owns the subscription |
sub_id | integer | Index of the subscription for which you want to delete an entitlement |
id | integer | Index of the customer entitlement you want to delete. Note that this is not the licenseModelId but the ID of the entitlement object linked to the subscription |
URL/Query parameters
N/A
Body
N/A
Response
Status codes
| Parameter | Description |
|---|---|
200 | The entitlement was deleted successfully. If the entitlement didn't exist, delete will be considered as being executed successfully |
400 | Error while deleting the entitlement |
403 | The API consumer doesn't have sufficient rights to perform this action |
500 | Uncatched error on server side |
Success
Body
| Parameter | Type | Description | Conditional |
|---|---|---|---|
id | integer | Index of the deleted entitlement | no |
Example
{
"id": 543
}