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

{
    "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

{
    "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"
        }
    ]
}

List all the rate plans of an entity

This endpoint returns the rate plans available for a given group, distributor, reseller or tenant. The list is not paginated: the full list of rate plans is returned in one response. For the rate plans of a subscription, see List all the rate plans supported by the subscription.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/groups/{uuid}/rate_plans

GET /api/v01/draas/{draas_instance}/distributors/{uuid}/rate_plans

GET /api/v01/draas/{draas_instance}/resellers/{uuid}/rate_plans

GET /api/v01/draas/{draas_instance}/tenants/{uuid}/rate_plans

Authorization

Required role

groups.instance.rate_plans.list

distributors.instance.rate_plans.list

resellers.instance.rate_plans.list

tenants.instance.rate_plans.list

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the group, distributor, reseller or tenant

URL/Query parameters

N/A

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 (e.g. EUR, USD, GBP), accordingly to the currency setting. Only returned at group level	yes
ratePlans	array	List containing the rate plans of the entity	no

Example

{
    "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

{
    "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

{
    "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

{
    "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

{
    "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