Api >

Service Portal REST API

GET /api/customers/{identifier}/devices

GET returns all Customer's Devices
Given I am authenticated as K0002
  • there is a Base Device Type with name base
    and there is Base Device with external identifier 00123
  • there is a Extended Base Device Type with name extended_base
    and there is Extended Base Device with external identifier 00777
  • and there is a XCAPI Device with ID xcapi123
  • and there is an UnprovisionedSip Device Type with name unprovisioned_sip
    and there is a Unprovisioned Sip Device with ID device123
  • and there is a Phone Extension with extension number 17
    and there is a Trunk with numbers +48 (22) 33-65
    and there is an Inbound Trunk Number with extension 33
    and it is assigned to phone extension
    and there is a Lync Option with id 134
    and there is a Lync Softphone Device attached
  • and there is a Standard Device Type with name standard
    and there is a Standard Device with ID 123456789abc
  • and there is a Handset Device Type with name handset
    and there is a Handset Device with ID ABCDEF012345-Port0
  • and there is a Operator Panel Device Type with name operator
    and there is a Operator Panel Device with ID operatorDevice
  • and there is a Media Gateway Device with ID 123AAAAAAAAA
When I send /api/customers/K0002/devices
Then I should receive HTTP/1.1 200 OK with following body: 
{
  "href": "/api/customers/K0002/devices?_offset=0&_pagesize=16",
  "offset": 0,
  "total": 9,
  "size": 9,
  "links": [{
    "rel": "availableNpanelPhones",
    "href": "/api/customers/K0002/devices/operator-panel/available-phones"
  }],
  "items": [{
    "href": "/api/customers/K0002/devices/base/00123"
  }, {
    "href": "/api/customers/K0002/devices/base/00777"
  }, {
    "href": "/api/customers/K0002/devices/xcapi/xcapi123"
  }, {
    "href": "/api/customers/K0002/devices/unprovisioned-sip/device123"
  }, {
    "href": "/api/customers/K0002/devices/lync/1-48223333"
  }, {
    "href": "/api/customers/K0002/devices/standard/123456789abc"
  }, {
    "href": "/api/customers/K0002/devices/base/ABCDEF012345/handsets/Port0"
  }, {
    "href": "/api/customers/K0002/devices/operator-panel/operatorDevice"
  }, {
    "href": "/api/customers/K0002/devices/media-gateway/123AAAAAAAAA"
  }]
}
GET retrieves items with useful data
Given I am authenticated as Customer K0002
and there is a Standard Device Type with name standard
and there is a Standard Device with ID 123456789abc
and there is a Phone Extension with extension number 17
which is attached to Phone Extension 17
which has been created at 2015-10-12 04:25 and deactivated at 2015-10-24 19:03
with SIP Username K00020A08F and SIP Secret kSIzxm76EE2
When I send /api/customers/K0002/devices
Then I should receive HTTP/1.1 200 OK with following body: 
{
  "href": "/api/customers/K0002/devices?_offset=0&_pagesize=16",
  "offset": 0,
  "total": 1,
  "size": 1,
  "links": [{
    "rel": "availableNpanelPhones",
    "href": "/api/customers/K0002/devices/operator-panel/available-phones"
  }],
  "items": [{
    "href": "/api/customers/K0002/devices/standard/123456789abc",
    "links": [],
    "data": [{
      "name": "deviceType",
      "value": "standard"
    }, {
      "name": "deviceId",
      "value": "123456789abc"
    }, {
      "name": "uniqueIdentifier",
      "value": "123456789abc"
    }, {
      "name": "extension",
      "value": "17"
    }, {
      "name": "created",
      "value": "2015-10-12 04:25"
    }, {
      "name": "active",
      "value": false
    }, {
      "name": "deactivated",
      "value": "2015-10-24 19:03"
    }, {
      "name": "deviceMasterCategory",
      "value": "STANDARD"
    }, {
      "name": "deviceCategory",
      "value": "category"
    }, {
      "name": "masterCategory",
      "value": "STANDARD"
    }, {
      "name": "category",
      "value": "category"
    }, {
      "name": "site",
      "value": "Dummy site K0002"
    }, {
      "name": "siteName",
      "value": "Dummy site K0002"
    }, {
      "name": "siteStreet",
      "value": ""
    }, {
      "name": "siteZip",
      "value": ""
    }, {
      "name": "siteCity",
      "value": ""
    }, {
      "name": "siteState",
      "value": null
    }, {
      "name": "siteCountry",
      "value": ""
    }, {
      "name": "siteSalesForceId",
      "value": "1"
    }, {
      "name": "note",
      "value": null
    }]
  }]
}
GET returns filtered Customer's Devices
Filtering is done on fields :
  • deviceType
  • deviceId
  • extension
  • site
  • deviceMasterCategory
Given I am authenticated as K0002
  • there is a Base Device Type with name base
    and there is Base Device with external identifier ABCDEF012345 which has been created at 2015-10-12 04:25
  • and there is a Standard Device Type with name standard
    and there is a Standard Device with ID 999999999999
  • and there is a XCAPI Device with ID ABC888888888 which has been created at 2015-10-12 04:25
When I send /api/customers/K0002/devices?_q=abC
Then I should receive HTTP/1.1 200 OK with following body: 
{
  "href": "/api/customers/K0002/devices?_offset=0&_pagesize=16&_q=abC",
  "offset": 0,
  "total": 2,
  "size": 2,
  "links": [{
    "rel": "availableNpanelPhones",
    "href": "/api/customers/K0002/devices/operator-panel/available-phones"
  }],
  "items": [{
    "href": "/api/customers/K0002/devices/base/ABCDEF012345",
    "links": [],
    "data": [{
      "name": "deviceType",
      "value": "base"
    }, {
      "name": "deviceId",
      "value": "ABCDEF012345"
    }, {
      "name": "extension",
      "value": null
    }, {
      "name": "created",
      "value": "2015-10-12 04:25"
    }, {
      "name": "active",
      "value": true
    }, {
      "name": "site",
      "value": "Dummy site K0002"
    }, {
      "name": "deviceMasterCategory",
      "value": "BASE"
    }]
  }, {
    "href": "/api/customers/K0002/devices/xcapi/ABC888888888",
    "links": [],
    "data": [{
      "name": "deviceType",
      "value": "XCAPI"
    }, {
      "name": "deviceId",
      "value": "ABC888888888"
    }, {
      "name": "extension",
      "value": null
    }, {
      "name": "created",
      "value": "2015-10-12 04:25"
    }, {
      "name": "active",
      "value": true
    }, {
      "name": "site",
      "value": "Dummy site K0002"
    }, {
      "name": "deviceMasterCategory",
      "value": "UNPROVISIONED_SIP"
    }]
  }]
}
System integrator can see sipUsername
Given I am authenticated as System Integrator S0002
and there is a Standard Device Type with name standard
and there is a Standard Device with ID 123456789abc
with SIP Username K00020A08F When I send /api/customers/K0002/devices
Then I should receive HTTP/1.1 200 OK with following body: 
{
  "items": [{
    "href": "/api/customers/K0002/devices/standard/123456789abc",
    "data": [{
      "name": "sipUsername",
      "value": "K00020A08F"
    }]
  }]
}
Operator can see sipSecret
Given I am authenticated as Operator C0002
and there is a Standard Device Type with name standard
and there is a Standard Device with ID 123456789abc
and SIP Secret kSIzxm76EE2
When I send /api/customers/K0002/devices
Then I should receive HTTP/1.1 200 OK with following body: 
{
  "items": [{
    "href": "/api/customers/K0002/devices/standard/123456789abc",
    "data": [{
      "name": "sipSecret",
      "value": "kSIzxm76EE2"
    }]
  }]
}
Cannot GET Device for missing Customer
Given I am authenticated as Admin
When I send /api/customers/K0404/devices/00123
Then I should receive HTTP/1.1 404 Not Found
with following body: 
{
  "described_by": "http://api.nfon.net/probs/customer-not-found",
  "title": "Customer not found",
  "detail": "Customer with identifier K0404 has not been found"
}
Cannot GET Devices of another Customer
Given and there is activated Device with external identifier 00123
Given I am authenticated as customer K0003
When I send /api/customers/K0002/devices/00123
Then I should receive HTTP/1.1 403 Forbidden
with following body: 
{
  "title": "Access forbidden",
  "detail": "Access denied to [Customer] with id [K0002]",
  "described_by": "http://api.nfon.net/probs/invalid-authorization"
}
System Integrator cannot access Devices of Customer that does not belong to him
Given I am authenticated as System Integrator S0002
When I send /api/customers/K0003/devices
Then I should receive HTTP/1.1 403 Forbidden
with following body 
{
  "title": "Access forbidden",
  "detail": "Access denied to [Customer] with id [K0003]",
  "described_by": "http://api.nfon.net/probs/invalid-authorization"
}
Operator cannot access Devices of Customer that does not belong to him
Given I am authenticated as Operator C0002
When I send /api/customers/K0003/devices
Then I should receive HTTP/1.1 403 Forbidden
with following body 
{
  "title": "Access forbidden",
  "detail": "Access denied to [Customer] with id [K0003]",
  "described_by": "http://api.nfon.net/probs/invalid-authorization"
}
Results generated by Concordion
in 1657 ms on 25-Feb-2026 at 00:41:02 CET