Query a Specific Cloud PBX by URL

Query the detailed information of a specific Cloud PBX using its URL.

Request URL

GET {base_url}/dm/open_api/v1/cloud_pbx/instances/get

Request parameters

Headers


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

Query parameter


Parameter	Required	Type	Description
url	Yes	String	The URL of the Cloud PBX. Note: You can query the Cloud PBX URL using Query All the Cloud PBXs.

Response parameters


Parameter	Type	Description
data	Object <Details>	The detailed information of the Cloud PBX.
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.
pbxStatus	String	The running status of the Cloud PBX. `Stopped` `Starting` `Running` `Upgrading` `Restoring` `Provisioning`
activationStatus	String	The activation status of the Cloud PBX. `Activated` `Unactivated`
name	String	The name of the Cloud PBX.
sn	String	The Serial Number (SN) of the Cloud PBX.
plan	String	The subscribed plan of the Cloud PBX. `Enterprise Plan` `Ultimate Plan`
planExpirationDate	Long	The expiration time of the PBX subscribed plan.
extensionCapacity	Long	The extension capacity of Cloud PBX.
concurrentCallCapacity	Long	The concurrent call capacity of Cloud PBX.
recordingStatus	String	Whether the call recording feature of Cloud PBX is enabled or not. `Enabled` `Disabled`
recordingCapacity	Long	The call recording capacity of the Cloud PBX.
transcriptionCapacity	Long	The total number of AI transcription minutes of the Cloud PBX.
transcriptionCapacityPlan	Long	The number of AI transcription minutes included in the Cloud PBX plan. Note: The Enterprise Plan includes 120 minutes, while the Ultimate Plan includes 240 minutes.
transcriptionCapacityAddon	Long	The extra number of minutes purchased for the PBX, in addition to those included in the PBX plans.
usedTranscription	Long	The number of AI transcription minutes used.
region	String	The region where the Cloud PBX is launched.
url	String	The URL of the Cloud PBX.
type	String	The PBX type. `Trial` `Commercial`
expirationDate	Long	The expiration time of Cloud PBX.
allowRunAfterExpirationDate	Boolean	Whether the Cloud PBX remains operational after its expiration time. `true`: PBX remains operational. `false`: PBX becomes unavailable.
version	String	The firmware version of Cloud PBX.
group	String	The group to which the Cloud PBX belongs.
creator	Object <Creator_Info>	The information of the Cloud PBX creator.
creatorRole	String	The role of the Cloud PBX creator. `My Colleague` `Hosting User` `Super Administrator`
createTime	Long	The create time of Cloud PBX.
initialStartUpTime	Long	When the Cloud PBX was first started.
upgradeInPbx	String	Whether firmware upgrading on PBX side is enabled or not. `Enabled` `Disabled`
im	String	Whether the internal chat feature (IM) of the PBX is enabled or not. `Enabled` `Disabled`
pbxApi	String	Whether API feature of the Cloud PBX is enabled or not. `Enabled` `Disabled`
passwordlessLogin	String	Whether passwordless login to PBX is enabled or not. `Enabled` `Disabled`
allowSuperiorPasswordlessLogin	String	Whether passwordless login to PBX for your superior account is enabled or not. `Enabled` `Disabled`
provisioningViaTemplate	String	Whether the PBX is allowed to be provisioned via a template. `Enabled` `Disabled`
lastUsedTemplate	String	The last used provisioning template.
lastUsedTime	Long	The last time the template was used to provision the PBX.
activeCalls	String	The number of the current active calls on the PBX.
usedExtensions	String	The number of created extensions on the PBX.
usedRecording	String	The used recording capacity on the PBX (Unit: Minute).
lastBackupTime	Long	The last time the PBX was backed up via task from Yeastar Central Management.
recordingExpireDate	Long	The expiration time of additional recording minutes allocated to the PBX (i.e., minutes beyond the free 500-minutes).
pbxHubCluster	Object<PBXHub_Info>	The information of the PBXHub Server where the PBX is created.

Creator_Info


Parameter	Type	Description
firstName	String	First name.
lastName	String	Last name.
email	String	Email address.

PBXHub_Info


Parameter	Type	Description
clusterName	String	The name of the PBXHub Server.
ip	String	The IP of the PBXHub Server.

Example

Request example

Query the information of a Cloud PBX using its URL.

GET /dm/open_api/v1/cloud_pbx/instances/get?url=cloud2.example.yeastarcloud.com HTTP/1.1
Host: ycm.yeastar.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21Kd3RQYXlsb2FkSW5mbyI6eyJncmFudFR5cGUiOiJjbGllbnRfY3JlZGVudGlhbHMiLCJ5c0lkIjoxNzg5NjM2MDM5MDg1MDI1NjY0NSwidmVyc2lvbiI6MTY2Mzc0MTEyNSwicmVmcmVzaFZlcnNpb24iOjE2NjQ0Mzk2OTF9LCJzY29wZSI6WyJhbGwiXSwiZXhwIjoxNjY0NDQxNDkxLCJhdXRob3JpdGllcyI6WyJST0xFX0NMSUVOVCJdLCJqdGkiOiI4OTVmM2I4ZC1iYjE5LTQ5Y2ItODE5NC01ZmUxYTNiMTgyNzAiLCJjbGllbnRfaWQiOiJ5QXN4ZzdITkRFczNxSHprQk1aUU5Pblo2NTBPRUNNWSJ9.nlO7AEithe4a-nAfPSAJv74wnJ0x-oH4jVChniV1Lmk

Response example

HTTP/1.1 200 OK
{
  "data": {
            "cloudPbxId": 7738,
            "pbxStatus": "Running",
            "activationStatus": "Activated",
            "name": "Yeastar P-Series Cloud PBX2",
            "sn": "3658B431119XXXXX",
            "plan": "Ultimate Plan",
           "planExpirationDate": 1638427632,
            "extensionCapacity": 15,
            "concurrentCallCapacity": 15,
            "recordingStatus": "Enabled",
            "recordingCapacity": 500,
            "transcriptionCapacity":240,
            "transcriptionCapacityPlan":240,
            "transcriptionCapacityAddon":0,
            "usedTranscription":0,
            "region": "China(GuangDong)",
            "url": "cloud2.example.yeastarcloud.com",
            "type": "Commercial",
            "expirationDate": 1638427632,
            "allowRunAfterExpirationDate": false,
            "version": "84.8.0.25",
            "creator": 
                 {
                   "firstName": "Jane",
                   "lastName": "Smith",
                   "email": "jane@example.com"
                  },
             "creatorRole": "Hosting User",
             "createTime": 1635749236,
             "initialStartUpTime": 1635749236，
             "upgradeInPbx": "Enabled",
             "im": "Enabled",
             "pbxApi": "Disabled",
             "passwordlessLogin": "Disabled",
             "provisioningViaTemplate": "Enabled",
             "allowSuperiorPasswordlessLogin": "Disabled",
             "lastUsedTemplate": "PCE-Provision-Template",
             "lastUsedTime": 1680138886,
             "activeCalls": "10",
             "usedExtensions": "10",
             "usedRecording": "150",
             "lastBackupTime": 1729786748,
             "recordingExpireDate": 1787031505,
            "pbxHubCluster": 
                      {
                         "clusterName": "us-pbxhub-a",
                         "ip": "192.168.1.186"
                      }
            },
  "requestId": "814bc5a4d2f281cd70a77534b4ccf48f",
  "status": "Success",
  "time": 1664440292
}