Fragen? 0800 55400300
View Categories

Cloud-PBX API

6 min read

With the Cloud PBX API, you can create, update or query the configuration of Cloud PBX users.

Configuration of Cloud PBX users:

A method to retrieve a list of all Cloud PBX user accounts (of a customer).

POST https://api.tenios.com/cloud-pbx/list

 

Request Parameter:

​

access_key The API access key. It can be found in the menu item General Settings, section API in the customer portal.
page The page of the configuration to be retrieved.
page_size The page size or maximum number of cloud PBX users to be returned.

Response Parameter:

success true if successful, otherwise error.
items[] A list of items where each is a Cloud PBX user account. Please note, that the “password” filed will not be included.
total_items Total amount of available items.
page_size Amount of items per page.
page Result page number (starts from 1)
Items:
user_name The user name of the Cloud PBX user.
first_name The first name of the Cloud PBX user.
last_name The last name of the Cloud PBX user.
internal_extension The internal extension of the Cloud PBX user.
outbound_allowed A flag indicating whether the Cloud PBX user is allowed to make outgoing calls.
sip_login_enabled A flag indicating whether the cloud PBX user is allowed to log in to the PBX portal (https://pbx.tenios.com).
call_history_enabled A flag indicating whether the call history should be displayed in the PBX portal (https://pbx.tenios.com).
email The email address of the Cloud PBX user.

Example of a successful request:

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "page": 1,
   "page_size": 2
}

API Response:

HTTP Status Code: 200 (OK)

{
   "success": true,
   "items": [
      {
         "user_name": "+49221234567",
         "first_name": "Toni",
         "last_name": "Tester",
         "internal_extension": "",
         "outbound_allowed": false,
         "sip_login_enabled": true,
         "call_history_enabled": true,
         "email": "tt@test.com"
      },
      {
         "user_name": "+49221235655",
         "first_name": "Alice",
         "last_name": "Example",
         "internal_extension": "",
         "outbound_allowed": true,
         "sip_login_enabled": false,
         "call_history_enabled": false,
         "email": "ae@test.com"
      }
   ],
   "total_items": 10,
   "page_size": 2,
   "page": 1
}

 

Examples of invalid requests:

BAD_CREDENTIALS
This code is returned if an invalid access_key was provided.

Request:

{
   "access_key": "12345676",
   "page": 1,
   "page_size": 10
}

API Response:

HTTP Status Code: 403 (Forbidden)

{
   "error_code": "BAD_CREDENTIALS",
   "error_message": "Bad credentials",
   "fields": []
}
FIELD_NEGATIVE_OR_ZERO
This error is returned if the field “page_size” has a neutral or negative value.

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "page": 1,
   "page_size": -1
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "FIELD_NEGATIVE_OR_ZERO",
   "error_message": "Parameter 'page_size' value can not be negative or equal to zero",
   "fields": [
      "page_size"
   ]
}

 

Change or create the configuration of Cloud PBX users:

A method to change or create the configuration of Cloud PBX users.

The parameter user_name must be a valid Cloud-PBX phone number.

POST https://api.tenios.com/cloud-pbx/upsert/{user_name}

 

Request Parameter:

access_key The API access key. It can be found in the menu item General Settings, section API in the customer portal.
user_name User name is always the phone number of the user. Note, that this parameter is sent as a part of the URL.
first_name The user first name of the Cloud PBX user. Note, this parameter can also be empty.
last_name The last name of the Cloud PBX user. Note, this parameter can also be empty.
internal_extension Optional The internal extension of the Cloud PBX user.
outbound_allowed A flag indicating whether the Cloud PBX user is allowed to make outgoing calls.
sip_login_enabled A flag indicating whether the cloud PBX user is allowed to log in to the PBX portal (https://pbx.tenios.com).
email Optional The email address of the Cloud PBX user.
call_history_enabled A flag indicating whether the call history should be displayed in the PBX portal (https://pbx.tenios.com).

 

Response Parameter:

success true if successful, otherwise error.

Example of a successful request:

Request:

Example: https://api.tenios.com/cloud-pbx/upsert/+49221000002

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "password": "i7Lkm07",
   "outbound_allowed": "true",
   "sip_login_enabled": "true",
   "call_history_enabled": "true",
   "first_name": "Peter",
   "last_name": "Mustermann"
}

API Response:

HTTP Status Code: 200 (OK)

{
   "success": true
}

 

Examples of invalid requests:

FIELD_IS_REQUIRED
This error is returned if a mandatory parameter is not provided in the request.

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "outbound_allowed": "true",
   "sip_login_enabled": "true",
   "call_history_enabled": "true",
   "first_name": "Peter",
   "last_name": "Mustermann"
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "FIELD_IS_REQUIRED",
   "error_message": "Parameter 'password' is required",
   "fields": [
      "password"
   ]
}
NOT_FOUND
This error is returned when the requested “user_name” parameter does not exist.

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "password": "i7Lkm07",
   "outbound_allowed": "true",
   "sip_login_enabled": "true",
   "call_history_enabled": "true",
   "first_name": "Peter",
   "last_name": "Mustermann"
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "success": false,
   "error_code": "NOT_FOUND",
   "error_message": "Not found.",
   "fields": []
}
PASSWORD_IS_IN_BLACKLIST
This error is returned when the “password” parameter is in the blacklist.

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "password": "12345678",
   "outbound_allowed": "true",
   "sip_login_enabled": "true",
   "call_history_enabled": "true",
   "first_name": "Peter",
   "last_name": "Mustermann",
   "email": "pm@test.com"
}

 

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "success": false,
   "error_code": "PASSWORD_IS_IN_BLACKLIST",
   "error_message": "The password is in the password blacklist, please choose another one.",
   "fields": [
      "password"
   ]
}
BAD_REQUEST_1
This error is returned when the “user_name” parameter is invalid. Example: https://api.tenios.com/cloud-pbx/upsert/+1234564646

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "password": "i7Lkm07",
   "outbound_allowed": "true",
   "sip_login_enabled": "true",
   "call_history_enabled": "true",
   "first_name": "Peter",
   "last_name": "Mustermann"
}

 

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "BAD_REQUEST",
   "error_message": "Invalid 'user_name' parameter",
   "fields": [
      "user_name"
   ]
}
BAD_REQUEST_2
This error is returned when the “email” parameter is invalid.

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "password": "i7Lkm07",
   "outbound_allowed": "true",
   "sip_login_enabled": "true",
   "call_history_enabled": "true",
   "first_name": "Peter",
   "last_name": "Mustermann",
   "email": "invalid@emailadress"
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "BAD_REQUEST",
   "error_message": "Invalid 'email' parameter",
   "fields": [
      "email"
   ]
}

TOP