Managing Hybrid Services Licenses

The Cisco Spark API includes several methods which can be used by administrators to programmatically manage license usage of the following Cisco Spark Hybrid services:

  • Hybrid Call Aware
  • Hybrid Call Connect
  • Hybrid Exchange Calendar
  • Hybrid Google Calendar

Requirements

  • API users must be assigned the “Full Administrator” role for their organization to access license information and display information about all people within the organization.
  • API users must be assigned the “Full Administrator” role or have the spark-admin:people_write scope enabled to add licenses to users.

Licenses and Usage

All Spark licenses for an organization can be retrieved via the /licenses endpoint of the API. This will include Hybrid Services licenses if they are enabled for the particular organization.

Hybrid Services licenses will always be displayed with a total unit quantity of 1 and a consumed unit value of 0. As licenses are assigned to users, these values will not change.

License Combinations and Dependencies

Google and Exchange Calendars

Organizations may have both Hybrid Exchange Calendar and Hybrid Google Calendar licenses enabled at the organization-level. Individual users may not have both of these services enabled at the same time. Attempting to add both licenses to the same user (to enable both services for that user) will result in an API error: Cannot enable both exchange and google calendar service for the same user.

Hybrid Call Aware and Hybrid Call Connect

The Hybrid Call Connect license cannot be added to users unless they also have the Hybrid Call Aware license enabled. Attempting to add Hybrid Call Connect to a user without Hybrid Call Aware will result in an API error: Cannot enable call connect service without call aware service.

Listing Licenses

License information can be retrieved for any organization where the calling user is granted access. If no organization ID is specified in the request, the calling user’s organization will be used. Information about each license associated with the organization will be returned. See the List Licenses reference for more details.

Example

GET https://api.ciscospark.com/v1/licenses

{
  "items" : [ {
    "id" : "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMTIzNDU2NzgtOTBhYi1jZGVmLTEyMzQtNTY3ODkwYWJjZGVmOkFBXzEyMzQ1Njc4LTkwYWItY2RlZi0xMjM0LTU2Nzg5MGFiY2RlZg",
    "name" : "Messaging",
    "totalUnits" : "100",
    "consumedUnits" : "17"
  }, {
    "id" : "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMDEyMzQ1NjctODkwYS1iY2RlLWYwMTItMzQ1Njc4OTBhYmNkOkFBXzAxMjM0NTY3LTg5MGEtYmNkZS1mMDEyLTM0NTY3ODkwYWJjZA",
    "name" : "Hybrid Call Aware",
    "totalUnits" : "1",
    "consumedUnits" : "0"
  } ]
}

Cisco Spark Users (People)

Cisco Spark administrators (both full and read-only administrators) can view all people either in bulk or individually. Using the People Resource of the API, full administrators can add and remove licenses from individual users.

Licenses can be applied either when people are created or via an update to individual existing people.

Listing All Users

Full administrators for the organization can list all people within an organization to see licenses associated with each person. Query parameters allow filtering by email or name—these options are not required for administrators.

Example

GET https://api.ciscospark.com/v1/people

{
  "items" : [ {
    "id" : "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
    "emails" : [ "john.andersen@foo.com" ],
    "displayName" : "John Andersen",
    "orgId" : "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
    "licenses" : [
      "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMTIzNDU2NzgtOTBhYi1jZGVmLTEyMzQtNTY3ODkwYWJjZGVmOkFBXzEyMzQ1Njc4LTkwYWItY2RlZi0xMjM0LTU2Nzg5MGFiY2RlZg",
      "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMDEyMzQ1NjctODkwYS1iY2RlLWYwMTItMzQ1Njc4OTBhYmNkOkFBXzAxMjM0NTY3LTg5MGEtYmNkZS1mMDEyLTM0NTY3ODkwYWJjZA"
    ]
    ... extra response data omitted ...
  } ]
}

Listing Individual Users

To see which licenses are associated with individual users, use their person ID to retrieve their details, which will include the licenses associated with their account.

Example

GET https://api.ciscospark.com/v1/people/Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY

{
  "id" : "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
  "emails" : [ "john.andersen@foo.com" ],
  "displayName" : "John Andersen",
  "orgId" : "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
  "licenses" : [
    "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMTIzNDU2NzgtOTBhYi1jZGVmLTEyMzQtNTY3ODkwYWJjZGVmOkFBXzEyMzQ1Njc4LTkwYWItY2RlZi0xMjM0LTU2Nzg5MGFiY2RlZg",
    "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMDEyMzQ1NjctODkwYS1iY2RlLWYwMTItMzQ1Njc4OTBhYmNkOkFBXzAxMjM0NTY3LTg5MGEtYmNkZS1mMDEyLTM0NTY3ODkwYWJjZA"
  ]
  ... extra response data omitted ...
}

This user has both Messaging (Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMTIzNDU2NzgtOTBhYi1jZGVmLTEyMzQtNTY3ODkwYWJjZGVmOkFBXzEyMzQ1Njc4LTkwYWItY2RlZi0xMjM0LTU2Nzg5MGFiY2RlZg) and the Hybrid Call Aware licenses (Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMDEyMzQ1NjctODkwYS1iY2RlLWYwMTItMzQ1Njc4OTBhYmNkOkFBXzAxMjM0NTY3LTg5MGEtYmNkZS1mMDEyLTM0NTY3ODkwYWJjZA) enabled.

Creating Cisco Spark Users

When creating Cisco Spark users, licenses which will be enabled for the new user can be included in the request. Include specific Hybrid Services licenses to enable those services for the new user. Be sure to use the license IDs retrieved from /licenses as described earlier in this document—license IDs will be different from the examples here and between different organizations. See the Create People reference for more details about how to create people.

Example

POST https://api.ciscospark.com/v1/people

Example Request Body

{
  "emails" : [ "john.andersen@foo.com" ],
  "displayName" : "John Andersen",
  "firstName" : "John",
  "lastName" : "Andersen",
  "avatar" : "URL",
  "orgId" : "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
  "roles" : [ "RoleID1", "RoleID2" ],
  "licenses" : [
    "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMTIzNDU2NzgtOTBhYi1jZGVmLTEyMzQtNTY3ODkwYWJjZGVmOkFBXzEyMzQ1Njc4LTkwYWItY2RlZi0xMjM0LTU2Nzg5MGFiY2RlZg",
    "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMDEyMzQ1NjctODkwYS1iY2RlLWYwMTItMzQ1Njc4OTBhYmNkOkFBXzAxMjM0NTY3LTg5MGEtYmNkZS1mMDEyLTM0NTY3ODkwYWJjZA"
    ]
}

This user will be granted Messaging and Hybrid Call Aware licenses.

Example Response

{
  "id" : "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY"
  "emails" : [ "john.andersen@foo.com" ],
  "displayName" : "John Andersen",
  "firstName" : "John",
  "lastName" : "Andersen",
  "avatar" : "URL",
  "orgId" : "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
  "roles" : [ "RoleID1", "RoleID2" ],
  "licenses" : [
    "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMTIzNDU2NzgtOTBhYi1jZGVmLTEyMzQtNTY3ODkwYWJjZGVmOkFBXzEyMzQ1Njc4LTkwYWItY2RlZi0xMjM0LTU2Nzg5MGFiY2RlZg",
    "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMDEyMzQ1NjctODkwYS1iY2RlLWYwMTItMzQ1Njc4OTBhYmNkOkFBXzAxMjM0NTY3LTg5MGEtYmNkZS1mMDEyLTM0NTY3ODkwYWJjZA"
    ]
  "created" : "2015-10-18T14:26:16+00:00",
  "timezone" : "America/Denver",
  "lastActivity" : "2015-10-18T14:26:16+00:00",
}

Updating Cisco Spark Users

To add to or remove licenses from an existing person, update their record with the new license IDs. Include all attributes for the person (as described in the Update People reference), specifically including only the licenses which should be enabled for the person.

If the person is currently assigned a license which is not included in the update request it will be unassigned from that person. Be sure to include all other details for the person, as the PUT operation expects all user details to be present in the request. It is common to first GET the person details, make changes, and then PUT those changes to ensure the other information is accurate.

Use the license IDs retrieved from /licenses as described earlier—license IDs will be different from the examples here and between different organizations.

Example

PUT https://api.ciscospark.com/v1/people/Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY

Example Request Body

{
  "emails" : [ "john.andersen@foo.com" ],
  "displayName" : "John Andersen",
  "firstName" : "John",
  "lastName" : "Andersen",
  "avatar" : "URL",
  "orgId" : "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
  "roles" : [ "RoleID1", "RoleID2" ],
  "licenses" : [
    "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMTIzNDU2NzgtOTBhYi1jZGVmLTEyMzQtNTY3ODkwYWJjZGVmOkFBXzEyMzQ1Njc4LTkwYWItY2RlZi0xMjM0LTU2Nzg5MGFiY2RlZg",
    "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMDEyMzQ1NjctODkwYS1iY2RlLWYwMTItMzQ1Njc4OTBhYmNkOkFBXzAxMjM0NTY3LTg5MGEtYmNkZS1mMDEyLTM0NTY3ODkwYWJjZA"
    ]
}

Example Response

{
  "id" : "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY"
  "emails" : [ "john.andersen@foo.com" ],
  "displayName" : "John Andersen",
  "firstName" : "John",
  "lastName" : "Andersen",
  "avatar" : "URL",
  "orgId" : "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
  "roles" : [ "RoleID1", "RoleID2" ],
  "licenses" : [
    "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMTIzNDU2NzgtOTBhYi1jZGVmLTEyMzQtNTY3ODkwYWJjZGVmOkFBXzEyMzQ1Njc4LTkwYWItY2RlZi0xMjM0LTU2Nzg5MGFiY2RlZg",
    "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMDEyMzQ1NjctODkwYS1iY2RlLWYwMTItMzQ1Njc4OTBhYmNkOkFBXzAxMjM0NTY3LTg5MGEtYmNkZS1mMDEyLTM0NTY3ODkwYWJjZA"
    ]
  "created" : "2015-10-18T14:26:16+00:00",
  "timezone" : "America/Denver",
  "lastActivity" : "2015-10-18T14:26:16+00:00",
}