Time logs API

Purpose

These APIs are used to get time logs, to add, to modify and to delete the time logs.

Get time logs API

This API is used to get the list of time logs.

Request URL:

http://people.zoho.com/people/api/timetracker/gettimelogs?authtoken=<authtoken>&fromDate=<fromDate>&toDate= <toDate>&billingStatus=<billingStatus>&jobId=<jobId>&user =<user>&dateFormat=<dateFormat>

Request parameter:

ParametersValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*user< all | ERECNO | Email-ID | Employee-ID ><current user>Specify user whose timelogs needs to be fetched
jobId<jobId>allSpecify jobId for which timelogs needs to be fetched
fromDate<date in yyyy-MM-dd/company dateformat><current date>Specify the date from when timelogs performed needs to be fetched
toDate<date in yyyy-MM-dd/company dateformat><current date>Specify the date uptill when timelogs performed needs to be fetched
dateFormat<dateFormat><company's date format>Specify the date format.
clientId< clientId >allSpecify the client id for which timelogs needs to be fetched
projectId< projectId>allSpecify the project Id based on which timelogs needs to be fetched
billingStatus<billable | non billable | non-billable | nonbillable| all | 0 | 1 | -1>allSpecify the billable status based on which timelogs needs to be fetched
approvalStatus< approvalStatus>allSpecify the approvalStatus based on which timelogs needs to be fetched
isCommentsCount<true|false>falseFetches the comments count of the timer timelog
sIndex< sIndex>0Specify from which record the response should be fetched
limit< limit>200Specify the number of records to be fetched.Maximum value is 200

Success Response Format:

{
"response": {
"result":  [{
         "erecno": < employee_erecno >,
         "employeeMailId": < emp_mailId >,
         "employeeLastName": < emp_lname >,
         "employeeFirstName": < emp_fname >,
         "timerLog": < true|false >,
         "timelogId": < timelog_id >,
         "type": <0|1|2>,(0-hours Type ,1-Start&End Type,2-Timer type)
         "workDate":< workdate_in_company_dateformat >,
         "toTime": < to_time_in_mins >,
         "isCurrentlyRunning":< true|false >, 
         "fromTime": < from_time_in_mins >,
         "fromTimeInTimeFormat": < from_time_in_company settings time format >,
         "toTimeInTimeFormat": < to_time_in_company settings time format >,
         "hours": < hours in HH:MM format >,
         "totaltime": < total_time_in_secs >,
         "taskName": < work_item >,
         "description": < timelog_description >,
         "jobId": < job_id >,
         "jobName": < job_name >, 
         "jobIsActive": < true|false >,
         "jobIsCompleted": < 0|1 >,(NOTE: 0-in-progress,1-completed)
         "clientId": < client_id >,
         "projectName": < project_name >,
         "projectId":< project_id >,
         "billingStatus": < billable|non-billable >,
         "isDeleteAllowed": < true|false >,
         "isEditAllowed":< true|false >,
         "isTimelogPushedToQBO": < true|false >,
         "billedStatus": < billed|not billed >,
         "approvalStatus": < approval_status >,
         "isTimelogPushedToZF":< true|false >,
         "commentsCount": < commentcount >,(NOTE:key exists when isCommentsCount=true)
         "add_ip":< added_ip_address>,
         "mod_ip":< modified_ip_address >,
         "isCurrentlyRunning":< true >,(NOTE:key exists if timelog's timer is running)
         "timearr":[(NOTE:key exists only when the timelog is of timer type)
               {
                 "fromTime": < from_time_in_secs >,
                 "geoLocation_in":< timer_started_location >,
                 "geoLocation_out": < timer_stopped_location >,
                 "toTime": < to_time_in_secs >,
                 "fromTimeInTimeFormat": < time_in_company settings timeformat >,
                 "toTimeInTimeFormat": < time_in_company settings timeformat >, 
                 "timerId": < timer_id> ,
                 "mod_ip": < modified_ip_address >,
                 "isRunning":< true >(NOTE:key exists only when the timer set is running)
               },....
	          ],}    
   ],...
         "isNextAvailable": true, (NOTE:this key exists only if there is more data)
	"message": "Data fetched successfully",
	 "uri": "/api/timetracker/gettimelogs",
}

Error Response Format:

{
  "response": {
    "message": "Error in fetching data",
    "uri": "/api/timetracker/gettimelogs",
    "errors": [
      {
        "code": < error_code >,
        "message": < error_message >
      }],
    "status": 1
  }
}

Error Codes & Messages:

Error CodeError Message
9000Permission denied
9002No parameter specified
9004Wrong date format given for parameter
9006toDate should be after the fromDate
9007Maximum of one month's data can only be fetched at a time

Example

Request URL:

http://people.zoho.com/people/api/timetracker/gettimelogs?authtoken=ffb014e4d3af62aa74c7db66eff557fc&user=charless@zohocorp.com&jobId=all&fromDate=2014-12-01&toDate=2014-12-31&billingStatus=all

XML response:

 <?xml version="1.0" encoding="UTF-8"?>
 <response uri="/api/timetracker/gettimelogs">
 <status>0</status>
 <message>Data fetched successfully</message>
 <result>
	<job>
		<erecno>492688000000135005</erecno>
		<timerLog>true</timerLog>
		<employeeMailId>c.spalding@zylker.com</employeeMailId>
		<employeeFirstName>Christine</employeeFirstName>
		<isDeleteAllowed>true</isDeleteAllowed>
		<type>2</type>
		<workDate>04-04-2019</workDate>
		<fromTime>666</fromTime>
		<billedStatus>not billed</billedStatus>
		<timearr>
		[{"timerId":"492688000000808292",
                         "fromTime":54040,
                         "fromTimeInTimeFormat":"03:00PM",
                         "toTime":64847,
                         "toTimeInTimeFormat":"06:00PM"}]
	            </timearr>
		<jobIsActive>true</jobIsActive>
		<toTime>667</toTime>
		<jobName>Development Phase</jobName>
		<approvalStatus>notsubmitted</approvalStatus>
		<hours>05:00</hours>
		<db_workDate>2019-04-04 00:00:00.0</db_workDate>
		<jobIsCompleted>0</jobIsCompleted>
		<jobBillableStatus>0</jobBillableStatus>
		<isEditAllowed>true</isEditAllowed>
		<billingStatus>billable</billingStatus>
		<jobId>492688000000808246</jobId>
		<isTimelogPushedToQBO>false</isTimelogPushedToQBO>
		<totaltime>18015</totaltime>
		<employeeLastName>Spalding</employeeLastName>
		<timelogId>492688000000808276</timelogId>
		<taskName></taskName>
	</job>
	<job>
		<erecno>492688000000135005</erecno>
		<timerLog>false</timerLog>
		<employeeMailId>c.spalding@zylker.com</employeeMailId>
		<isTimelogPushedToZF>false</isTimelogPushedToZF>
		<employeeFirstName>Sridhar</employeeFirstName>
		<isDeleteAllowed>true</isDeleteAllowed>
		<type>1</type>
		<workDate>09-04-2019</workDate>
		<fromTime>600</fromTime>
		<billedStatus>not billed</billedStatus>
		<fromTimeInTimeFormat>10:00AM</fromTimeInTimeFormat>
		<jobIsActive>true</jobIsActive>
		<toTime>1080</toTime>
		<jobName>Development Phase</jobName>
		<approvalStatus>notsubmitted</approvalStatus>
		<hours>08:00</hours>
		<db_workDate>2019-04-09 00:00:00.0</db_workDate>
		<jobIsCompleted>0</jobIsCompleted>
		<jobBillableStatus>0</jobBillableStatus>
		<isEditAllowed>true</isEditAllowed>
		<billingStatus>billable</billingStatus>
		<jobId>492688000000808246</jobId>
		<isTimelogPushedToQBO>false</isTimelogPushedToQBO>
		<totaltime>28800</totaltime>
		<employeeLastName>Spalding</employeeLastName>
		<timelogId>492688000000808270</timelogId>
		<toTimeInTimeFormat>06:00PM</toTimeInTimeFormat>
	</job>
 </result>
 </response>
 

JSON response:

{
    "response": {
        "result": [
            {
                "erecno": "492688000000135005",
                "timerLog": true,
                "employeeMailId": "c.spalding@zylker.com",
                "isTimelogPushedToZF": false,
                "jobColor": 1,
                "employeeFirstName": "Christine",
                "isDeleteAllowed": true,
                "type": "2",
                "workDate": "04-04-2019",
                "fromTime": 666,
                "billedStatus": "not billed",
                "timearr": [
                    {
                        "timerId": "492688000000808292",
                        "fromTime": 54040,
                        "fromTimeInTimeFormat": "03:00PM",
                        "toTime": 64847,
                        "toTimeInTimeFormat": "06:00PM"
                    },
                    {
                        "timerId": "492688000000808280",
                        "fromTime": 39908,
                        "fromTimeInTimeFormat": "11:05AM",
                        "toTime": 47116,
                        "toTimeInTimeFormat": "01:05PM",
                    }
                ],
                "jobIsActive": true,
                "toTime": 667,
                "jobName": "Development Phase",
                "approvalStatus": "notsubmitted",
                "hours": "05:00",
                "db_workDate": "2019-04-04 00:00:00.0",
                "jobIsCompleted": 0,
                "jobBillableStatus": "0",
                "isEditAllowed": true,
                "billingStatus": "billable",
                "jobId": "492688000000808246",
                "isTimelogPushedToQBO": false,
                "totaltime": 18015,
                "employeeLastName": "Spalding",
                "timelogId": "492688000000808276",
                "taskName": "",
            },
           {
                "erecno": "492688000000135005",
                "timerLog": false,
                "employeeMailId": "c.spalding@zylker.com",
                "employeeFirstName": "Christine",
                "isDeleteAllowed": true,
                "type": "1",
                "workDate": "09-04-2019",
                "fromTime": 600,
                "billedStatus": "not billed",
                "fromTimeInTimeFormat": "10:00AM",
                "jobIsActive": true,
                "toTime": 1080,
                "longitude": 80.0493048,
                "jobName": "Development Phase",
                "approvalStatus": "notsubmitted",
                "hours": "08:00",
                "db_workDate": "2019-04-09 00:00:00.0",
                "jobIsCompleted": 0,
                "jobBillableStatus": "0",
                "isEditAllowed": true,
                "billingStatus": "billable",
                "jobId": "492688000000808246",
                "isTimelogPushedToQBO": false,
                "totaltime": 28800,
                "employeeLastName": "Spalding",
                "timelogId": "492688000000808270",
                "toTimeInTimeFormat": "06:00PM",
            }
        ],
        "message": "Data fetched successfully",
        "uri": "/api/timetracker/gettimelogs",
        "status": 0
    }
}

Add time log API

This API is used to add the time log.

Request URL:

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

Request parameter:

ParametersValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*user< ERECNO | Email-ID | Employee-ID ><Mandatory>Specify the user for whom timelog needs to be added
*jobId<jobId><Mandatory>Specify the job Id for which the timelog needs to be done
projectId<projectId>-Specify the project Id of the job if needed
projectName<projectName>-Specifying project name will create a new project based on the form add permission of the user
jobName<jobName>-Specifying job name will create a new job based on the form add permission of the user
*workDate<date in yyyy-MM-dd/company dateformat><Mandatory>Specify the work date for when timelog needs to be added
dateFormat<dateformat>yyyy-MM-ddSpecify the date format.
billingStatus<billable/non-billable>Default Billing status based on settingsSpecify the Billiable status
hours<hours in decimal/time format>0Decimal-2.5 or Time format-2:30
fromTime<time in timeformat>-Time format-2:30PM or 14:30
toTime<time in timeformat>-Time format-2:30PM or 14:30
workItem<workitem>-Specify the workitem
description<description>-Specify the description

Success Response Format:

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

Error Response Format:

{
  "response": {
    "message": < message>,(NOTE: refer the table below)
   "uri": "/api/timetracker/addtimelog",
    "errors": [
      {
        "code": < error_code >,
        "message": < error_message >
      }],
    "status": 1
  }
}
Messages
Error in adding data
Manual Log is disabled in Settings. Contact your Administrator.
Cannot log time for a Future Date
Logged-in user alone can start timer
Error in adding/modifying Timelog.Logged Hours is greater than maximum billable hours allowed per day
Cannot log time beyond attendance hours
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/addtimelog?authtoken=28ac426a249678c8867a0d93bb373912&
user=charles@zohocorp.com&jobName=Testing&workDate=2015-01-05&billingStatus=Billable&hours=10

XML response:

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

JSON response:

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

Modify time log API

This API is used to edit the time log.

Request URL:

http://people.zoho.com/people/api/timetracker/edittimelog?authtoken=<authtoken>&timeLogId=<timeLogId>&user= <user>&workDate =<workDate>&jobId =<jobId>&hours=<hours>&fromTime=<fromTime>&toTime=<toTime>&billingStatus =<billingStatus>&description =<description>&workItem=<workItem>

Request parameter:

ParametersValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*timeLogId<timeLogId><Mandatory>Specify the timelog Id whose details needs to be modified
user< ERECNO | Email-ID | Employee-ID ><Mandatory>Specify the user
jobId<jobId >-Specify the job Id if needed to be modified.
workDate<date in yyyy-MM-dd/company dateformat>-Specify the workdate if needed to be modified.
dateFormat<dateformat>yyyy-MM-ddSpecify the date format. If not specified, yyyy-MM-dd format will be taken
billingStatus<billable|non-billable>-Specify the billable status if needed
hours<hours in decimal/time format>-Decimal-2.5 or Time format-2:30
fromTime<time in timeformat>-Time format-2:30PM or 14:30
toTime<time in timeformat>-Time format-2:30PM or 14:30
workItem<workitem>-Specify the workitem
description<description>-Specify the description

Success Response Format:

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

Error Response Format:

{
  "response": {
    "message": < message >,
   "uri": "/api/timetracker/edittimelog",
    "errors": [
      {
        "code": < error_code >,
        "message": < error_message >
      }],
    "status": 1
  }
Messages
Error in modifying data
Manual Log is disabled in Settings. Contact your Administrator.
Cannot log time for a Future Date
Logged-in user alone can start timer
Error in adding/modifying Timelog.Logged Hours is greater than maximum billable hours allowed per day
Cannot log time beyond attendance hours
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
8008Cannot log time during Weekend/Holidays/Leave

Example

Request URL

http://people.zoho.com/people/api/timetracker/edittimelog?authtoken=28ac426a249678c8867a0d93bb373912&
timeLogId=177402000000814321&workItem=designing&user=49268800000013&
billingStatus=Billable&hours=10

 

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/edittimelog">
   <status>0</status>
   <message>Timelog entry modified Successfully</message>
   <result>
      <timeLogId>469505000000265027</timeLogId>
   </result>
</response>
 

JSON response:

{
    "response": {
        "result": [
            {
                "timeLogId": "469505000000265027"
            }
        ],
        "message": "Timelog entry modified Successfully",
        "uri": "/api/timetracker/edittimelog",
        "status": 0
    }
}

Delete time logs API

This API is used to delete the timelogs.

Request URL:

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

Request parameter:

ParametersValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*timeLogId<timeLogId><Mandatory>Specify the timeLogId (seperated by commas)

Success Response Format:

{
    "response": {
        "result": [
            {
                "timeLogId": < timelogid >
            }
        ],
        "message": "Timelog(s) deleted successfully",
        "uri": "/api/timetracker/deletetimelog",
        "status": 0
    }
}

Error Response Format:

{
  "response": {
    "message": "Error occured",
    "uri": "/api/timetracker/deletetimelog",
    "errors": [
      {
        "code": < error_code >,
        "message": < error_message >
      }],
    "status": 1
 }
}

Error Codes & Messages:

Error CodeError Message
8000No <param_name> specified
8001Wrong value for <param_name>
8005TimerRunningError: Time Logs deleted. Skipped Time Log with timer running

Example

Request URL:

http://people.zoho.com/people/api/timetracker/deletetimelog?authtoken=28ac426a249678c8867a0d93bb373912&timeLogId=177402000000814321

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/deletetimelog">
   <status>0</status>
   <message>Timelog(s) deleted successfully</message>
</response>
 

JSON response:

{
    "response": {
        "message": "Timelog(s) deleted successfully",
        "uri": "/api/timetracker/deletetimelog",
        "status": 0
    }
}