Create a Cloud PBX

Create a Cloud PBX.

Request URL

POST {base_url}/dm/open_api/v1/cloud_pbx/instances

Request parameters

Headers


Parameter	Required	Type	Description
Authorization	Yes	String	Pass the access token in the header. Format: Bearer `{access_token}`.

Body


Parameter	Required	Type	Description
name	Yes	String	PBX name.
plan	Yes	String	PBX Plan. Valid value: `Enterprise Plan` `Ultimate Plan`
extensionCapacity	Yes	Long	The number of extensions for the Cloud PBX.
concurrentCallCapacity	Yes	Long	The number of concurrent calls for the Cloud PBX.
recordingStatus	Yes	String	Whether to enable the call recording feature for the Cloud PBX. Valid value: `Enabled` `Disabled`
recordingCapacity	Yes	Long	The number of call recording minutes. Note: If you set the parameter to 0, the call recording feature of the Cloud PBX will be disabled.
regionId	Yes	Integer	The ID of the region where the Cloud PBX will be launched. Note: You can query the region ID using Query Available Regions.
subDomain	Yes	String	The sub-domain of the Cloud PBX. Note: The Cloud PBX URL is composed of a custom sub-domain and a specific domain name. Only allowed to enter numbers, letters, and hyphens `-` in this parameter.
domainId	Yes	Integer	The ID of the desired domain name. Note: You can query the domain ID using Query Available Domain Names.
versionId	Yes	Integer	The ID of the PBX firmware version. Note: You can query the version ID using Query Available Firmwares.
type	Yes	String	PBX Type. Valid value: `Trial` `Commercial`
transcriptionCapacity	No	Long	The number of AI transcription minutes you want to assign to the PBX in addition to those included in the PBX plan. Note: This setting only takes effect on the P-Series Cloud PBX with firmware version 84.19.0.110 or later. The Enterprise Plan includes 120 minutes, while the Ultimate Plan includes 240 minutes. Set the value to 0, or omit this parameter if no extra transcription minutes are needed.
expirationDate	No	Long	PBX expiration date. Note: Enter the timestamp of the desired expiration date in this field.
allowRunAfterExpirationDate	No	Boolean	Whether to allow the PBX to remain operational after its expiration date. Valid value: `true`: Allow `false`: Not allow Note: This parameter is required when the `expirationDate` parameter is configured.
customerIds	Yes	Array <Long>	The ID(s) of the customer(s) that will be associated with the Cloud PBX. Note: You can query the customer ID using Query all the Customers or Query the Customer(s) of a Cloud PBX. Support up to 5 customers; Use a comma to separate multiple IDs.
trunkDidRelations	No	Array <Trunk_DID_Relation>	The relation list of DID numbers to be assigned to the Cloud PBX and their associated shared trunks. Note: This parameter only takes effect when the firmware of Cloud PBX is 84.19.0.22 or later.
upgradeInPbx	Yes	String	Whether to enable firmware upgrading on PBX side. Valid value: `Enabled` `Disabled`
im	Yes	String	Whether to enable internal chat feature (IM) of the Cloud PBX. Note: The setting can be applied to the P-Series Cloud PBXs with a firmware version of 84.12.0.32 or later. Valid value: `Enabled` `Disabled`
pbxApi	No	String	Whether to enable API feature of the Cloud PBX. Valid value: `Enabled` `Disabled`
passwordlessLogin	Yes	String	Whether to enable passwordless login to the Cloud PBX. Valid value: `Enabled` `Disabled`
allowSuperiorPasswordlessLogin	Yes	String	Whether to enable passwordless login to the Cloud PBX for your superior account. Note: The setting of this parameter only takes effect when `passwordlessLogin` is set to `Enabled`. Valid value: `Enabled` `Disabled`
provisioningViaTemplate	No	String	Whether to allow the Cloud PBX to be provisioned via a template. Valid value: `Enabled` `Disabled`
provisionTemplateId	No	Integer	The unique ID of the provisioning template. Note: You can query the provisioning template ID using the Query All the Provisioning Templates interface.
trunkConfigurationAccess	No	String	Whether to allow the PBX users to add and import trunks on the PBX. Note: You have the permission to configure Trunk Configuration Access for Cloud PBXs, or the setting will not take effect. This setting only takes effect on the P-Series Cloud PBX with firmware version 84.21.0.66 or later. Valid value: `Enabled` `Disabled`
autoActivated	No	Boolean	Whether to automatically activate the Cloud PBX. Note: This setting only takes effect on the P-Series Cloud PBX with firmware version 84.21.0.66 or later. Valid value: `true`: Automatically activate the PBX after creation. `false` (Default)
cloudPbxInitialConfigRequest	No	Object<Initial_Config>	The initial configurations of the Cloud PBX. Note: This parameter is REQUIRED when `autoActivated` is set to `true`. This setting only takes effect on the P-Series Cloud PBX with firmware version 84.21.0.66 or later.

Trunk_DID_Relation


Parameter	Required	Type	Description
trunkId	Yes	Integer	The ID of the shared trunk. Note: You can query the trunk ID using Query Available Shared Trunks.
didIds	Yes	Array<Integer>	The ID list of the DID numbers. Note: You can query the DID number ID using Query Available DID Numbers of Specific Trunk.

Initial_Config


Parameter	Required	Type	Description
administratorSettings	Yes	Object<Admin_Settings>	The information of the PBX super administrator account.
dateAndTimeSettings	Yes	Object<Date_Time>	The PBX system's date and time settings.
localization	Yes	Object<Local_Setting>	The PBX's localization settings.

Admin_Settings


Parameter	Required	Type	Description
username	Yes	String	The username for logging into the PBX web portal. Note: The length must be at least 6 characters. The username must contain both uppercase and lowercase letters. Special character `@` is not allowed.
newPassword	Yes	String	The password for logging into the PBX web portal. Note: The length must be at least 10 characters. The password must contain uppercase letters, lowercase letters, and numbers. 4 repeated or consecutive numbers are not allowed.
confirmPassword	Yes	String	Repeat the password for confirmation.
emailAddress	Yes	String	The email address of the super administrator.
prefix	No	String	The dialing prefix. If set, when the system needs to notify the super administrator of system events by calling the mobile number, it will automatically prepend this prefix to the number for dialing. Note: After the initialization is complete, you need to create an outbound route on the PBX with a dial pattern that matches this prefix to ensure successful notification calls.
mobileNumber	No	String	The mobile number for receiving system notifications. Note: This parameter is REQUIRED when `enableMobileNotify` is set to `Enabled`. The length can not exceed 31 characters.
enableEventNotify	No	String	Whether to send event notifications to the PBX super administrator or not. Valid value: `Enabled` `Disabled`
contactName	No	String	The name of the contact who will receive event notifications. Note: This parameter is REQUIRED when the `enableEventNotify` is set to `Enabled`.
notificationLevel	No	String	Filters event notifications by severity level. Note: This parameter is REQUIRED when `enableEventNotify` is set to `Enabled`. Multiple levels can be specified, separated by spaces (e.g., `"error warn"`). Valid value: `error`: Critical alerts requiring immediate attention. `warn`: Warnings indicating non-ideal states that may lead to errors. `info`: General informational messages.
enableEmailNotify	No	String	Whether to send system event notifications to the contact by email. Note: Either `enableEmailNotify` or `enableMobileNotify` is REQUIRED when `enableEventNotify` is set to `Enabled`. Valid value: `Enabled` `Disabled`
enableMobileNotify	No	String	Whether to send system event notifications to the contact by calling the mobile number. Note: Either `enableEmailNotify` or `enableMobileNotify` is REQUIRED when `enableEventNotify` is set to `Enabled`. Valid value: `Enabled` `Disabled`

Date_Time


Parameter	Required	Type	Description
timeZone	Yes	String	The default time zone for the PBX system. Note: For valid value, refer to PBX Creation Value Reference - Time Zone.
enableDst	Yes	String	Whether to enable Daylight Saving Time (DST). Valid value: `Enabled` `Disabled`
dateFormat	Yes	String	The display format for dates within the system. Valid value: `yyyy/mm/dd`: Year/Month/Day `mm/dd/yyyy`: Month/Day/Year `dd/mm/yyyy`: Day/Month/Year
timeFormat	Yes	String	The display format for time within the system. Valid value: `12-hour` `24-hour`

Local_Settings


Parameter	Required	Type	Description
systemPromptLanguage	Yes	String	The default language for system voice prompts. Note: For valid value, refer to PBX Creation Value Reference - Prompt.
emailLanguage	Yes	String	The language used for system-generated notification emails. Note: For valid value, refer to PBX Creation Value Reference - Notification Email Language.
deviceName	Yes	String	The device name for the PBX system.
nameDisplayFormat	Yes	String	The format for displaying user and contact names. Valid value: `first_last`: `{First_Name}` `{Last_Name}` (with a space) `first_last`: `{Last_Name}` `{First_Name}` (with a space) `lastfirst`: `{Last_Name}{First_Name}` (without a space)
toneRegion	Yes	String	Specify your country/region, PBX will adopt the standard call progress tones for that area (including default dial tone, busy tone, ring tone, etc.). Note: Refer to PBX Creation Value Reference - Tone Region for valid value.
enbCountryCode	Yes	String	Decide whether to restrict users from making international calls. Valid value: `Enabled` `Disabled`
dialCode	No	String	Specify a custom prefix to identify international calls within the PBX. When a user dials a number starting with this prefix, the PBX will treat it as an international call. Note: This parameter is REQUIRED when `enbCountryCode` is set to `Enabled`.

Response parameters


Parameter	Type	Description
data	Object <Details>	The detailed information.
requestId	String	The unique ID of the request, which can be used to quickly locate the request.
status	String	Request result: `Success` `Failed`
time	Long	The response time. Note: The YCM API response returns a timestamp, you can convert the timestamp to detailed date and time as needed. For more information, see Convert Timestamp to Local Date and Time.

Details


Parameter	Type	Description
cloudPbxId	Long	The ID of the Cloud PBX.

Example

Request example

Create a Cloud PBX:

URL: cloud.test4.yeastarcloud.com;
Region: Asia Pacific(Singapore) (ID: 4);
Domain name: test4.yeastarcloud.com (ID: 4);
Firmware: 84.8.0.25 (ID: 764).

POST /dm/open_api/v1/cloud_pbx/instances HTTP/1.1
Host: ycm.yeastar.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21Kd3RQYXlsb2FkSW5mbyI6eyJncmFudFR5cGUiOiJjbGllbnRfY3JlZGVudGlhbHMiLCJ5c0lkIjoxNzg5NjM2MDM5MDg1MDI1NjY0NSwidmVyc2lvbiI6MTY2Mzc0MTEyNSwicmVmcmVzaFZlcnNpb24iOjE2NjQ0NTAxOTh9LCJzY29wZSI6WyJhbGwiXSwiZXhwIjoxNjY0NDUxOTk4LCJhdXRob3JpdGllcyI6WyJST0xFX0NMSUVOVCJdLCJqdGkiOiJmNzAzYjk0Ni1kMzk4LTQxZWEtOTgwZi1hOGZmNWYxODhiNDAiLCJjbGllbnRfaWQiOiJ5QXN4ZzdITkRFczNxSHprQk1aUU5Pblo2NTBPRUNNWSJ9.N9R6s5ttSah3LRdDBowQYdYw8URWhzyJYiD5cdVm2ZM
Content-Type: application/json
{
  "name": "Yeastar P-Series Cloud PBX",
  "plan": "Enterprise Plan",
  "extensionCapacity": 20,
  "concurrentCallCapacity": 10,
  "recordingStatus": "Enabled",
  "recordingCapacity": 500,
  "transcriptionCapacity":0,
  "regionId": 4,
  "subDomain": "cloud",
  "domainId": 4,
  "type": "Commercial",
  "expirationDate": 1667059200,
  "allowRunAfterExpirationDate":false,
  "versionId": 764,
  "customerIds": [50086182,50429564],
  "upgradeInPbx": "Enabled",
  "im": "Enabled",
  "pbxApi": "Enabled",
  "passwordlessLogin": "Enabled",
  "allowSuperiorPasswordlessLogin": "Enabled",
  "provisioningViaTemplate":"Enabled",
  "provisionTemplateId":306,
  "autoActivated":"true", 
  "cloudPbxInitialConfigRequest":{
    "administratorSettings":{
        "username":"PBXadmin1",
        "newPassword":"Yeastar202",
        "confirmPassword":"Yeastar202",
        "emailAddress":"evelynhong@yeastar.com",
        "prefix":"123",
        "mobileNumber":"123456789",
        "enableEventNotify":"Enabled",
        "contactName":"Evelynhong",
        "notificationLevel":"warn info error",
        "enableEmailNotify":"Enabled",
        "enableMobileNotify":"Enabled"

    },
    "dateAndTimeSettings":{
        "timeZone":"UTC+8 Asia/Shanghai",
        "enableDst":"Enabled",
        "dateFormat":"yyyy/mm/dd",
        "timeFormat":"24-hour"

    },
    "localization":{
        "systemPromptLanguage":"sound-en",
        "emailLanguage":"en",
        "deviceName":"API Test",
        "nameDisplayFormat":"first_last",
        "toneRegion":"us",
        "enbCountryCode":"Enabled",
        "dialCode":"123"

    }
  }
}

Response example

HTTP/1.1 200 OK
{
  "data": {
    "cloudPbxId": 42100
  },
  "requestId": "44151421047434e0ef817a10fc5331a5",
  "status": "Success",
  "time": 1664450755
}