Recording Label API

Overview

Use this API to create and manage label definitions, and to apply those label definitions to recordings. A label definition defines a label, which can then be applied to a recording. For example, a label definition could be created to mark a recording for further review.

Access this API and its Operations at the base path /api/v2. For example:
http://localhost:8080/api/v2/recording-label-definitions

Prerequisites

Configure the Elasticsearch schema v2 to enable support for labels and non-deletion features. For existing deployments, follow the migration steps here: Migrating an Existing Elasticsearch Deployment to Schema V2. New deployments after GIR version 8.5.214.02 will have Elasticsearch schema v2 enabled by default.

Configure the SpeechMiner Settings for Interaction Recording Web Services.

Roles and Permissions

To access the below listed APIs, the user must be assigned to one of the required roles as mentioned in the specifications. For details, see Configuring Roles for Recording Users. The Genesys Interaction Recording API uses Basic HTTP Authentication. See RFC 2617 Section 2 for reference.
Specific permissions support your ability to create and administer label definitions, and to set and remove labels from recordings. See: Configuring Permissions for Recording Labels.

Creating a label definition

Request URL	/recording-label-definitions/
HTTP Method	POST
Required Roles	Administrator	Supervisor Agent
Required Permissions	N/A	RECORDING_PERMISSION_ADD_LABEL_DEFINITION

Payload
Attributes	JSON Data Type	Mandatory	Possible Values	Default Value	Description	Notes
name	String	Yes		N/A	The name of the label definition.	Is case-insensitive. Must only contain ASCII characters. Must not include space. Must be unique among other label definitions. Must not start with two underscores("__") as it is reserved.
displayName	String	No		Defaults to the value of name.	The display name of the label definition.	Must be unique among other label definitions.
description	String	No		Empty string	The description of the label definition.

Response

HTTP Status
Status Codes	Situations
201 CREATED	The label definition was created successfully.
400 BAD REQUEST	Bad request received.
403 FORBIDDEN	Forbidden to create the label definition.
409 CONFLICT	The label definition was not created as one with the same name exists already.

Payload
Attributes	JSON Data Type	Mandatory	Possible Values	Default Value	Situations	Notes
statusCode	Integer	Yes	0	N/A	Label definition was created.
			1 (RequiredParameterMissing)		The required payload attributes are missing.
			2 (InvalidRequestParameter)		The constraints of payload attributes are not met.
			3 (OperationForbidden)		The requesting user does not have the permissions required or is attempting to create with reserved name.
			18 (ResourceAlreadyExists)		A label definition with the same name exists already.
			20 (unauthenticated)		The requesting user is not properly authenticated or using a non-ops API as an ops user.
statusMessage	String	No	Not specified. A message providing information.	N/A		The statusMessage will provide more information about a failure if statusCode is not 0.
labelDefinition	JSON object	No	JSON object containing the label definition. path (string): The path to the resource. name (string): The name of the label definition. displayName (string, optional): The display name of the label definition. description (string, optional): The description of the label definition.	N/A	The newly created label definition or existing one in case of an attempt to create an already existing one.

Example Request

POST /recording-label-definitions/
{
        "name": "SomeLabelDefinition",
        "displayName": "New Label Definition",
        "description": "A new label definition"
 }

Example Responses

{
	"statusCode": 0,
	"labelDefinition": {
		"path": "/recording-label-definitions/2365adc7-67bb-448e-b32d-04731faa9231",
		"name": "SomeLabelDefinition",
		"displayName": "New Label Definition",
		"description": "A new label definition"
	}
}
{
	"statusCode": 2,
	"statusMessage": "Invalid value specified."
}
{
	"statusCode": 3,
	"statusMessage": "This operation is not allowed."
}
{
	"statusCode": 18,
	"statusMessage": "Resource exists already."
	"labelDefinition": {
		"path": "/recording-label-definitions/a6a6f1d9-788a-47b4-bdeb-80b3d598cfa6",
		"name": "ExistingLabelDefinition",
		"displayName": "Existing Label Definition."
		"description": "An existing label definition"
	}
}

Updating a label definition

Request URL	/recording-label-definitions/<labelDefinitionId>
HTTP Method	PUT
Required Roles	Administrator	Supervisor Agent
Required Permissions	N/A	RECORDING_PERMISSION_ADD_LABEL_DEFINITION

Note: You can use the path attribute from the response returned by the GET or POST operations for label definition.

Payload
Attributes	JSON Data Type	Mandatory	Possible Values	Default Value	Description	Notes
name	String	Yes		N/A	The name of the label definition.	Name cannot be updated—must be specified to the same value as the existing name.
displayName	String	No		Default to the value of name if not specified.	The display name of the label definition.	Must be unique among other label definitions.
description	String	No		Empty string	The description of the label definition.

Response

HTTP Status
Status Codes	Situations
200 OK	The label definition was updated successfully.
400 BAD REQUEST	Bad request received.
403 FORBIDDEN	Forbidden to update the label definition.
404 NOT FOUND	Cannot find the label definition to update.

Payload
Attributes	JSON Data Type	Mandatory	Possible Values	Default Value	Situations	Notes
statusCode	Integer	Yes	0	N/A	Label definition was updated.
			1 (RequiredParameterMissing)		The required payload attributes are missing.
			2 (InvalidRequestParameter)		The constraints of payload attributes are not met.
			3 (OperationForbidden)		The requesting user does not have the permissions required or is attempting to update with different name.
			6 (ResourceNotFound)		The specified label definition cannot be found.
			20 (Unauthenticated)		The requesting user is not properly authenticated or using a non-ops API as an ops user.
statusMessage	String	No	Not specified. A message providing information.	N/A		The statusMessage will provide more information about a failure if statusCode is not 0.
labelDefinition	JSON object	Yes	name (string): The name of the label definition. displayName (string, optional): The display name of the label definition. description (string, optional): The description of the label definition. path (string, optional): The path of the label definition. Must be unique among other label definitions.	N/A

Example Request

PUT /recording-label-definitions/{labelDefinitionId}
{
        "name": "SomeLabelDefinition",
        "displayName": "New Label Definition",
        "description": "A new label definition"
 }

Example Responses

{
	"statusCode": 0,
	"labelDefinition": {
		"path": "/recording-label-definitions/2365adc7-67bb-448e-b32d-04731faa9231",
		"name": "SomeLabelDefinition",
		"displayName": "Updated Label Definition",
		"description": "An updated label definition"
	}
}
 
{
	"statusCode": 2,
	"statusMessage": "Invalid value specified."
}
 
{
	"statusCode": 3,
	"statusMessage": "This operation is not allowed."
}
 
{
	"statusCode": 6,
	"statusMessage": "Custom label definition cannot be found."
}

{
	"statusCode": 20,
	"statusMessage": "Access denied."
}

Deleting a label definition

Request URL	/recording-label-definitions/{labelDefinitionId}
HTTP Method	DELETE
Required Roles	Administrator	Supervisor Agent
Required Permissions	N/A	RECORDING_PERMISSION_DELETE_LABEL_DEFINITION

Note: You can use the path attribute from the response returned by the GET or POST operations for label definition.

Response

HTTP Status
Status Codes	Situations	Notes
200 OK	The label definition was deleted successfully.
403 FORBIDDEN	Forbidden to delete the label definition.
404 NOT FOUND	Cannot find the label definition to delete.

Payload
Attributes	JSON Data Type	Mandatory	Possible Values	Default Value	Situations	Notes
statusCode	Integer	Yes	0	N/A	The label definition was deleted.
			3 (OperationForbidden)		The requesting user does not have the permissions required.
			6 (ResourceNotFound)		The specified label definition cannot be found.
			20 (Unauthorized)		The requesting user is ops.
statusMessage	String	No	Not specified. A message providing information.	N/A		The statusMessage will provide more information about a failure if statusCode is not 0.

Example Responses

{
	"statusCode": 0
}
 
{
	"statusCode": 3,
	"statusMessage": "This operation is not allowed."
}
 
{
	"statusCode": 5,
	"statusMessage": "Access denied."
}
 
{
	"statusCode": 6,
	"statusMessage": "Custom label definition cannot be found."
}

Retrieving label definitions

Request URL	/recording-label-definitions
HTTP Method	GET
Required Roles	Administrator	Supervisor Agent
Required Permissions	N/A	N/A

Note: Returns all the label definitions.

Parameters
Attributes	JSON Data Type	Mandatory	Possible Values	Default Value	Description	Notes
type	Comma-separated string of label definition types.	No	Reserved Custom	N/A	The type of label definition to return.	If the type is not specified, the Reserved and Custom label definitions are returned. If type is empty ("?type="), the Reserved and Custom label definitions are returned. If type contains a valid value, only the type of label definition that was specified is returned.
fields	Comma-separated string of fields.	No	name displayName description *	N/A	The fields to be returned from the label definition. Path is always returned. Use "*" to return all fields.	If fields is not specified, the path and name will be returned. If fields is empty("?fields="), the path is returned. If fields contains a valid value, the path and the specified fields are returned.

Response

HTTP Status	Fields	Possible Values	Situations
200 OK	statusCode	0 (Ok)	Retrieval of all label definitions succeeded.
		7 (PartialResponse)	Retrieval of some label definitions failed.
		12 (UnableToRetrieveResource)	Retrieval of all label definitions failed.
	labelDefinitions	An array of label definitions.	Always

Label definition response data

Fields	Description
path	The path of the label definition.
name	The name of the label definition.
type	The type of the label definition.
displayName	The display name of the label definition.
description	The description of the label definition.

Example

GET /recording-label-definitions
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c",
      "name": "__evaluated"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550b",
      "name": "importantTag"
    }
  ]
}
 
GET /recording-label-definitions?fields=
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B"
    }
  ]
}

GET /recording-label-definitions?fields=*
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c",
      "name": "__evaluated",
      "type": "Reserved",
      "displayName": "Evaluated",
      "description": "A label indicating the interaction on which it is applied has been evaluated."
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment",
      "type": "Custom",
      "displayName": "Comment",
      "description": "A label for recording comment."
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B",
      "name": "importantTag",
      "type": "Custom",
      "displayName": "Important",
      "description": "A label to tag recordings that are important."
    }
  ]
}
 
GET /recording-label-definitions?fields=name,displayName
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c",
      "name": "__evaluated",
      "displayName": "Evaluated"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment",
      "displayName": "Comment"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B",
      "name": "importantTag",
      "displayName": "Important"
    }
  ]
}
 
GET /recording-label-definitions?fields=*&type=Custom
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment",
      "type": "Custom",
      "displayName": "Comment",
      "description": "A label for recording comment."
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B",
      "name": "importantTag",
      "type": "Custom",
      "displayName": "Important",
      "description": "A label to tag recordings that are important."
    }
  ]
}
 
GET /recording-label-definitions?type=Reserved
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c",
      "name": "__evaluated"
    }
  ]
}

Adding a label to a recording

Request URL	/recordings/<recid>/labels
HTTP Method	POST
Required Roles	Administrator	Supervisor Agent
Required Permissions	N/A	RECORDING_PERMISSION_ADD_LABEL

Payload
Properties	Type	Mandatory	Default Values	Description
name	String	Yes	N/A	The name of the label definition to be added to the recording.
content	JSON Object	No	empty	The content associated with the label to be added to the recording. This is a free-form JSON element that accepts valid JSON types.

Response

HTTP Status
Status Codes	Situations
201 CREATED	The label has been added to the recording successfully.
403 FORBIDDEN	The recording requested can be found, but the label cannot be added to it for some reason (for example, region not matched, requesting user cannot access the recording). The recording requested cannot be found. There already exists a label instance that is identical to the one to add on the same recording. The label definition name cannot be found.

Payload
Fields	Type	Mandatory	Possible Values	Situations	Notes
statusCode	Integer	Yes	0 (Ok)	The label was added to the requested recording successfully.
			13 (UnableToCreateResource)	Label failed to be added to the requested recording.
			18 (ResourceAlreadyExists)	There already exists a label instance that is identical to the one to add on the same recording.
statusMessage	String	No	Not specified. A message providing information.		The statusMessage will provide more information about a failure if statusCode is not 0.
id	String	No	ID of the created label.	HTTP status is 201.
path	String	No	Path of the created label.	HTTP status is 201.

Example Requests

POST /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels 
{ 
   "name" :  "comment" , 
   "content" : { 
     "time" :  "2017-01-01T15:07:17Z" , 
     "text" :  "This is an awesome comment!" 
   } 
} 
   
POST /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels 
{ 
   "name" :  "importantTag" 
} 
   
POST /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels 
{ 
   "name" :  "comment" , 
   "content" : { 
     "time" :  "2017-08-05T15:07:17Z" , 
     "rating" :  "excellent" , 
     "by" : { 
       "userName" :  "supervisor_1" , 
       "firstName" :  "super" , 
       "lastName" :  "visor" 
     } 
   } 
}

Example Responses

201 CREATED
{
  "statusCode": 0,
  "id": "8c9a634f-343d-49b3-8322-b571be520b31",
  "path": "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31"
}
  
 
403 FORBIDDEN
{
  "statusCode": 13,
  "statusMessage": "Cannot add label to recording."
}

Adding a label to multiple recordings

Request URL	/recording-labels
HTTP Method	POST
Required Roles	Administrator	Supervisor Agent
Required Permissions	N/A	RECORDING_PERMISSION_ADD_LABEL

Payload
Level-0 Properties	Level-1 Properties	Type	Mandatory	Default Values	Description
recordingIds	N/A	JSON Array	Yes	N/A	The list of recording IDs that the label needs to be added to.
label	name	String	Yes	N/A	The name of the label definition to be added to the recordings.
label	content	JSON Object	No	empty	The content associated with the label to be added to the recordings. This is a free-form JSON element that accepts valid JSON types.

Response

HTTP Status	Situations
200 OK	The requested list of recordings is empty.
201 CREATED	The label has been added to all the requested recordings successfully and at least one label resource has been created.
207 MULTI-STATUS	The label failed to be added to some but not all of the requested recordings, but succeeded for the rest.
403 FORBIDDEN	The label failed to be added to all of the requested recordings.

Payload
Fields	Type	Mandatory	Possible Values	Situations	Notes
statusCode	Integer	Yes	0 (Ok)	The label is added to all the requested recordings successfully.
			7 (PartialResponse)	The label succeeded on some of the requested recordings, but failed on the rest.
			13 (UnableToCreateResource)	The label failed to be added to all the requested recordings.
statusMessage	String	No	Not specified. A message providing information.		The statusMessage will provide more information about a failure if statusCode is not 0.
succeeded	JSON Array	Yes	The recording id to created label URI mapping for the recordings to which label has been successfully added.	It will always be displayed in the response but can be empty.
failed	JSON Array	Yes	A list of blocks that describes the failures.	It will always be displayed in the response but can be empty.

Example Requests

POST /recording-labels 
{ 
   "recordingIds" : [ 
     "bf697521-3ffc-46f1-b840-f7230e940df3" , 
     "76705af9-65d4-46a4-af84-e984ef09ec5d" 
   ], 
   "label" : { 
     "name" :  "comment" , 
     "content" : { 
       "time" :  "2017-08-05T15:07:17Z" , 
       "text" :  "This is an awesome comment!" 
     } 
   } 
} 
   
POST /recording-labels 
{ 
   "recordingIds" : [ 
     "bf697521-3ffc-46f1-b840-f7230e940df3" , 
     "76705af9-65d4-46a4-af84-e984ef09ec5d" 
   ], 
   "label" : { 
     "name" :  "importantTag" 
   } 
} 
   
POST /recording-labels 
{ 
   "recordingIds" : [ 
     "bf697521-3ffc-46f1-b840-f7230e940df3" , 
     "76705af9-65d4-46a4-af84-e984ef09ec5d" 
   ], 
   "label" : { 
     "name" :  "comment" , 
     "content" : { 
       "time" :  "2017-08-05T15:07:17Z" , 
       "rating" :  "excellent" , 
       "by" : { 
         "userName" :  "supervisor_1" , 
         "firstName" :  "super" , 
         "lastName" :  "visor" 
       } 
     } 
   } 
}

Example Responses

200 OK
{
  "statusCode": 0,
  "succeeded": [],
  "failed": []
}
  
201 CREATED
{
  "statusCode": 0,
  "succeeded": [
    {
      "recordingId": "bf697521-3ffc-46f1-b840-f7230e940df3",
      "id": "8c9a634f-343d-49b3-8322-b571be520b31",
      "path": "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31"
    },
    {
      "recordingId": "76705af9-65d4-46a4-af84-e984ef09ec5d",
      "id": "1574da8d-ed8d-419d-b2e7-f00c1dabe0dc",
      "path": "/recordings/76705af9-65d4-46a4-af84-e984ef09ec5d/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc"
    }
  ],
  "failed": []
}
 
207 MULTI-STATUS
{
  "statusCode": 7,
  "statusMessage": "Add of label failed on some recordings.",
  "succeeded": [
    {
      "recordingId": "bf697521-3ffc-46f1-b840-f7230e940df3",
      "id": "8c9a634f-343d-49b3-8322-b571be520b31",
      "path": "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31"
    }
  ],
  "failed": [
    {
      "recordingId": "76705af9-65d4-46a4-af84-e984ef09ec5d",
      "statusCode": 13,
      "statusMessage": "Cannot add label."
    },
    {
      "recordingId": "d0464cf3-f81f-49b5-bc0e-bd166161d756",
      "statusCode": 13,
      "statusMessage": "Internal error."
    }
  ]
}
 
403 FORBIDDEN
{
  "statusCode": 13,
  "statusMessage": "Add of label failed on all the recordings.",
  "succeeded": [],
  "failed": [
    {
      "recordingId": "d0464cf3-f81f-49b5-bc0e-bd166161d756",
      "statusCode": 13,
      "statusMessage": "Cannot add label."
    }
  ]
}

Updating a label on a recording

Request URL	/recordings/<recid>/labels/<id>
HTTP Method	PUT
Required Roles	Administrator	Supervisor Agent
Required Permissions	N/A	RECORDING_PERMISSION_ADD_LABEL

Payload
Properties	Type	Mandatory	Default Values	Description
content	JSON Object	No	empty	The content associated with the label to be updated to the recording. This is a JSON object which can be customized depending on the application. The examples below show a possible use case of adding user comments on a recording.

Effect

When a label is updated:

The content of the label is updated to the one that is specified in the payload.
The field createTime is updated to the time when the update action was performed.
The field createUser is updated to the username of the user who requested the update.

Response

HTTP Status
Status Codes	Situations
200 OK	The requested label has been updated successfully.
403 FORBIDDEN	The recording requested can be found but the label cannot be updated to it for whatever reason (for example, region not matched, requesting user cannot access the recording). The recording requested cannot be found.
404 NOT FOUND	The requested label cannot be found.

Payload
Fields	Type	Mandatory	Possible Values	Situations	Notes
statusCode	Integer	Yes	0 (Ok)	The label has been updated to the requested recording successfully.
			6 (ResourceNotFound)	The label cannot be found.
			15 (UnableToUpdateResource)	The recording requested can be found but the label cannot be updated to it for whatever reason (for example, region not matched, requesting user cannot access the recording). The recording requested cannot be found.
statusMessage	String	No	Not specified. A message providing information.		The statusMessage will provide more information about a failure if statusCode is not 0.

Example Requests

PUT /recordings/<labels> 
{ 
   "content" : { 
     "time" :  "2017-08-05T15:07:17Z" , 
     "text" :  "This is an awesome comment!" 
   } 
} 
   
PUT /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/5dbdb466-5377-4351-bd1e-c4066437d410 
{ 
   "content" : { 
     "time" :  "2017-08-05T15:07:17Z" , 
     "rating" :  "excellent" 
     "by" : { 
         "userName" :  "supervisor_1" , 
         "firstName" :  "super" , 
         "lastName" :  "visor" 
     } 
   } 
}

Example Responses

200 OK 
{ 
   "statusCode" : 0 
} 
  
403 FORBIDDEN 
{ 
   "statusCode" : 15, 
   "statusMessage" :  "Cannot update the label for recording." 
} 
   
404 NOT FOUND 
{ 
   "statusCode" : 6, 
   "statusMessage" :  "Requested label cannot be found." 
}

Deleting a label from a recording

Request URL	/recordings/<recid>/labels/<id>
HTTP Method	DELETE
Required Roles	Administrator	Supervisor Agent
Required Permissions	N/A	RECORDING_PERMISSION_DELETE_LABEL

Response

HTTP Status
Status Codes	Situations
200 OK	The label has been deleted from the requested recording successfully.
403 FORBIDDEN	The recording requested can be found but the label cannot be deleted from it for some reason (for example, region not matched, requesting user cannot access the recording). The recording requested cannot be found.

Payload
Fields	Type	Mand- atory	Possible Values	Situations	Notes
statusCode	Integer	Yes	0 (Ok)	The label has been deleted from the requested recording successfully. OR The label cannot be found within the requested recording.
statusCode	Integer	Yes	14 (UnableToDeleteResource)	The label failed to be deleted from the requested recording.
statusMessage	String	No	Not specified. A message providing information.		The statusMessage will provide more information about a failure if statusCode is not 0.

Example Responses

DELETE /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
200 OK 
{ 
   "statusCode" : 0 
} 
   
DELETE /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31 
403 FORBIDDEN 
{ 
   "statusCode" : 14, 
   "statusMessage" :  "Label failed to be deleted from the recording." 
}

Getting all labels from a recording

Request URL	/recordings/<recid>/labels
HTTP Method	GET
Required Roles	Administrator Supervisor Agent
Required Permissions	N/A

Parameters

Attributes

JSON Data Type

Mandatory

Possible Values

Default Value

Description

Notes

Fields

comma-separated string of fields

No

*
name
createTime
createUser
content

N/A

The fields to be returned back for the label definition

If fields parameter is set, path and id are always returned regardless if they are specified or not

If fields value is set to "*", all the fields will be returned in the response.

if fields not specified, path, id, and name will be returned;

else if fields set to empty, path and id will be returned;
else, path, id, and fields specified will be returned.

Response

HTTP Status
Status Codes	Situations
200 OK	The retrieval of the labels succeeded or there are no labels associated with the recording.
403 FORBIDDEN	The recording for which the labels are requested can be found but cannot be retrieved for some reason (for example, region not matched, requesting user cannot access the recording). The recording for which the labels are requested cannot be found.

Payload
Fields	Subfields	Type	Mandatory	Possible Values	Situations	Notes
statusCode		Integer	Yes	0 (Ok)	The retrieval of the labels succeeded.
				12 (UnableToRetrieveResource)	The retrieval of the labels failed.
statusMessage		String	No	Not specified. A message providing information.		The statusMessage will provide more information about a failure if statusCode is not 0.
labels		Array of labels	No	Each label will have the fields requested.	Always
	id	String	No	The ID of the created label.	Always
	path	String	No	The path of the created label.	Always
	name	String	No	The name of the label definition.	Not specified or if fields parameter is received.
	createTime	String	No	The time when the label was last updated.	If the fields parameter is received.
	createUser	String	No	The username of the user who last updated the label on the recording.	If the fields parameter is received.
	content	JSON object	No	The JSON object containing custom content, if populated.	If the fields parameter is received.	The content is a JSON object that can contain custom data.

Examples

GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df5/labels
200 OK
{
   "statusCode" : 0,
   "labels" : []
}
  
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df4/labels
200 OK
{
   "statusCode" : 0,
   "labels" : [
     {
       "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31" ,
       "name" :  "comment" ,
       "id" :  "8c9a634f-343d-49b3-8322-b571be520b31"
     }
   ]
}
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels?fields=
200 OK
{
   "statusCode" : 0,
   "labels" : [
     {
       "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31" ,
      
       "id" :  "8c9a634f-343d-49b3-8322-b571be520b31"
     }
   ]
}
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels?fields=content
200 OK
{
   "statusCode" : 0,
   "labels" : [
     {
       "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31",
       "id" :  "8c9a634f-343d-49b3-8322-b571be520b31" ,
       "content" : {
         "time" :  "2017-04-22T12:42:44.000+0000" ,
         "comment" :  "This is an awesome comment!"
       }
     }
   ]
}
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels?fields=*
200 OK
{
   "statusCode" : 0,
   "labels" : [
     {
       "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels
/8c9a634f-343d-49b3-8322-b571be520b31" ,
       "name" :  "comment" ,
       "id" :  "8c9a634f-343d-49b3-8322-b571be520b31" ,
       "createTime" :  "2017-04-22T12:42:46.000+0000" ,
       "createUser" :  "supervisor" ,
       "content" : {
         "time" :  "2017-04-22T12:42:44.000+0000" ,
         "comment" :  "This is an awesome comment!"
       }
     }
   ]
}
  
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels
403 FORBIDDEN
{
   "statusCode" : 12,
   "statusMessage" :  "Recording cannot be found."
}
  
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels?fields=*
403 FORBIDDEN
{
   "statusCode" : 12,
   "statusMessage" :  "Recording cannot be accessed."
}

Getting a specific label from a recording

Request URL	/recordings/<recid>/labels/<id>
HTTP Method	GET
Required Roles	Administrator Supervisor Agent
Required Permissions	N/A

Response

HTTP Status
Status Codes	Situations
200 OK	The retrieval of the label succeeded.
403 FORBIDDEN	The recording for which the label is requested can be found but cannot be retrieved for some reason (for example, region not matched, requesting user cannot access the recording). The recording for which the label is requested cannot be found.
404 NOT FOUND	The label cannot be found by the ID specified.

Payload
Fields	Type	Mandatory	Possible Values	Situations	Notes
statusCode	Integer	Yes	0 (Ok)	Retrieval of the label succeeded.
			6 (ResourceNotFound)	The label cannot be found.
			12 (UnableToRetrieveResource)	Retrieval of the label failed.
statusMessage	String	No	Not specified. A message providing information.		The statusMessage will provide more information about a failure if statusCode is not 0.
label	JSON Object	No	The actual data of the label requested. A label contains the following information: Path (string): the path of the label. Name (string): the name of the label. Type (string): the type of the label. ID (string): the ID of the label. createTime (string): the time the label was last created or updated. createUser (string): the last user that created or updated the label. content (a JSON object): an object containing custom data, if populated.	It will only be displayed if the retrieval of the label succeeded.

Examples

GET /recordings/bf697521-3ffc-46f1-b840-f7230e940da3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
200 OK 
{ 
   "statusCode" : 0, 
   "label" : { 
     "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940da3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc" , 
     "name" :  "comment" , 
     "id" :  "1574da8d-ed8d-419d-b2e7-f00c1dabe0dc" , 
     "createTime" :  "2017-04-20T04:11:02.000+0000" , 
     "createUser" :  "supervisor" , 
     "content" : {} 
   } 
} 
   
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
403 FORBIDDEN 
{ 
   "statusCode" : 12, 
   "statusMessage" :  "Recording cannot be found." 
} 
   
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
404 NOT FOUND 
{ 
   "statusCode" : 6, 
   "statusMessage" :  "Label cannot be found for the recording." 
}

Contents

Recording Label API

Overview

Prerequisites

Roles and Permissions

Creating a label definition

Response

Example Request

Example Responses

Updating a label definition

Response

Example Request

Example Responses

Deleting a label definition

Response

Example Responses

Retrieving label definitions

Response

Label definition response data

Example

Adding a label to a recording

Response

Example Requests

Example Responses

Adding a label to multiple recordings

Response

Example Requests

Example Responses

Updating a label on a recording

Effect

Response

Example Requests

Example Responses

Deleting a label from a recording

Response

Example Responses

Getting all labels from a recording

Response

Examples

Getting a specific label from a recording

Response

Examples

Contact

Genesys

Customer Care

Legal