Cases API

Purpose

These APIs are used to add case, view case, list cases.

Add case API

This API is used to add cases.

Request URL:

https://people.zoho.com/api/hrcases/addcase?authtoken=<Authtoken>&categoryId=<Category ID>&subject=<subject>&description=<description>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*categoryId<Category ID><Mandatory>Specify the category ID
*subject<Subject><Mandatory>Specify the subject of the case
description<Description><Empty>Specify the description of the case

Success Response Format :

{
  "response": {
     "result": {
	"zp_recordId":<Record ID of the case>,
            "caseId": <Generated case ID>,
            "desc": <Description of the action performed>,
            "status": <status of the action performed>
      },
       "message": "Success",
       "uri": "/api/hrcases/addcase",
       "status": 0
   }
}

Error Response Format :

{
   "response": {
        "message": "Error occurred",
        "uri": "/api/hrcases/addcase",
        "errors": {
            "desc": <Description of the error message>,
	"status": <Status of the action performed>
	},
        "status": 1
   }
}

Example :

Request URL :

https://people.zoho.com/api/hrcases/addcase?categoryId=323150000000281001&subject=What time does the seminar on Security start tomorrow?&description=Also where in the premises is the seminar held?&authtoken=03a8fe957320f9877ab650dc21ed58c7

 

JSON response:

{
  "response": {
        "result": {
            "zp_recordId": "323150000000686003",
            "caseId": "#00108",
            "desc": "Success",
            "status": "success"
        },
        "message": "Success",
        "uri": "/api/hrcases/addcase",
        "status": 0
  }
}

View case details API

This API is used to view case details.

Request URL:

https://people.zoho.com/api/hrcases/viewcase?authtoken=<Authtoken>&recordId=<Record ID of the case>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*recordId<Record ID of the case><Mandatory>Specify the record ID of the case

Success Response Format :

{
    "response": {
        "result": {
            "filesList": [
                {
                    "fileName": <Returns file name>,
                    "downloadUrl": <Returns download URL of the attached file>,
                    "filesize": <Returns file size>,
                    "fileUploadId": <Returns record ID of file attached>,
                }, ...
            ],
            "caseDetails": {
				"agent": {
                        "empid": <Agent employee ID>, (Key available only if the agent is employee)
                        "erecno": <Employee Record ID>, (Key available only if the agent is employee)
                        "employeePhoto": <Employee Photo URL>, (Key available only if the agent is employee)
                        "name": <Employee Display name>, (Key available only if the agent is employee)
                        "zuid": <ZUID of the Agent(Employee)> (Key available only if the agent is employee)
                        "details": <Agent display name - employee / department / group ID>,
                        "valueId": <Agent ID - it can be employee / department / group ID>,
                        "typeId": <Type ID of Agent>,
                        "type": <Type of Agent - display name>,
                },
                "permittedCaseStatus": [ (Object is empty if the user cannot change status of this case - Returns only valid status that the user is allowed to change for this case)
                    {
                        "optionValue": <Status name>,
                        "optionId": <Status record ID>,
                        "systemValue": <Status ID>
                    }, ...
                ]
                "subject": <Subject of the case>,
                "description":  <Description of the case>,
                "categoryName": <Name of the category>,
                "requestor": {
                        "empid": <Requestor employee ID>,
                        "erecno": <Employee Record ID>,
                        "employeePhoto":<Employee Photo URL>,
                        "name": <Employee Display name>,
                        "zuid": <ZUID of the Requestor(Employee)> 
                },
                "statusId": <ID of the status of case>,
                "isAgent": <Returns true if user is an agent>,
                "categoryIcon": <Returns Icon display name of the category>,
                "caseId": <Case ID>,
				"createdTime": <case created time in Long>,
				"isEscalatedUser": <returns true if the case is escalated to the user>,
                "categoryId": <Category ID>,
                "status": <Status of this case>
            },
            "needCategoryChange": <returns true if the user is eligible to change category of the case>,
             "SLA": { (Object is empty if there is no SLA defined for this case)
                        "nextViolation": <immediate next violation display time count down>, (Key available only if there is countdown to escalation - not available when there is no SLA or already escalated or case closed)
                        "currentStatus": <Status of the timer ; 1 - start, 2 - paused, 3 - stop>,
                        "isViolated": <If the case violated SLA>
             },
        },
        "message": "Success",
        "uri": "/api/hrcases/viewcase",
        "status": 0
    }
}

Error Response Format :

{
  "response": {
      "message": "Error occurred",
      "uri": "/api/hrcases/viewcase",
      "errors": {
          "status": <Status of action performed>,
          "desc": <Description of the error>
      },
      "status": 1
   }
}

Example :

Request URL :

https://people.zoho.com/api/hrcases/viewcase?authtoken=03a8fe957320f9877ab650dc21ed58c7&recordId=323150000000281001

 

JSON response:

{
    "response": {
        "result": {
            "filesList": [
                {
                    "fileName": "Security_Seminar_Invitation.pdf",
                    "downloadUrl": "https://people.zoho.com/api/hrcases/downloadFile?&recordId=323150000000686003&fileId=323150000000686025&fileType=1",
                    "filesize": "32.35 KB",
                    "fileUploadId": "323150000000686025"
                }, ...
            ],
            "caseDetails": {
                "agent": {
                    "empid": "1",
                    "valueId": "323150000000082005",
                    "erecno": "323150000000082005",
                    "employeePhoto": "viewPhoto?filename=567593000000015001",
                    "name": "1 Admin AD",
                    "details": "Admin AD",
                    "typeId": "1",
                    "type": "Employee",
                    "zuid": "408541577"
                },
                "permittedCaseStatus": [],
                "subject": "What time does the seminar on Security start tomorrow?",
                "description": "Also where in the premises is the seminar held?",
                "categoryName": "General Queries",
                "requestor": {
                    "empid": "2",
                    "erecno": "323150000000082109",
                    "employeePhoto": "https://contacts.zoho.com/file?ID=409625379&fs=thumb",
                    "name": "2 Manager MG",
                    "zuid": "409625379"
                },
                "statusId": "1",
                "isAgent": false,
                "categoryIcon": "star",
                "caseId": "#00108",
                "createdTime": "1559557216353",
                "isEscalatedUser": false,
                "categoryId": "323150000000281001",
                "status": "Open"
            },
            "needCategoryChange": true,
            "sla": {
                "nextViolation": "00 : 54 : 22",
                "currentStatus": 1,
                "isViolated": true
            },
        },
        "message": "Success",
        "uri": "/api/hrcases/viewcase",
        "status": 0
    }
}

View case listings API

This API is list cases.

Request URI for Requested Cases: https://people.zoho.com/api/hrcases/getRequestedCases?authtoken=<Authtoken>&index=<index>&status=<status>

Request URI for cases assigned to User: https://people.zoho.com/api/hrcases/getMyCases?authtoken=<Authtoken>&index=<index>&status=<status>&query=<query>&requestorErecno=<Employee Record ID of Requestor>&periodOfTime=<Time period>

Request URI for unassigned cases: https://people.zoho.com/api/hrcases/getUnassignedCases?authtoken=<Authtoken>&index=<index>

Request URI for cases open for the User: https://people.zoho.com/api/hrcases/getOpenCases?authtoken=<Authtoken>&index=<index>&status=<status>&query=<query>&requestorErecno=<Employee Record ID of Requestor>&periodOfTime=<Time period>

Request URI for all cases: https://people.zoho.com/api/hrcases/getAllCases?authtoken=<Authtoken>&index=<index>&status=<status>&query=<query>&categoryId=<Category ID>&requestorErecno=<Employee Record ID of Requestor>&periodOfTime=<Time period>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*index<index of listing><Mandatory - 1>Specify the index of the listing
status<multiple status IDs><Empty>String of status IDs separated by (,) comma - (Open: "1", In Progress: "2", Awaiting action from Requestor: "3", On Hold: "4", Closed: "5") - empty for all status
categoryId<multiple category IDs><Empty>Category IDs separated by (,) comma
query<query string><Empty>Specify the query string of the case
requestorErecno<Multiple record IDs of requestor><Empty>Employee record IDs separated by (,) comma
periodOfTime<Time limit><Empty>Send single time limit(Today - 0, Yesterday - 1, Past 7 days - 2, Past 30 days - 3)

Success Response Format :

{
    "response": {
        "result": {
            "hrcaseList": [
                {
                    "agent": {
                        "empid": <Agent employee ID>, (Key available only if the agent is employee)
                        "erecno": <Employee Record ID>, (Key available only if the agent is employee)
                        "employeePhoto": <Employee Photo URL>, (Key available only if the agent is employee)
                        "name": <Employee Display name>, (Key available only if the agent is employee)
                        "zuid": <ZUID of the Agent(Employee)> (Key available only if the agent is employee)
                        "details": <Agent display name - employee / department / group ID>,
                        "valueId": <Agent ID - it can be employee / department / group ID>,
                        "typeId": <Type ID of Agent>,
                        "type": <Type of Agent - display name>,
                    },
                    "subject": <Subject of the case>,
                    "SLA": { (Object is empty if there is no SLA defined for this case)
                        "nextViolation": <immediate next violation display time count down>, (Key available only if there is countdown to escalation - not available when there is no SLA or already escalated or case closed)
                        "currentStatus": <Status of the timer ; 1 - start, 2 - paused, 3 - stop>,
                        "isViolated": <If the case violated SLA>
                    },
                    "categoryName": <Name of the category>,
                    "requestor": {
                        "empid": <Requestor employee ID>,
                        "erecno": <Employee Record ID>,
                        "employeePhoto":<Employee Photo URL>,
                        "name": <Employee Display name>,
                        "zuid": <ZUID of the Requestor(Employee)> 
                    },
                    "recordId": <Case record ID>,
                    "hasAttachment": <If the case has documents attached>,
                    "statusId": <ID of the status of case>,
                    "caseId": <Case ID>,
                    "followerMode": <Reason for user to have this case in watchlist>, (Key available only if this case is in the user's watchlist
                    "createdTime": <case created time in Long>,
                    "categoryId": <Category ID>,
                    "status": <Status of this case>
                }, ...
            ],
            "isNextAvailable": <returns true if there are more cases> (Each fetch will bring set of 25 cases)
        },
        "message": "Success",
        "uri": "/api/hrcases/getRequestedCases",
        "status": 0
    }
}

Example :

Request URL :

https://people.zoho.com/api/hrcases/getRequestedCases?authtoken=03a8fe957320f9877ab650dc21ed58c7&index=1

 

JSON response:

{
    "response": {
        "result": {
            "hrcaseList": [
                {
                    "recordId": "323150000000686003",
                    "hasAttachment": true,
                    "agent": {
                        "empid": "1",
                        "valueId": "323150000000082005",
                        "erecno": "323150000000082005",
                        "employeePhoto": "viewPhoto?filename=567593000000015001",
                        "name": "1 Admin AD",
                        "details": "Admin AD",
                        "typeId": "1",
                        "type": "Employee",
                        "zuid": "408541577"
                    },
                    "statusId": "1",
                    "subject": "What time does the seminar on Security start tomorrow?",
                    "caseId": "#00108",
                    "SLA": {
                        "nextViolation": "55 minutes",
                        "currentStatus": 1,
                        "isViolated": true
                    },
                    "createdTime": "1559557216353",
                    "categoryName": "General Queries",
                    "categoryId": "323150000000281001",
                    "requestor": {
                        "empid": "2",
                        "erecno": "323150000000082109",
                        "employeePhoto": "https://contacts.zoho.com/file?ID=409625379&fs=thumb",
                        "name": "2 Manager MG",
                        "zuid": "409625379"
                    },
                    "status": "Open"
                }, ...
            ],
            "isNextAvailable": false
        },
        "message": "Success",
        "uri": "/api/hrcases/getRequestedCases",
        "status": 0
    }
}

View list of categories API

This API is used to list categories that a user case raise query to.

Request URL:

https://people.zoho.com/api/hrcases/listCategory?authtoken=<Authtoken>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token

Success Response Format :

{
   "response": {
      "result": [
         {
	"isAgent": <Returns true if user is an agent>,
	"categoryIcon": <Returns Icon display name of the category>,
	"isEnabled": <Returns true if the category is enabled>,
	"categoryShortDescription": <Returns short description of the category>,
	"serviceId": <Returns ID of service from where this category is enabled else returns emtpy>,
            "applicableLocations": <Returns array of location IDs specifically where the user is an agent for. If empty and if user is agent, then user is agent for all locations>,
            "categoryName": <Returns category name>,
            "categoryId": <Category ID>
           }, ...
       ],
       "message": "Success",
       "uri": "/api/hrcases/listCategory",
       "status": 0
    }
}

Example :

Request URL :

https://people.zoho.com/api/hrcases/listCategory?authtoken=03a8fe957320f9877ab650dc21ed58c7

 

JSON response:

{
	"response": {
	"result": [
	{
	"isAgent": true,
	"categoryIcon": "Travel",
	"isEnabled": true,
	"categoryShortDescription": "Post your queries regarding transportation facilities provided by our organization",
	"serviceId": "",
	"applicableLocations": [],
	"categoryName": "Transport",
	"categoryId": "323150000000202001"
	}, ...
			],
	"message": "Success",
		"uri": "/api/hrcases/listCategory",
	"status": 0
	}
}