Request Parameters

This topic discusses the request parameters for the Web Services API Reference.

Object Fields

When making "list" requests for any kind of object, Web Services returns a list of the corresponding object URI's.

For example:

Request:

 GET .../api/v2/me/devices
  

Response:

 { "statusCode" : 0,
  "uris" : [ "http://127.0.0.1:8080/api/v2/devices/ba0f987f-15b4-42c7-bed0-5f302259f9db" ]
}
  

In order to receive a list of objects with their actual fields, you will need to provide the fields request parameter, and have it set either to *, or to a list of data fields of interest.

For example:

Request:

GET .../api/v2/me/devices?fields=*
 

Response:

{ "devices" : [ { "capabilities" : [ "ForwardCallsOn",
            "DoNotDisturbOn"
          ],
        "deviceState" : "Active",
        "doNotDisturb" : "Off",
        "e164Number" : "5001",
        "id" : "ba0f987f-15b4-42c7-bed0-5f302259f9db",
        "phoneNumber" : "5001",
        "telephonyNetwork" : "Private",
        "userState" : { "displayName" : "Ready",
            "id" : "9430250E-0A1B-421F-B372-F29E69366DED",
            "state" : "Ready"
          },
        "voiceEnvironmentUri" : "http://127.0.0.1:8080/api/v2/voice-environments/a481cd8e-7b6a-4466-af88-db3471ac909e"
      } ],
  "statusCode" : 0
}
 

Subresources

The subresources feature allows you to read subresources of an object together with the object itself. For example, if you have a user object that has one or more skills and one or more devices, and you want to read all of those in one request, you need to do the following:

Request:

GET .../api/v2/users/<user_id>?subresources=*
 

Response:

{
	"id":<user_id>,
	"firstName":<first_name>,
	...
	"skills":[{
		"id":<skill_1_id>,
		...
	},
	...
	{
		"id":<skill_N_id>,
		...
	}],
	"devices":[{
		"id":<device_1_id>,
		...
	},
	...
	{
		"id":<device_M_id>,
		...
	}]
}
 

In comparison, if you do not include the subresources parameter in the request, you will get everything except the "skills" collection and "devices" collection.

Important

It is also possible to apply the subresources feature to object settings and request both an object and its settings in one request.

Selecting Subresources

In the example above, "subresources=*" was specified in order to get all available subresources. If the object you are interested in has several types of subresources, it is possible to choose whether you want all subresources to be returned or just some of them. This can be achieved by specifying a comma-separated list of subresources.

For example:

Example 1

Request:

GET .../api/v2/users/<user_id>?subresources=skills,devices
 

Response:

{
	"id":<user_id>,
	"firstName":<first_name>,
	...
	"skills":[{
		"id":<skill_1_id>,
		...
	},
	...
	{
		"id":<skill_N_id>,
		...
	}],
	"devices":[{
		"id":<device_1_id>,
		...
	},
	...
	{
		"id":<device_M_id>,
		...
	}]
}
 

Example 2

Request:

GET .../api/v2/users/<user_id>?subresources=skills
 

Response:

{
	"id":<user_id>,
	"firstName":<first_name>,
	...
	"skills":[{
		"id":<skill_1_id>,
		...
	},
	...
	{
		"id":<skill_N_id>,
		...
	}]
}
 

User Authentication

Basic HTTP Authentication is used. Please see RFC 2617 Section 2 for reference.

Supported Requests

Important

Note that this is a Reference Guide for Pre-Release software. Therefore, some attributes and operations might not yet be supported for all resources. Some are marked throughout the document, but it is possible some were missed.

The following requests are supported at this time:

• /devices: fields=*
• /features: fields=*
• /me: subresources=*
• /me/calls: fields=*
• /me/devices: fields=*
• /me/skils: fields=*
• /skills: fields=*
• /system/features: fields=*
• /system/routing-templates: channel, version (these are query parameters), fields=*
• /users: fields=*, subresources=*
• /users/{id}: subresources=*
• /users/{id}/devices: fields=*
• /recordings: startTime, endTime, callerPhoneNumber, dialedPhoneNumber, userName, offset, limit (query parameters)