Timer API

Purpose

These APIs are used to start a new timer, to resume/pause an existing timer, to get current running timer, to add comments for the timer, delete comments for the timer and to get comments for the timer.

Start timer API

This API is used to start a new timer.

Request URL:

http://people.zoho.com/people/api/timetracker/timer?authtoken=<authtoken>&user=<user>&workDate= <workDate>&jobId=<jobId>&timer=<timer>&workItem= <workItem>&dateFormat=<dateFormat>&billingStatus=<billingStatus>

Request parameter:

ParametersValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*user< ERECNO | Email-ID | Employee-ID ><Mandatory>Specify the current user's value
*jobId<jobId><Mandatory>Specify jobId for which timer needs to be started
*workDate<date in yyyy-MM-dd/company dateformat><Mandatory>Specify the work date for when timelog needs to be added
dateFormat<dateFormat><company's date format>Specify the date format.
projectId< projectId>allSpecify the project Id based on which timer needs to be started
*billingStatus<billable | non billable | non-billable | nonbillable| all | 0 | 1 | -1><Mandatory>Specify the billable status
*timerstart<Mandatory>Specify value 'start'
description<description>-Specify the description(maximum length is 250)
workItem< workItem>-Specify the workitem (maximum length is 500)

Success Response Format:

{
    "response": {
        "result": [
            {
                "timeLogId": < timelogId >
            }
        ],
        "message": "Timelog entry added Successfully",
        "uri": "/api/timetracker/timer",
        "status": 0
    }
}

Error Response Format:

{
    "response": {
        "message": < message >,(NOTE: Refer the table below)
        "uri": "/api/timetracker/timer",
        "errors": {
            "code": < error_code >,
            "message": < error_message >
        },
        "status": 1
    }
}
Messages
Error in adding timelog
Cannot log time beyond attendance hours
Logged-in user alone can start timer
Error in adding/modifying Timelog.Logged Hours is greater than maximum billable hours allowed per day
Error in adding/modifying Timelog.Logged Hours is greater than Estimated hours

Error Codes & Messages:

Error CodeError Message
8000No parameter specified
8002Wrong format for parameter
8001Wrong value for parameter
7038Permission denied
8005Timer is disabled in Settings. Contact your Administrator
8008Cannot log time during Weekend/Holidays/Leave

Example

Request URL:

http://people.zoho.com/people/api/timetracker/timer?authtoken=28ac426a249678c8867a0d93bb373912&user=charles@zohocorp.com& jobId=492688000000806005&workDate=2019-04-05&timer=start&billingStatus=Billable

 

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/timer">
<status>0</status>
<message>Timelog entry added Successfully</message>
<result>
	<timeLogId>4926880000f00819003</timeLogId>
</result>
</response>
 

JSON response:

{
    "response": {
        "result": [
            {
                "timeLogId": "492688000000819009"
            }
        ],
        "message": "Timelog entry added Successfully",
        "uri": "/api/timetracker/timer",
        "status": 0
    }
}

Pause/Resume timer API

This API is used to resume/pause an existing timer.

Request URL:

http://people.zoho.com/people/api/timetracker/timer?authtoken=<authtoken>&timeLogId=<timeLogId>&timer=<timer>

Request parameter:

ParametersValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*timeLogId< timeLogId ><Mandatory>Specify the timelog id
*timer<start/stop><Mandatory>Specify the start to resume the timer or stop to pause the timer of the timelog

Success Response Format:

Timer Pause:

{
    "response": {
        "message": "Timer Paused successfully",
        "uri": "/api/timetracker/timer",
        "status": 0
    }
}

Timer Resume:

{
    "response": {
        "message": "Timer resumed successfully",
        "uri": "/api/timetracker/timer",
        "status": 0
    }
}

Error Response Format:

{
    "response": {
        "message": < message >,(NOTE: refer the table below)
        "uri": "/api/timetracker/timer",
        "errors": {
            "code": < error code >,
            "message": < error message >
        },
        "status": 1
    }
}
Messages
Error in pausing the timer
Error in restarting the timer
Cannot log time beyond attendance hours
Error in starting timer.Logged-in user alone can start timer
Error in pausing timer.Logged-in user alone can start timer
Error in restarting the Timer.Logged Hours is greater than maximum billable hours allowed per day
Error in pausing the Timer.Logged Hours is greater than maximum billable hours allowed per day
Error in restarting the Timer.Logged Hours is greater than Estimated hours
Error in pausing the Timer.Logged Hours is greater than Estimated hours

Error Codes & Messages:

Error CodeError Message
8000No parameter specified
8001Wrong value for parameter
8005Timer is disabled in Settings. Contact your Administrator
8008Cannot log time during Weekend/Holidays/Leave

Example

Request URL:

http://people.zoho.com/people/api/timetracker/timer?authtoken=28ac426a24967 8c8867a0d93bb373912&
timeLogId=281496000000264017&timer=start

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/timer">
<status>0</status>
<message>Timer Paused successfully</message>
</response>
 

JSON response:

{
    "response": {
        "message": "Timer Paused successfully",
        "uri": "/api/timetracker/timer",
        "status": 0
    }
}

Get currently running timer API

This API is used to get the currently running timer.

Request URL:

http://people.zoho.com/people/api/timetracker/getcurrentlyrunningtimer?authtoken=<authtoken>&dateFormat=<dateFormat>

Request parameter:

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

Success Response Format:

{
    "response": {
        "result": { (Note: This key exists only when there is a timer running currently)
            "jobName": < job name >
            "date": < current time (in secs) >,
            "hours": < hours in mins >,
            "erecno": < erecno >,
            "diff": < difference (in secs) between timer start time & current time >,
            "billingStatus": < billable | nonbillable >
            "timerId": < currently running timer's id >,
            "jobId": < jobId >,
            "workDate": < date in yyyy-mm-dd >,
            "totaltime": < total hours(in sec) logged for the timelog whose timer is running >,
            "isRunning": true,
            "timelogId": < timelog id containing the running timer >,
            "fromTime": < running timer's start time in sec >,
            "taskName": < workitem >,
            "employeename": < employee name >,
        },
        "message": "Running Timer information fetched successfully",
        "uri": "/api/timetracker/getcurrentlyrunningtimer",
        "status": 0
    }
}

Example

Request URL

http://people.zoho.com/people/api/timetracker/getcurrentlyrunningtimer?authtoken=28ac426a249678c8867a0d93bb373912

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/getcurrentlyrunningtimer">
<status>0</status>
<message>Running Timer information fetched successfully</message>
<result>
	<timer>
		<date>60635</date>
		<hours>241</hours>
		<jobName>UI designing</jobName>
		<erecno>492688000000142191</erecno>
		<diff>634</diff>
		<billingStatus>billable</billingStatus>
		<timerId>492688000000820013</timerId>
		<jobId>492688000000790013</jobId>
		<workDate>2019-04-06</workDate>
		<totaltime>14495</totaltime>
		<isRunning>true</isRunning>
		<timelogId>492688000000821095</timelogId>
		<fromTime>60001</fromTime>
		<taskName></taskName>
		<jobIsActive>true</jobIsActive>
		<employeename>amutha</employeename>
		<isCompleted>0</isCompleted>
	</timer>
</result>
</response>
 

JSON response:

{
    "response": {
        "result": {
            "jobName": "UI designing",
            "date": 60574,
            "hours": 241,
            "erecno": "492688000000142191",
            "diff": 573,
            "billingStatus": "billable",
            "timerId": "492688000000820013",
            "jobId": "492688000000790013",
            "workDate": "2019-04-06",
            "totaltime": 14495,
            "isRunning": true,
            "timelogId": "492688000000821095",
            "fromTime": 60001,
            "taskName": "",
            "jobIsActive": true,
            "employeename": "Christine Spalding",
            "isCompleted": 0
        },
        "message": "Running Timer information fetched successfully",
        "uri": "/api/timetracker/getcurrentlyrunningtimer",
        "status": 0
    }
}


Get comments for timer API

This API is used to get comments for the timer API.

Request URL:

http://people.zoho.com/people/api/timetracker/getcomments?authtoken=<authtoken>&timeLogId=<timeLogId>

Request parameter:

ParametersValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*timeLogId<timeLogId><Mandatory>Specify the timeLogId

Success Response Format:

{
    "response": {
        "result": [
            {
                "commentId": < comment id >,
                "createdTime": < date(in dd-mm-yyy) , time in( hh:mm:ss 24-hr format) >,
                "comment": < comment >
            }
        ],
        "message": "Timer Comments fetched successfully",
        "uri": "/api/timetracker/getcomments",
        "status": 0
    }
}

Error Response Format:

{
    "response": {
        "message": "Error in getting comments",
        "uri": "/api/timetracker/getcomments",
        "errors": [
            {
                "code": < error code >,
                "message": < error message >
            }
        ],
        "status": 1
    }
}

Error Codes & Messages:

Error CodeError Message
8000No <param_name> specified
8001Wrong value for <param_name>

Example

Request URL:

https://people.zoho.com/people/api/timetracker/getcomments?authtoken=1408d03bff741277ec9465eca625d390&
timeLogId=177402000000936001

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/getcomments">
<status>0</status>
<message>Timer Comments fetched successfully</message>
<result>
	<Comment>
		<commentId>492688000000821129</commentId>
		<createdTime>06-04-2019 , 17:22:28</createdTime>
		<comment>Complete security testing</comment>
	</Comment>
</result>
</response>
 

JSON response:

{
    "response": {
        "result": [
            {
                "commentId": "492688000000821129",
                "createdTime": "06-04-2019 , 17:22:28",
                "comment": "Complete security testing"
            }
        ],
        "message": "Timer Comments fetched successfully",
        "uri": "/api/timetracker/getcomments",
        "status": 0
    }
}

Add comment for timer API

This API is used to add comments for the running timer .

Request URL:

http://people/api/timetracker/addcomment?authtoken=369d0d85b1e3034dcdc5ba18f0&timeLogId=<timelogId>&comment=<comment>

Request parameter:

ParametersValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*timeLogId<timeLogId><Mandatory>Specify the timeLogId
*comment<comment><Mandatory>Specify the comment

Success Response Format:

{
    "response": {
        "result": [
            {
                "commentId": < commentId >
            }
        ],
        "message": "Timer Comment Added successfully",
        "uri": "/api/timetracker/addcomment",
        "status": 0
    }
}

Error Response Format:

{
    "response": {
        "message": "Error in adding comments",
        "uri": "/api/timetracker/addcomment",
        "errors": [
            {
                "code": < error code >,
                "message": < error message >
            }
        ],
        "status": 1
    }
}

Error Codes & Messages:

Error CodeError Message
8000No <param_name> specified
8001Wrong value for <param_name>
8005Comments can be added only when the timer is running

Example

Request URL:

http://people.zoho.com/people/api/timetracker/addcomment?authtoken=745bd43eff7a164a02bad52f0011fd35&
timeLogId=293141000000147001&comment=Complete security testing

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/addcomment">
<status>0</status>
<message>Timer Comment Added successfully</message>
<result>
   <commentId>492688000000822001</commentId>
</result>
</response>


JSON response:

{
    "response": {
        "result": [
            {
                "commentId": "492688000000822001"
            }
        ],
        "message": "Timer Comment Added successfully",
        "uri": "/api/timetracker/addcomment",
        "status": 0
    }
}

Delete comment for timer API

This API is used to delete comments of a timer.

Request URL:

http://people.zoho.com/people/api/timetracker/deletecomment?authtoken=<authtoken>&commentId=<commentId>

Request parameter:

ParametersValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*commentId<commentId><Mandatory>Specify the commentId to delete

Success Response Format:

{
    "response": {
        "message": "Timer Comments deleted successfully",
        "uri": "/api/timetracker/deletecomment",
        "status": 0
    }
}

Error Response Format:

{
    "response": {
        "message": "Error in deleting comment",
        "uri": "/api/timetracker/deletecomment",
        "errors": [
            {
                "code": < error code >,
                "message": < error message >
            }
        ],
        "status": 1
    }
}

Error Codes & Messages:

Error CodeError Message
8000No <param_name> specified
8001Wrong value for <param_name>

Example

Request URL:

https://people.zoho.com/people/api/timetracker/deletecomment?authtoken=745bd43eff7a164a02bad52f0011fd35&
commentId=293141000000144053

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/deletecomment">
<status>0</status>
<message>Timer Comments deleted successfully</message>
</response>
 

JSON response:

{
    "response": {
        "message": "Timer Comments deleted successfully",
        "uri": "/api/timetracker/deletecomment",
        "status": 0
    }
}