API examples

Article sections

    API examples

    Some simple examples using cURL (Windows Powershell users might prefer Invoke-WebRequest although this requires slightly different syntax). You may also want to try Postman, an app for Windows, MacOS, and Linux that enables you to visually create requests.

    Getting a user list using authentication via the query string and the default JSON output format

    $ curl http://pbx.example.org/apis/pbx/users?key=8d0a0704a96db1773fcb52db2f3e0979
      [{"username": "admin", "uuid": "828638d5-90c5-3abf-9609-7bb0c85ecd6d", "full_name": null, "primary_phone": null}, {"username": "501", "uuid": "26d6d6de-5050-3401-adfa-0967bb414213", "full_name": null, "primary_phone": null}, {"username": "303", "uuid": "c506e9b6-cdbf-360a-b022-b0ff2ad3b4de", "full_name": "John Brown", "primary_phone": null}, {"username": "300", "uuid": "092587dd-3b6f-3cfe-a769-654a0c1e5caa", "full_name": "phone 300", "primary_phone": "92913299-f2d4-3a67-98ca-c76234d3d58f"}, {"username": "500", "uuid": "ad2852c1-5509-3068-b510-f98747b430a1", "full_name": null, "primary_phone": null}, {"username": "301", "uuid": "396edcb6-2818-3d7c-9056-029b972be3c4", "full_name": "phone 301", "primary_phone": "9a899b91-3002-3565-9706-1bcff54589f4"}, {"username": "302", "uuid": "617e8555-b25a-35c2-b1c6-63cf8a867c0f", "full_name": "John Black", "primary_phone": "97fb3488-e763-319d-9db3-f0345ae046ad"}]
    

    Getting a user list using authentication via the query string and XML output format

    $ curl http://pbx.example.org/apis/pbx/users.xml?key=8d0a0704a96db1773fcb52db2f3e0979
      <users>
       <user>
        <full_name/>
        <primary_phone/>
        <username>admin</username>
        <uuid>828638d5-90c5-3abf-9609-7bb0c85ecd6d</uuid>
       </user>
       <user>
        <full_name/>
        <primary_phone/>
        <username>501</username>
        <uuid>26d6d6de-5050-3401-adfa-0967bb414213</uuid>
       </user>
       <user>
        <full_name>John Brown</full_name>
        <primary_phone/>
        <username>303</username>
        <uuid>c506e9b6-cdbf-360a-b022-b0ff2ad3b4de</uuid>
       </user>
       <user>
        <full_name>phone 300</full_name>
        <primary_phone>92913299-f2d4-3a67-98ca-c76234d3d58f</primary_phone>
        <username>300</username>
        <uuid>092587dd-3b6f-3cfe-a769-654a0c1e5caa</uuid>
       </user>
       <user>
        <full_name/>
        <primary_phone/>
        <username>500</username>
        <uuid>ad2852c1-5509-3068-b510-f98747b430a1</uuid>
       </user>
       <user>
        <full_name>phone 301</full_name>
        <primary_phone>9a899b91-3002-3565-9706-1bcff54589f4</primary_phone>
        <username>301</username>
        <uuid>396edcb6-2818-3d7c-9056-029b972be3c4</uuid>
       </user>
       <user>
        <full_name>John Black</full_name>
        <primary_phone>97fb3488-e763-319d-9db3-f0345ae046ad</primary_phone>
        <username>302</username>
        <uuid>617e8555-b25a-35c2-b1c6-63cf8a867c0f</uuid>
       </user>
      </users>
    

    Using HTTP headers for authentication and output format selection

     
    $ curl -u apiKey:8d0a0704a96db1773fcb52db2f3e0979 -H 'Accept: application/xml' http://pbx.example.org/apis/pbx/users
      <users>
       <user>
        <full_name/>
        <primary_phone/>
        <username>admin</username>
        <uuid>828638d5-90c5-3abf-9609-7bb0c85ecd6d</uuid>
       </user>
       <user>
        <full_name/>
        <primary_phone/>
        <username>501</username>
        <uuid>26d6d6de-5050-3401-adfa-0967bb414213</uuid>
       </user>
       <user>
        <full_name>John Brown</full_name>
        <primary_phone/>
        <username>303</username>
        <uuid>c506e9b6-cdbf-360a-b022-b0ff2ad3b4de</uuid>
       </user>
       <user>
        <full_name>phone 300</full_name>
        <primary_phone>92913299-f2d4-3a67-98ca-c76234d3d58f</primary_phone>
        <username>300</username>
        <uuid>092587dd-3b6f-3cfe-a769-654a0c1e5caa</uuid>
       </user>
       <user>
        <full_name/>
        <primary_phone/>
        <username>500</username>
        <uuid>ad2852c1-5509-3068-b510-f98747b430a1</uuid>
       </user>
       <user>
        <full_name>phone 301</full_name>
        <primary_phone>9a899b91-3002-3565-9706-1bcff54589f4</primary_phone>
        <username>301</username>
        <uuid>396edcb6-2818-3d7c-9056-029b972be3c4</uuid>
       </user>
       <user>
        <full_name>John Black</full_name>
        <primary_phone>97fb3488-e763-319d-9db3-f0345ae046ad</primary_phone>
        <username>302</username>
        <uuid>617e8555-b25a-35c2-b1c6-63cf8a867c0f</uuid>
       </user>
      </users>

    Getting a user status

    $ curl -u apiKey:8d0a0704a96db1773fcb52db2f3e0979 -H 'Accept: application/json' http://pbx.example.org/apis/pbx/users/396edcb6-2818-3d7c-9056-029b972be3c4
      {"username": "301", "dnd": false, "uuid": "396edcb6-2818-3d7c-9056-029b972be3c4", "primary_phone": "9a899b91-3002-3565-9706-1bcff54589f4", "phone": "9a899b91-3002-3565-9706-1bcff54589f4", "full_name": "phone 301", "call_forward": null, "cw": false}

    Getting a phone list

    $ curl -u apiKey:8d0a0704a96db1773fcb52db2f3e0979 -H 'Accept: application/json' http://pbx.example.org/apis/pbx/phones
      [{"phone_username": "w7tny", "hot_desk": false, "type": "Snom 300 (V7 firmware)", "uuid": "92913299-f2d4-3a67-98ca-c76234d3d58f", "name": "telefon 300"}, {"phone_username": "u215e", "hot_desk": true, "type": "Snom 300 (V8 firmware)", "uuid": "9a899b91-3002-3565-9706-1bcff54589f4", "name": "telefon 301"}]

    Getting a phone status

    $ curl -u apiKey:8d0a0704a96db1773fcb52db2f3e0979 -H 'Accept: application/json' http://pbx.example.org/apis/pbx/phones/9a899b91-3002-3565-9706-1bcff54589f4
      {"status": "Idle", "uuid": "9a899b91-3002-3565-9706-1bcff54589f4", "type": "Snom 300 (V8 firmware)", "status_code": 0, "phone_username": "u215e", "hot_desk_user": "ad2852c1-5509-3068-b510-f98747b430a1", "hot_desk": true, "name": "telefon 301"}
    

    Fetching events (JSON)

    $ curl -u apiKey:8d0a0704a96db1773fcb52db2f3e0979 -H 'Accept: application/json' 'http://pbx.example.org/apis/pbx/events?limit=10'
    [{"status": "In Use", "event_type": "phone status update", "seq": 0, "status_code": 1, "phone_uuid": "9a899b91-3002-3565-9706-1bcff54589f4", "timestamp": "2012-03-22T13:48:52Z"}, {"status": "Ringing", "event_type": "phone status update", "seq": 1, "status_code": 8, "phone_uuid": "92913299-f2d4-3a67-98ca-c76234d3d58f", "timestamp": "2012-03-22T13:48:52Z"}, {"status": "In Use", "event_type": "phone status update", "seq": 2, "status_code": 1, "phone_uuid": "92913299-f2d4-3a67-98ca-c76234d3d58f", "timestamp": "2012-03-22T13:48:53Z"}, {"status": "Idle", "event_type": "phone status update", "seq": 3, "status_code": 0, "phone_uuid": "92913299-f2d4-3a67-98ca-c76234d3d58f", "timestamp": "2012-03-22T13:48:55Z"}, {"status": "Idle", "event_type": "phone status update", "seq": 4, "status_code": 0, "phone_uuid": "9a899b91-3002-3565-9706-1bcff54589f4", "timestamp": "2012-03-22T13:48:56Z"}]
    $ curl -u apiKey:8d0a0704a96db1773fcb52db2f3e0979 -H 'Accept: application/json' 'http://pbx.example.org/apis/pbx/events?limit=10&last=4'
    []
    $ curl -u apiKey:8d0a0704a96db1773fcb52db2f3e0979 -H 'Accept: application/json' 'http://pbx.example.org/apis/pbx/events?limit=10&last=4'
    [{"status": "In Use", "event_type": "phone status update", "seq": 5, "status_code": 1, "phone_uuid": "9a899b91-3002-3565-9706-1bcff54589f4", "timestamp": "2012-03-22T14:23:10Z"}, {"status": "Idle", "event_type": "phone status update", "seq": 6, "status_code": 0, "phone_uuid": "9a899b91-3002-3565-9706-1bcff54589f4", "timestamp": "2012-03-22T14:23:10Z"}, {"status": "In Use", "event_type": "phone status update", "seq": 7, "status_code": 1, "phone_uuid": "9a899b91-3002-3565-9706-1bcff54589f4", "timestamp": "2012-03-22T14:23:16Z"}, {"phone_uuid": "9a899b91-3002-3565-9706-1bcff54589f4", "timestamp": "2012-03-22T14:23:19Z", "user_uuid": "ad2852c1-5509-3068-b510-f98747b430a1", "event_type": "user logged out", "seq": 8}, {"status": "Idle", "event_type": "phone status update", "seq": 9, "status_code": 0, "phone_uuid": "9a899b91-3002-3565-9706-1bcff54589f4", "timestamp": "2012-03-22T14:23:19Z"}]
    

    Fetching events (XML)

    $ curl -u apiKey:8d0a0704a96db1773fcb52db2f3e0979 -H 'Accept: application/xml' 'http://pbx.example.org/apis/pbx/events?limit=3'
    <events>
    <event>
    <event_type>phone status update</event_type>
    <phone_uuid>9a899b91-3002-3565-9706-1bcff54589f4</phone_uuid>
    <seq>7</seq>
    <status>In Use</status>
    <status_code>1</status_code>
    <timestamp>2012-03-22T14:23:16Z</timestamp>
    </event>
    <event>
    <event_type>user logged out</event_type>
    <phone_uuid>9a899b91-3002-3565-9706-1bcff54589f4</phone_uuid>
    <seq>8</seq>
    <timestamp>2012-03-22T14:23:19Z</timestamp>
    <user_uuid>ad2852c1-5509-3068-b510-f98747b430a1</user_uuid>
    </event>
    <event>
    <event_type>phone status update</event_type>
    <phone_uuid>9a899b91-3002-3565-9706-1bcff54589f4</phone_uuid>
    <seq>9</seq>
    <status>Idle</status>
    <status_code>0</status_code>
    <timestamp>2012-03-22T14:23:19Z</timestamp>
    </event>
    </events>
    $ curl -u apiKey:8d0a0704a96db1773fcb52db2f3e0979 -H 'Accept: application/xml' 'http://pbx.example.org/apis/pbx/events?limit=3&last=9'
    <events>
    </events>
    $ curl -u apiKey:8d0a0704a96db1773fcb52db2f3e0979 -H 'Accept: application/xml' 'http://pbx.example.org/apis/pbx/events?limit=3&last=9'
    <events>
    </events>
    $ curl -u apiKey:8d0a0704a96db1773fcb52db2f3e0979 -H 'Accept: application/xml' 'http://pbx.example.org/apis/pbx/events?limit=3&last=9'
    <events>
    <event>
    <event_type>phone status update</event_type>
    <phone_uuid>9a899b91-3002-3565-9706-1bcff54589f4</phone_uuid>
    <seq>10</seq>
    <status>In Use</status>
    <status_code>1</status_code>
    <timestamp>2012-03-22T14:26:31Z</timestamp>
    </event>
    </events>
    $ curl -u apiKey:8d0a0704a96db1773fcb52db2f3e0979 -H 'Accept: application/xml' 'http://pbx.example.org/apis/pbx/events?limit=3&last=10'
    <events>
    <event>
    <event_type>user logged in</event_type>
    <phone_uuid>9a899b91-3002-3565-9706-1bcff54589f4</phone_uuid>
    <seq>11</seq>
    <timestamp>2012-03-22T14:26:49Z</timestamp>
    <user_uuid>ad2852c1-5509-3068-b510-f98747b430a1</user_uuid>
    </event>
    <event>
    <event_type>phone status update</event_type>
    <phone_uuid>9a899b91-3002-3565-9706-1bcff54589f4</phone_uuid>
    <seq>12</seq>
    <status>Idle</status>
    <status_code>0</status_code>
    <timestamp>2012-03-22T14:26:49Z</timestamp>
    </event>
    </events>
    

    Fetching calls (JSON)

    $curl -u apiKey:fb1c747701f2d21c35f4c7bc1f8ffebe -H 'accept: application/json' 'http://pbx.example.org/apis/pbx/acd/stats?calls=1' 
    {"queues": [{"service_level": 0.0, "calls_waiting": 1, "available_agents": 0, "talk_time": 0, "longest_hold_time": 20, "service_level_interval": 0, "name": "niekumam", "answered": 0, "all_agents": 4, "aborted": 2, "free_agents": 0, "calls": [{"callerid_name": "FakeSip Linphone", "position": 1, "callerid_num": "123456", "wait": 20}], "hold_time": 0, "logged_in_agents": 1, "uuid": "ef382287-2c8c-32ca-a91f-b2216498fa17"}]}

    Fetching calls (XML)

    $curl -u apiKey:fb1c747701f2d21c35f4c7bc1f8ffebe -H 'accept: application/xml' 'http://pbx.example.org/apis/pbx/acd/stats.xml?calls=1'
    <acd_stats>
    <queue uuid="ef382287-2c8c-32ca-a91f-b2216498fa17" name="niekumam">
    <calls_waiting>1</calls_waiting>
    <longest_hold_time>11</longest_hold_time>
    <hold_time>0</hold_time>
    <talk_time>0</talk_time>
    <answered>0</answered>
    <aborted>2</aborted>
    <service_level interval="0">0.0</service_level>
    <all_agents>4</all_agents>
    <logged_in_agents>1</logged_in_agents>
    <available_agents>0</available_agents>
    <free_agents>0</free_agents>
    <calls>
    <call>
    <callerid_name>FakeSip Linphone</callerid_name>
    <callerid_num>123456</callerid_num>
    <position>1</position>
    <wait>11</wait>
    </call>
    </calls>
    </queue>
    </acd_stats>
    

    Fetching agents (JSON)

    $curl -u apiKey:fb1c747701f2d21c35f4c7bc1f8ffebe -H 'accept: application/json' 'http://pbx.example.org/apis/pbx/acd/stats?agents=1' 
    {"queues": [{"service_level": 0.0, "calls_waiting": 0, "available_agents": 2, "talk_time": 0, "longest_hold_time": 0, "service_level_interval": 0, "name": "niekumam", "answered": 0, "all_agents": 4, "aborted": 2, "free_agents": 2, "agents": [{"status": "Unavailable", "paused": true, "last_call": "", "name": "304", "penalty": 1, "status_code": 5, "user_uuid": "8ff48136-df77-388e-ab08-64268a221371", "calls_taken": 0}, {"status": "Unavailable", "paused": true, "last_call": "", "name": "302", "penalty": 1, "status_code": 5, "user_uuid": "52b1e37c-9184-3e7a-b8b7-eb909bef0035", "calls_taken": 0}, {"status": "Not In Use", "paused": false, "last_call": "", "name": "301", "penalty": 1, "status_code": 1, "user_uuid": "cdad7e96-fa5f-3210-8641-20ed441d491b", "calls_taken": 0}, {"status": "Not In Use", "paused": false, "last_call": "", "name": "300", "penalty": 1, "status_code": 1, "user_uuid": "a8258b12-a203-3ccb-8365-95f40bdff152", "calls_taken": 0}], "hold_time": 0, "logged_in_agents": 2, "uuid": "ef382287-2c8c-32ca-a91f-b2216498fa17"}]}

    Fetching agents (XML)

    $curl -u apiKey:fb1c747701f2d21c35f4c7bc1f8ffebe -H 'accept: application/xml' 'http://pbx.example.org/apis/pbx/acd/stats.xml?agents=1' 
    <acd_stats>
    <queue uuid="ef382287-2c8c-32ca-a91f-b2216498fa17" name="niekumam">
    <calls_waiting>1</calls_waiting>
    <longest_hold_time>1</longest_hold_time>
    <hold_time>0</hold_time>
    <talk_time>0</talk_time>
    <answered>1</answered>
    <aborted>1</aborted>
    <service_level interval="0">0.0</service_level>
    <all_agents>2</all_agents>
    <logged_in_agents>2</logged_in_agents>
    <available_agents>1</available_agents>
    <free_agents>1</free_agents>
    <agents>
    <agent>
    <calls_taken>1</calls_taken>
    <last_call>2013-12-19T11:59:15</last_call>
    <name>301</name>
    <paused>False</paused>
    <penalty>1</penalty>
    <status>Not In Use</status>
    <status_code>1</status_code>
    <user_uuid>cdad7e96-fa5f-3210-8641-20ed441d491b</user_uuid>
    </agent>
    <agent>
    <calls_taken>0</calls_taken>
    <last_call/>
    <name>300</name>
    <paused>False</paused>
    <penalty>1</penalty>
    <status>Ringing</status>
    <status_code>6</status_code>
    <user_uuid>a8258b12-a203-3ccb-8365-95f40bdff152</user_uuid>
    </agent>
    </agents>
    </queue>
    </acd_stats>
    

    Fetching call statistics for a specific queue (JSON)

    $ curl -u apiKey:fb1c747701f2d21c35f4c7bc1f8ffebe  -H 'accept: application/json' http://pbx.example.org/apis/pbx/acd/ef382287-2c8c-32ca-a91f-b2216498fa17/stats
    {"service_level": 0.0, "calls_waiting": 1, "available_agents": 2, "talk_time": 0, "longest_hold_time": 72, "service_level_interval": 0, "name": "niekumam", "answered": 0, "all_agents": 4, "aborted": 4, "free_agents": 2, "hold_time": 0, "logged_in_agents": 2, "uuid": "ef382287-2c8c-32ca-a91f-b2216498fa17"}
    

    Fetching call statistics for a specific queue (XML)

    $ curl -u apiKey:fb1c747701f2d21c35f4c7bc1f8ffebe  -H 'accept: application/xml' http://pbx.example.org/apis/pbx/acd/ef382287-2c8c-32ca-a91f-b2216498fa17/stats    
    <acd_stats>
    <queue uuid="ef382287-2c8c-32ca-a91f-b2216498fa17" name="niekumam">
    <calls_waiting>1</calls_waiting>
    <longest_hold_time>59</longest_hold_time>
    <hold_time>0</hold_time>
    <talk_time>0</talk_time>
    <answered>0</answered>
    <aborted>4</aborted>
    <service_level interval="0">0.0</service_level>
    <all_agents>4</all_agents>
    <logged_in_agents>2</logged_in_agents>
    <available_agents>1</available_agents>
    <free_agents>1</free_agents>
    </queue>
    </acd_stats>

    in API
    Did this article answer your question?

    No Comments – be the first.

    Leave a Reply