Rate plans
A rate plan is a set of prices that are applied to outbound phone calls made through the platform. For each phone call, the customer must pay a setup cost and/or per minute cost. If the source and destination number are in the same country, a national rate is applied while, if both are different, an international rate applies.
Depending on the type of traffic (e.g. SIP trunking, MS Teams, ...) different rates might be applied
Get a list of destinations
List all available destinations that might be used to define new rate plans.
Request
Endpoint
GET /api/v01/draas/{draas_instance}/public/rate_plans/destinations
Authorization
Required role
Available for all authenticated users
Path Parameters
| Parameter | Type | Description |
|---|---|---|
draas_instance | string | See common parameters |
URL/Query parameters
| Parameter | Type | Description | Required? |
|---|---|---|---|
search | string | Used to perform a search through all searchable properties of a destination that look like the string passed (currently only name is allowed) | no |
sort | string | Allows to specify one searchable property of a destination to apply a sorting operation (currently only name is allowed) | no |
dir | string | When performing a sort operation, specifies the type. Allowed values are asc for ascending (default) or desc for descending | no |
page_size | integer | Used for pagination, determines the maximum number of records on one page of results (defaults to 10) | no |
next | string | A token used to get the next records in the list. This token is taken back from the results of the previous call | no |
Response
Status codes
| Parameter | Description |
|---|---|
200 | One or more destinations found |
400 | Error while processing the request |
403 | The API consumer doesn't have sufficient rights to perform this action |
404 | No destination found |
500 | Uncatched error on server side |
Success
Body
| Parameter | Type | Description | Conditional? |
|---|---|---|---|
results | integer | Total number of results from the query | no |
pages | integer | Total number of pages according to pagination settings | no |
page | integer | Current displayed page from the set of pages | no |
next | string | A token used for infinite scrolling, to be used in the next call to retrieve subsequent records. Only present if the list of numbers has to be continued | yes |
destinations | array | List containing all destination objects in the system | no |
Destination Object
| Parameter | Type | Description | Conditional? | Searchable? |
|---|---|---|---|---|
id | integer | Internal ID of the destination | no | no |
name | string | Name the destination | no | yes |
Example
json
{
"results": 9,
"pages": 3,
"page": 1,
"next": "c2VhcmNoPW5ldCZwYWdlX3NpemU9MyZkaXI9YXNjJnBhZ2U9Mg==",
"destinations": [
{
"id": 449,
"name": "Croatia Internet Access"
},
{
"id": 454,
"name": "Czech Republic Private Telephone Networks"
},
{
"id": 663,
"name": "Netherlands"
}
]
}List all the rate plans supported by the system
Currently the platform only distinguishes between MS Teams and SIP Trunking calls. However, this might change in the future. This endpoint returns the actual price plans supported by the platform.
Request
Endpoint
GET /api/v01/draas/{draas_instance}/public/rate_plans
Authorization
Required role
Available for all authenticated users
Path Parameters
| Parameter | Type | Description |
|---|---|---|
draas_instance | string | See common parameters |
URL/Query parameters
| Parameter | Type | Description | Required? |
|---|---|---|---|
parent | string | Set this value to the desired parent entity to retrieve its rate plans | yes |
type | string | Set this value to the desired entity type to retrieve its rate plans. See entity type. | yes |
Entity Type Object
Value from:
- group,
- distributor,
- reseller,
- tenant
Response
Status codes
| Parameter | Description |
|---|---|
200 | One or more rate plans 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? |
|---|---|---|---|
currency | string | The currency code, accordingly to the currency setting. | no |
ratePlans | array | List containing the rate plans supported by the platform. | no |
Rate Plan Object
| Parameter | Type | Description | Conditional? | Searchable? |
|---|---|---|---|---|
id | string | Identifier. | no | no |
name | string | Name of the rateplan | no | yes |
description | string | Description of the rateplan | no | yes |
Example
json
{
"currency": "EUR",
"ratePlans": [
{
"id": "msteams",
"name": "MS Teams",
"description": "Applicable for all calls made from a MS Teams account"
},
{
"id": "trunking",
"name": "SIP trunking",
"description": "Applicable for all calls made from a SIP trunk"
}
]
}Get a specific rateplan
This endpoint returns for a specific rateplan all different prices that apply (setup + per minute) per destination.
Request
Endpoint
GET /api/v01/draas/{draas_instance}/public/rate_plans/{rate_plan}
Authorization
Required role
Available for all authenticated users. However, you will only see the rateplans applicable for you.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
draas_instance | string | See common parameters |
rate_plan | string | Refers to the rateplan for which you want to get the pricing. See also rateplans |
URL/Query parameters
Response
Status codes
| Parameter | Description |
|---|---|
200 | One or more prices 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? |
|---|---|---|---|
prices | array | List containing the latest price objects for any dial plan groups. | no |
Price Object
| Parameter | Type | Description | Conditional? | Searchable? |
|---|---|---|---|---|
destination | string | Destination for which this prices applies. | no | yes |
destinationId | string | Internal ID of the destination in question. This ID has to be used to fetch more details about this specific destination. | no | yes |
startDate | date | Date since when this price has become active. | no | yes |
nextUpdate | date | Next date when a new price activation will occur. | yes | yes |
national | object | Contains 2 floats:setup and duration. The first one concerns to the setup price in euro for a call when source and destination are located in the same country. | no | yes |
international | object | Contains 2 floats:setup and duration. The first one concerns to the setup price in euro for a call when source and destination are located in a different country. | no | yes |
Example
json
{
"prices": [
{
"destination": "Italy",
"destinationId": 177,
"activeSince": "2022-07-14",
"nextUpdate": "2022-09-02",
"national": {
"setup": 3.2,
"duration": 4.3
},
"international": {
"setup": 5.4,
"duration": 6.5
}
},
{
"destination": "Austria Freephone",
"destinationId": 414,
"activeSince": "2022-07-12",
"national": {
"setup": 1.0,
"duration": 2.0
},
"international": {
"setup": 3.0,
"duration": 4.05
}
},
{
"destination": "Azerbaijan Mobile",
"destinationId": 28,
"activeSince": "2022-07-09",
"national": {
"setup": 1.0,
"duration": 2.0
},
"international": {
"setup": 3.0,
"duration": 4.05
}
}
]
}List price history for a given destination of a rate plan
This endpoint returns the history of prices for a given destination of a rate plan.
Request
Endpoint
GET /api/v01/draas/{draas_instance}/groups/{uuid}/rate_plans/{rate_plan_id}/destinations/{destination_id}/prices
Authorization
Required role
public.rate_plans.instance.destinations.instance.prices.list (only allowed to system administrators)
Path Parameters
| Parameter | Type | Description |
|---|---|---|
draas_instance | string | See common parameters |
uuid | string | A system generated unique ID (UUID) identifying the group for which you want to get the supported rate plans |
rate_plan_id_id | string | The requested rate plan identifier |
destination_id | integer | The requested destination identifier |
URL/Query parameters
| Parameter | Type | Description | Required? |
|---|---|---|---|
page_size | integer | Used for pagination, determines the maximum number of records on one page of results (defaults to 10) | no |
next | string | A token used to get the next records in the list. This token is taken back from the results of the previous call | no |
Response
Status codes
| Parameter | Description |
|---|---|
200 | One or more price found for this destination |
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? |
|---|---|---|---|
results | string | Total count of results that match your query | no |
pages | string | Total count of result pages that are available | no |
page | string | ID of the page that is currently returned | no |
next | string | A token used for infinite scrolling, to be used in the next call to retrieve subsequent records. Only present if the list of numbers has to be continued | yes |
prices | array | List containing all price objects of the requested dial plan group. | no |
Example
json
{
"results": 17,
"pages": 9,
"page": 1,
"next": "cGFnZV9zaXplPTImcGFnZT0y",
"prices": [
{
"id": 51,
"startDate": "2023-06-09",
"national": {
"setup": 8.0,
"duration": 8.0
},
"international": {
"setup": 14.0,
"duration": 14.0
}
},
{
"id": 50,
"startDate": "2022-06-29",
"national": {
"setup": 5.0,
"duration": 5.0
},
"international": {
"setup": 10.0,
"duration": 10.0
}
}
]
}Add a new destination / price to a rate plan
This endpoint allows to add a destination and and a price to a rate plan.
Request
Endpoint
POST /api/v01/draas/{draas_instance}/groups/{uuid}/rate_plans/{rate_plan_id}/prices
Authorization
Required role
public.rate_plans.instance.prices.create (only allowed to system administrators)
Path Parameters
| Parameter | Type | Description |
|---|---|---|
draas_instance | string | See common parameters |
uuid | string | A system generated unique ID (UUID) identifying the group for which you want to get the supported rate plans |
rate_plan_id | string | The rate plan identifier for which you want to add a destination / price |
URL/Query parameters
N/A
| Parameter | Type | Description | Required |
|---|---|---|---|
destinationId | integer | Destination index in the SRE database | yes |
startDate | string | Application start date for the price expressed in format YYYY-MM-DD. Note that all dates start at time `00:00:00 (midnight). There can be only one record per date. The date has to be in the future. If the date is omitted, start date is set at midnight tomorrow | no |
national | object | Contains 2 floats: setup and duration. The first one concerns to the setup price in euro for a call when source and destination are located in the same country | no |
international | object | Contains 2 floats: setup and duration. The first one concerns to the setup price in euro for a call when source and destination are located in a different country | no |
Example
json
{
"destinationId": 450,
"startDate": "2022-09-02",
"national": {
"setup": 3.2,
"duration": 4.3
},
"international": {
"setup": 5.4,
"duration": 6.5
}
}Response
Status codes
| Parameter | Description |
|---|---|
201 | The price was correctly created |
400 | Error while creating the price |
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 | ID of the created price in the SRE database | no |
Example
json
{
"id": 36
}Remove a price from a destination
This endpoint allows to remove a price from a given destination for a given rate plan. Only prices set in the future are allowed for removal.
Request
Endpoint
DELETE /api/v01/draas/{draas_instance}/groups/{uuid}/rate_plans/{rate_plan_id}/prices/{price_id}
Authorization
Required role
public.rate_plans.instance.prices.delete (only allowed to system administrators)
Path Parameters
| Parameter | Type | Description |
|---|---|---|
draas_instance | string | See common parameters |
uuid | string | A system generated unique ID (UUID) identifying the group for which you want to get the supported rate plans |
rate_plan_id | string | The rate plan identifier from which you want to remove a price |
price_id | string | The price identifier |
URL/Query parameters
N/A
Body
N/A
Response
Status codes
| Parameter | Description |
|---|---|
204 | The price was correctly removed from the destination for the given rate plan |
403 | The API consumer doesn't have sufficient rights to perform this action |
500 | Uncatched error on server side |
Success
Body
N/A