Timesheet API

Purpose

These APIs are used to get the list of timesheets, timesheet details, create timesheet, modify timesheet, approve timesheet and delete the timesheet(s).

Get timesheets API

This API is used to get the list of timesheets.

Request URL:

https://people.zoho.com/people/api/timetracker/gettimesheet?authtoken=<authtoken>&user=<user>&approvalStatus=<approvalStatus>&employeeStatus=<employeeStatus>&dateFormat=<dateFormat>&fromDate=<fromDate>&toDate=<toDate>&sIndex=<sIndex>&limit=<limit>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*userall | <Email Id> | <Employee Id> | <Erec No><Mandatory>Specify the user whose timesheets have to be fetched
dateFormat<Date format>Company date formatSpecify the format in which the dates should be provided
fromDate<From date>-Specify the "from date" of the timesheet
toDate<To date>-Specify the "to date" of the timesheet
approvalStatusall | draft | pending | approved | rejectedallSpecify the approval status of the timesheet
employeeStatususers | nonusers | usersandnonusers | logindisabledusersandnonusersSpecify the status of the employees whose timesheets have to be fetched
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": [
            {
                "recordId": <Timesheet Id>,
                "listId": <Timesheet Id>,
                "timesheetName": <Timesheet name>,
                "erecno": <User Id>,
                "employeeName": <User name>,
                "employeeId": <Employee Id>,
                "employeeEmail": <User mail Id>,
                "description": <Description>,
                "fromDate": <Timesheet start date>,
                "toDate": <Timesheet end date>,
                "owner": <Owner Id>,
                "status": <Draft | Pending | Approved | Rejected>,
                "currency": <Currency code>,
                "billableHours": <Total billable hours in HH:mm>,
                "nonbillableHours": <Total non billable hours in HH:mm>,
                "totalHours": <Total hours in HH:mm>,
                "approvedBillableHours": <Approved billable hours in HH:mm>,
                "approvedNonBillableHours": <Approved non billable hours in HH:mm>,
                "approvedTotalHours": <Approved total hours in HH:mm>,
                "ratePerHour": <Employee rate per hour>,
                "approvedRatePerHour": <Approved rate>,
                "totalAmount": <Total amount>,
                "approvedTotalAmount": <Approved total amount>
            },....
        ],
        "message": "Data fetched successfully",
        "uri": "/api/timetracker/gettimesheet",
        "status": 0
    }
}

Error Response Format :

{
    "response": {
        "message": "Error in fetching data",
        "uri": "/api/timetracker/gettimesheet",
        "errors": [
            {
                "code": <Error Code>,
                "message": <Error Message>
            }
        ],
        "status": 1
    }
}

Error Codes and Messages :

Error CodeError Message
9000Permission denied
9002No <parameter name> parameter specified
9003Wrong value given for <parameter name> parameter
9004Wrong date format given for <parameter name> parameter
9005Time Tracker tab is disabled
9006toDate should be after the fromDate

Example :

Request URL :

https://people.zoho.com/people/api/timetracker/gettimesheet?authtoken=9f8d1b973c85dbec3a335ac976319f6d&user=eliza.madison@gmail.com&approvalStatus=
approved&employeeStatus=users&dateFormat=dd-MMM-yyyy&fromDate=07-Apr-2019&toDate=13-Apr-2019&sIndex=0&limit=1

 

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/gettimesheet">
    <status>0</status>
    <message>Data fetched successfully</message>
    <result>
        <timesheet>
            <owner>469505000000133005</owner>
            <formId>469505000000118001</formId>
            <nonbillableHours>03:48</nonbillableHours>
            <employeeName>Eliza Madison</employeeName>
            <erecno>469505000000133005</erecno>
            <totalHours>04:48</totalHours>
            <toDate>13-Apr-2019</toDate>
            <description>Worked on System/Requirement Analysis</description>
            <employeeEmail>eliza.madison@gmail.com</employeeEmail>
            <approvedBillableHours>01:00</approvedBillableHours>
            <employeeId>ID - 1</employeeId>
            <billableHours>01:00</billableHours>
            <recordId>469505000000272183</recordId>
            <listId>469505<<000000272183</listId>
            <fromDate>07-Apr-2019</fromDate>
            <totalAmount>100.00</totalAmount>
            <approvedNonBillableHours>00:00</approvedNonBillableHours>
            <approvedRatePerHour>100.0</approvedRatePerHour>
            <approvedTotalAmount>100.00</approvedTotalAmount>
            <ratePerHour>100.0</ratePerHour>
            <timesheetName>Weekly Timesheet (07-Apr-2019 - 13-Apr-2019)</timesheetName>
            <currency>USD</currency>
            <approvedTotalHours>01:00</approvedTotalHours>
            <status>Approved</status>
        </timesheet>
    </result>
</response>
 

JSON response:

{
    "response": {
        "result": [
            {
                "owner": "469505000000133005",
                "formId": "469505000000118001",
                "nonbillableHours": "03:48",
                "employeeName": "Eliza Madison",
                "erecno": "469505000000133005",
                "totalHours": "04:48",
                "toDate": "13-Apr-2019",
                "description": "Worked on System/Requirement Analysis",
                "employeeEmail": "eliza.madison@gmail.com",
                "approvedBillableHours": "01:00",
                "employeeId": "ID - 1",
                "billableHours": "01:00",
                "recordId": "469505000000272183",
                "listId": "469505000000272183",
                "fromDate": "07-Apr-2019",
                "totalAmount": "100.00",
                "approvedNonBillableHours": "00:00",
                "approvedRatePerHour": 100,
                "approvedTotalAmount": "100.00",
                "ratePerHour": 100,
                "timesheetName": "Weekly Timesheet (07-Apr-2019 - 13-Apr-2019)",
                "currency": "USD",
                "approvedTotalHours": "01:00",
                "status": "Approved"
            }
        ],
        "message": "Data fetched successfully",
        "uri": "/api/timetracker/gettimesheet",
        "status": 0
    }
}

Get timesheet details API

This API is used to get the timesheet details.

Request URL:

https://people.zoho.com/people/api/timetracker/gettimesheetdetails?authtoken=<authtoken>&timesheetId=<timesheetId>&dateFormat=<dateFormat>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*timesheetId<Timesheet Id><Mandatory>Specify the timesheet Id
dateFormat<Date format>yyyy-MM-ddSpecify the format in which the dates should be provided

Success Response Format :

{
    "response": {
        "result": {
            "details": {
                "recordId": <Timesheet Id>,
                "listName": <Timesheet name>,
                "erecno": <Employee Id>,
                "empName": <Employee name>,
                "desc": <Description>,
                "fromDate": <Timesheet start date>,
                "toDate": <Timesheet end date>,
                "owner": <Owner Id>,
                "attachmentId": <Attachment Id>,
                "attachmentName": <Attachment name>,
                "status": <draft | pending | approved | rejected>,
                "currency": <Currency code>,
                "billHours": <Total billable hours>,
                "nonbillHours": <Total non billable hours>,
                "totalHours": <Total hours>,
                "appbillHours": <Approved billable hours>,
                "appnonbillHours": <Approved non billable hours>,
                "apptotalHours": <Approved total hours>,
                "ratePerHour": <Employee rate per hour>,
                "appratePerHour": <Approved rate>,
                "totalAmount": <Total amount>,
                "apptotalAmount": <Total approved amount>
            },
            "tsArr": [ (NOTE: Timelogs belong to this timesheet)
                {
                    "timelogId": <Timelog Id>,
                    "jobId": <Job Id>,
                    "jobName": <Job name>,
                    "projectId": <Project Id>,
                    "projectName": <Project Name>,
                    "clientId": <Client Id>,
                    "erecno": <User Id>,
                    "workDate": <Timelog date>,
                    "hours": <Hours in HH:mm>,
                    "billingStatus": <billable | non-billable>,
                    "approvalStatus": <approved | rejected>,
                    "type": <0 | 1 | 2>, (NOTE: 0 -> Hours based, 1 -> Start/End time based, 2 -> Timer based)
                    "jobIsCompleted": <0 | 1>, (NOTE: 0 -> In-Progress, 1 -> Completed)
                    "jobBillableStatus": <0 | 1>, (NOTE: 0 -> Billable, 1 -> Non-Billable)
                },....
            ]
        },
        "message": "Data fetched successfully",
        "uri": "/api/timetracker/gettimesheetdetails",
        "status": 0
    }
}

Error Response Format :

{
    "response": {
        "message": "Error in fetching data",
        "uri": "/api/timetracker/gettimesheetdetails",
        "errors": [
            {
                "code": <Error Code>,
                "message": <Error Message>
            }
        ],
        "status": 1
    }
}

Error Codes and Messages :

Error CodeError Message
9000Permission denied
9002No <parameter name> parameter specified
9003Wrong value given for <parameter name> parameter
9005Time Tracker tab is disabled

Example :

Request URL :

https://people.zoho.com/people/api/timetracker/gettimesheetdetails?authtoken=9f8d1b973c85dbec3a335ac976319f6d234&timesheetId=469505000000272322&
dateFormat=dd/MM/yyyy

 

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/gettimesheetdetails">
    <status>0</status>
    <message>Data fetched successfully</message>
    <result>
            <tsArr>[{"erecno":"469505000000133005","type":"0","workDate":"07/04/2019","jobName":"System Performance Analysis","approvalStatus":"approved","hours":"02:00","clientId":"469505000000133417","jobIsCompleted":0,"jobBillableStatus":"1","billingStatus":"non-billable","jobId":"469505000000268001","timelogId":"469505000000272225","projectName":"Analysis","projectId":"469505000000267333"}]</tsArr>
            <details>{"owner":"469505000000133005","appbillHours":0,"erecno":"469505000000133005","totalHours":120,"toDate":"07/04/2019","nonbillHours":120,"appnonbillHours":120,"billHours":0,"appratePerHour":100,"fromDate":"07/04/2019","recordId":"469505000000272322","totalAmount":0,"apptotalHours":120,"empName":"Eliza Madison","ratePerHour":100,"apptotalAmount":0,"currency":"USD","attachmentName":"Work Details.pdf","listName":"Daily Timesheet (07-Apr-2019)","attachmentId":"6606691000000018001","desc":"Worked on System Analysis","status":"approved"}</details>
    </result>
</response>
 

JSON response:

{
    "response": {
        "result": {
            "tsArr": [
                {
                    "erecno": "469505000000133005",
                    "type": "0",
                    "workDate": "07/04/2019",
                    "jobName": "System Performance Analysis",
                    "approvalStatus": "approved",
                    "hours": "02:00",
                    "clientId": "469505000000133417",
                    "jobIsCompleted": 0,
                    "jobBillableStatus": "1",
                    "billingStatus": "non-billable",
                    "jobId": "469505000000268001",
                    "timelogId": "469505000000272225",
                    "projectName": "Analysis",
                    "projectId": "469505000000267333"
                }
            ],
            "details": {
                "owner": "469505000000133005",
                "appbillHours": 0,
                "erecno": "469505000000133005",
                "totalHours": 120,
                "toDate": "07/04/2019",
                "nonbillHours": 120,
                "appnonbillHours": 120,
                "billHours": 0,
                "appratePerHour": 100,
                "fromDate": "07/04/2019",
                "recordId": "469505000000272322",
                "totalAmount": 0,
                "apptotalHours": 120,
                "empName": "Eliza Madison",
                "ratePerHour": 100,
                "apptotalAmount": 0,
                "currency": "USD",
                "attachmentName": "Work Details.pdf",
                "listName": "Daily Timesheet (07-Apr-2019)",
                "attachmentId": "6606691000000018001",
                "desc": "Worked on System Analysis",
                "status": "approved"
            }
        },
        "message": "Data fetched successfully",
        "uri": "/api/timetracker/gettimesheetdetails",
        "status": 0
    }
}

Create timesheet API

This API is used to create timesheet.

Request URL:

https://people.zoho.com/people/api/timetracker/createtimesheet?authtoken=<authtoken>&user=<user>&timesheetName=<timesheetName>&description=<description>&dateFormat=<dateFormat>&fromDate=<fromDate>&toDate=<toDate>&billableStatus=<billableStatus>&jobId=<jobId>&projectId=<projectId>&clientId=<clientId>&sendforApproval=<sendforApproval>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*user<Email Id> | <Employee Id> | <Erec No><Mandatory>Specify the user for whom timesheet has to be created
*timesheetName<Timesheet name><Mandatory>Specify the timesheet name
dateFormat<Date format>yyyy-MM-ddSpecify the format in which the dates should be provided
*fromDate<Timesheet from date><Mandatory>Specify the from date
*toDate<Timesheet to date><Mandatory>Specify the to date
description<Description>-Specify the description
jobIdall | <Job Id>allSpecify the job Id
projectIdall | <Project Id>allSpecify the project Id
clientIdall | <Client Id>allSpecify the client Id
billableStatusall | <Billable> | <Non-Billable>allSpecify the billable status of the timelogs
sendforApprovaltrue | falsefalseTo submit the timesheet for approval

Note:

  • To attach a file to the timesheet, set the content type of the request as "multipart/form-data" and attach the file in the request body with the key name as "attachment".
 

Success Response Format :

{
    "response": {
        "result": {
            "timesheetId": [
                <Array of timesheet Ids>
            ]
        },
        "message": <Message>,
        "uri": "/api/timetracker/createtimesheet",
        "status": 0
    }
}

Error Response Format :

{
    "response": {
        "message": "Error in adding data",
        "uri": "/api/timetracker/createtimesheet",
        "errors": [
            {
                "code": <Error Code>,
                "message": <Error Message>
            }
        ],
        "status": 1
    }
}

Error Codes and Messages :

Error CodeError Message
9000Permission denied
9002No <parameter name> parameter specified
9003Wrong value given for <parameter name> parameter
9004Wrong date format given for <parameter name> parameter
9005Time Tracker tab is disabled
9006toDate should be after the fromDate
9007Maximum of one month's data can only be fetched at a time
9009Payment has already been processed for all time logs/timesheets until <pay period processing date>. Hence, you cannot perform this action
9031No timelogs found for these conditions

Example :

Request URL :

https://people.zoho.com/people/api/timetracker/createtimesheet?authtoken=9f8d1b973c85dbec3a335ac976319f6d234&user=eliza.madison@gmail.com×heetName=Daily Timesheet&description=Worked on System Analysis&dateFormat=dd-MM-yyyy&fromDate=07-04-2019&toDate=07-04-2019&billableStatus=all&jobId=all&projectId=all&clientId=all&sendforApproval=true

 

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/createtimesheet">
    <status>0</status>
    <message>Data added successfully</message>
    <result>
        <timesheetId>["469505000000271133"]</timesheetId>
    </result>
</response>
 

JSON response:

{
    "response": {
        "result": {
            "timesheetId": [
                "469505000000271133"
            ]
        },
        "message": "Data added successfully",
        "uri": "/api/timetracker/createtimesheet",
        "status": 0
    }
}

Modify Timesheet API

This API is used to modify timesheet.

Request URL:

https://people.zoho.com/people/api/timetracker/modifytimesheet?authtoken=<authtoken>&timesheetId=<timesheetId>&timesheetName=<timesheetName>&description=<description>&sendforApproval=<sendforApproval>&removeAttachment=<removeAttachment>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*timesheetId<Timesheet Id><Mandatory>Specify the timesheet Id
timesheetName<Timesheet name>-Specify the timesheet name
description<Description>-Specify the description
sendforApprovaltrue | falsefalseTo submit the timesheet for approval
removeAttachmenttrue | falsefalseTo remove the attachment attached to the timesheet

Note:

  • To attach a file to the timesheet, set the content type of the request as "multipart/form-data" and attach the file in the request body with the key name as "attachment".
 

Success Response Format :

{
    "response": {
        "result": {
            "timesheetId": <Timesheet Id>
        },
        "message": <Message>,
        "uri": "/api/timetracker/modifytimesheet",
        "status": 0
    }
}

Error Response Format :

{
    "response": {
        "message": "Error in updating data",
        "uri": "/api/timetracker/modifytimesheet",
        "errors": [
            {
                "code": <Error Code>,
                "message": <Error Message>
            }
        ],
        "status": 1
    }
}

Error Codes and Messages :

Error CodeError Message
9000Permission denied
9002No <parameter name> parameter specified
9003Wrong value given for <parameter name> parameter
9005Time Tracker tab is disabled
9009Payment has already been processed for all time logs/timesheets until <pay period processing date>. Hence, you cannot perform this action

Example :

Request URL :

https://people.zoho.com/people/api/timetracker/modifytimesheet?authtoken=9f8d1b973c85dbec3a335ac976319f6d234&timesheetId=469505000000271189&
timesheetName=Daily Timesheet&description=Worked on System Analysis&sendforApproval=true

 

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/modifytimesheet">
    <status>0</status>
    <message>Data updated successfully</message>
    <result>
        <timesheetId>469505000000271189</timesheetId>
    </result>
</response>
 

JSON response:

{
    "response": {
        "result": {
            "timesheetId": "469505000000271189"
        },
        "message": "Data updated successfully",
        "uri": "/api/timetracker/modifytimesheet",
        "status": 0
    }
}

Resubmit timesheet API

This API is used to resubmit the rejected timesheet.

Note:

  • To resubmit the rejected timesheet, use Modify Timesheet API and add "isResubmit" parameter to the request with the value as "true".
 

Delete timesheets API

This API is used to delete timesheets.

Request URL:

https://people.zoho.com/people/api/timetracker/deletetimesheet?authtoken=<authtoken>&timesheetId=<timesheetId>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*timesheetId<Timesheet Ids><Mandatory>Specify the timesheet Ids (separated by commas). Maximum number of Ids allowed is 1000.

Success Response Format :

{
    "response": {
        "result": {
            "timesheetId": [
                <Array of deleted timesheet Ids>
            ],
            "skippedInfo": [ (NOTE: This key will be available only if any one of the timesheets is not deleted)
                {
                    "timesheetId": [
                        <Array of timesheet Ids which are not deleted>
                    ],
                    "code": <Error Code>,
                    "message": <Error Message>
                },.....
            ]
        },
        "message": "Data deleted successfully",
        "uri": "/api/timetracker/deletetimesheet",
        "status": 0
    }
}

Error Response Format :

{
    "response": {
        "message": "Error in deleting data",
        "uri": "/api/timetracker/deletetimesheet",
        "errors": [
            {
                "code": <Error Code>,
                "message": <Error Message>
            }
        ],
        "status": 1
    }
}

Error Codes and Messages :

Error CodeError Message
9000Permission denied
9005Time Tracker tab is disabled
9009Payment has already been processed for all time logs/timesheets until <pay period processing date>. Hence, you cannot perform this action

Example :

Request URL :

https://people.zoho.com/people/api/timetracker/deletetimesheet?authtoken=9f8d1b973c85dbec3a335ac976319f6d&timesheetId=469505000000272361,
469505000000272374,469505000000176009,469505000000271189,469505000000176019,
469505000000271129

 

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/deletetimesheet">
    <status>0</status>
    <message>Data deleted successfully</message>
    <result>
        <timesheetId>["469505000000272361","469505000000272374"]</timesheetId>
        <skippedInfo>[{"timesheetId":["469505000000176009","469505000000271189"],"code":9000,"message":"Permission Denied"},{"timesheetId":["469505000000176019","469505000000271129"],"code":9009,"message":"Payment has already been processed for all time logs/timesheets until 12-Apr-2019. Hence, you cannot perform this action."}]</skippedInfo>
    </result>
</response>
 

JSON response:

{
    "response": {
        "result": {
            "timesheetId": [
                "469505000000272361",
                "469505000000272374"
            ],
            "skippedInfo": [
                {
                    "timesheetId": [
                        "469505000000176009",
                        "469505000000271189"
                    ],
                    "code": 9000,
                    "message": "Permission Denied"
                },
                {
                    "timesheetId": [
                        "469505000000176019",
                        "469505000000271129"
                    ],
                    "code": 9009,
                    "message": "Payment has already been processed for all time logs/timesheets until 12-Apr-2019. Hence, you cannot perform this action."
                }
            ]
        },
        "message": "Data deleted successfully",
        "uri": "/api/timetracker/deletetimesheet",
        "status": 0
    }
}

Approve timesheet API

This API is used to approve timesheet.

Request URL:

https://people.zoho.com/people/api/timetracker/approvetimesheet?authtoken=<authtoken>&timesheetId=<timesheetId>&approvalStatus=<approvalStatus>&timeLogs=<timeLogs>&comments=<comments>&isAllLevelApprove=<isAllLevelApprove>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*timesheetId<Timesheet Id><Mandatory>Specify the timesheet Id
*approvalStatusapproved | rejected<Mandatory>Specify the approval status
timeLogs{<Timelog Id1>: <approved | rejected>,<Timelog Id2>: <approved | rejected>}-Specify the time logs of the timesheet along with the approval status in JSON format as shown. If this is not specified, all the time logs of the timesheet will either be approved or rejected based on the "approvalStatus" parameter.
isAllLevelApprovetrue | falsefalseTo approve the timesheet on behalf of all the approvers.
comments<Approval comments>-Specify the approval comments.

Success Response Format :

{
    "response": {
        "result": {
            "timesheetId": <Timesheet Id>
        },
        "message": <Message>,
        "uri": "/api/timetracker/approvetimesheet",
        "status": 0
    }
}

Error Response Format :

{
    "response": {
        "message": "Error in approving timesheet",
        "uri": "/api/timetracker/approvetimesheet",
        "errors": [
            {
                "code": <Error Code>,
                "message": <Error Message>
            }
        ],
        "status": 1
    }
}

Error Codes and Messages :

Error CodeError Message
9000Permission denied
9005Time Tracker tab is disabled
9008Timesheet not found
9009Payment has already been processed for all time logs/timesheets until <pay period processing date>. Hence, you cannot perform this action
9032Timesheet is either deleted or resubmitted.

Example :

Request URL :

https://people.zoho.com/people/api/timetracker/approvetimesheet?authtoken=9f8d1b973c85dbec3a335ac976319f6d234×heetId=469505000000271209&approvalStatus=
approved&timeLogs={"469505000000272225":"approved","469505000000272083":"rejected"}&comments=Partially Approved&isAllLevelApprove=false

 

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/approvetimesheet">
    <status>0</status>
    <message>Timesheet approved successfully</message>
    <result>
        <timesheetId>469505000000271209</timesheetId>
    </result>
</response>
 

JSON response:

{
    "response": {
        "result": {
            "timesheetId": "469505000000271209"
        },
        "message": "Timesheet approved successfully",
        "uri": "/api/timetracker/approvetimesheet",
        "status": 0
    }
}