Jobs API

Purpose

These APIs are used to get the list of jobs, job details, add job, modify job, change the job status and delete the job(s).

Get jobs API

This API is used to get the list of jobs.

Request URL:

https://people.zoho.com/people/api/timetracker/getjobs?authtoken=<authtoken>&assignedTo=<assignedTo>&assignedBy=<assignedBy>&jobStatus=<jobStatus>&dateFormat=<dateFormat>&projectId=<projectId>&clientId=<clientId>&isAssigneeCount=<isAssigneeCount>&fetchLoggedHrs=<fetchLoggedHrs>&sIndex=<sIndex>&limit=<limit>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*assignedToall | <Email Id> | <Employee Id> | <Erec No><Mandatory>Specify the user whose jobs have to be fetched
assignedByall | <Email Id> | <Employee Id> | <Erec No>allSpecify the user by whom the jobs are assigned
jobStatusall | in-progress | completedallSpecify the job status
projectIdall | <project Id>allSpecify the project Id which the jobs are associated with
clientIdall | <client Id>allSpecify the client Id
dateFormat<date format><Company date format>Specify the format in which the dates should be provided
isAssigneeCounttrue | falsefalseFetches the number of users mapped to the job
fetchLoggedHrstrue | falsefalseFetches the total hours logged for the job
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": [
            
            {
                
                "jobId": <Job Id>,
                "jobName": <Job name>,
                
                "projectId": <Project Id>,
                "projectName": <Project name>,
                
                "clientId": <Client Id>,
                
                "clientName": <Client name>,
                "fromDate": <Start date>,
                
                "toDate": <End date>,
                
                "description": <Description>,
                
                "jobBillableStatus": <Billable | Non-Billable>,
                
                "ratePerHour": <Rate per hour>,
                
                "jobStatus": <In-Progress | Completed>
                "hours": <Estimated hours in HH:mm>,
                
                "totalhours": <Total hours logged for the job in HH:mm>, (NOTE: this key will be available only if "fetchLoggedHrs" parameter is set as true in the request)     
                
                "owner": <Owner Id>,
                "assignedBy": <Owner name>,
                
                "assigneeCount": <No of assignees>, (NOTE: this key will be available only if "isAssigneeCount" parameter is set as true in the request)
                
                "isDeleteAllowed": <true | false>
            },....
        
         ],
        
         "message": "Data fetched successfully",
        
         "uri": "/api/timetracker/getjobs",
        
         "isNextAvailable": true, (NOTE: this key will not be available if there is no more data)
        
         "status": 0
    
     }

}

Error Response Format :

{
    "response": {
        "message": "Error in fetching data",
        "uri": "/api/timetracker/getjobs",
        "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

Example :

Request URL :

https://people.zoho.com/people/api/timetracker/getjobs?authtoken=9f8d1b973c85dbec3a335ac976319f6d234&assignedTo=eliza.madison@gmail.com&assignedBy=
eliza.madison@gmail.com&jobStatus=in-progress&dateFormat=dd/MM/yyyy&projectId=469505000000267333&clientId=469505000000133417&
isAssigneeCount=true&fetchLoggedHrs=true&sIndex=0&limit=1

 

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/getjobs">
    <status>0</status>
    <message>Data fetched successfully</message>
    <isNextAvailable>true</isNextAvailable>
    <result>
        <job>
            <jobName>System Performance Analysis</jobName>
            <owner>469505000000133005</owner>
            <jobStatus>In-Progress</jobStatus>
            <hours>57:00</hours>
            <assignedBy>Eliza Madison</assignedBy>
            <clientId>469505000000133417</clientId>
            <clientName>Adamo Meyrick</clientName>
            <toDate>12/04/2019</toDate>
            <description>To analyse the system performance</description>
            <jobBillableStatus>Non-Billable</jobBillableStatus>
            <assigneeCount>26</assigneeCount>
            <isDeleteAllowed>true</isDeleteAllowed>
            <fromDate>05/04/2019</fromDate>
            <jobId>469505000000268001</jobId>
            <ratePerHour>0.0</ratePerHour>
            <totalhours>52:00</totalhours>
            <projectName>Analysis</projectName>
            <projectId>469505000000267333</projectId>
        </job>
    </result>
</response>
 

JSON response:

{
    
    "response": {
        
        "result": [
            
           {
                
              "jobName": "System Performance Analysis",
                
              "owner": "469505000000133005",
                
              "jobStatus": "In-Progress",
                
              "hours": "57:00",
                
              "assignedBy": "Eliza Madison",
                
              "clientId": "469505000000133417",
                
              "clientName": "Adamo Meyrick",
                
              "toDate": "12/04/2019",
                
              "description": "To analyse the system performance",
                
              "jobBillableStatus": "Non-Billable",
                
              "assigneeCount": 26,
                
              "isDeleteAllowed": true,
                
              "fromDate": "05/04/2019",
                
              "jobId": "469505000000268001",
                
              "ratePerHour": 0,
                
              "totalhours": "52:00",
                
              "projectName": "Analysis",
                
              "projectId": "469505000000267333"
            
          }
        
       ],
        
    "message": "Data fetched successfully",
        
    "uri": "/api/timetracker/getjobs",
        
    "isNextAvailable": true,
        
    "status": 0
    
  }
​
}

Get job details API

This API is used to get the job details.

Request URL:

https://people.zoho.com/people/api/timetracker/getjobdetails?authtoken=<authtoken>&jobId=<jobId>&dateFormat=<dateFormat>&includeDept=<includeDept>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*jobId<jobId><Mandatory>Specify the job Id
dateFormat<dateFormat><Company date format>Specify the date format
includeDepttrue | falsefalseTo fetch the departments that are assigned to this Job

Success Response Format :

{
    "response": {
        "result": [
            {
                "jobId": <Job Id>,
                "jobName": <Job name>,
                "projectId": <Project Id>
                "projectName": <Project name>,
                "clientId": <Client Id>,
                "clientName": <Client name>,
                "fromDate": <Start date>,
                "toDate": <End date>,
                "description": <Description>,
                "jobBillableStatus": <Billable | Non-Billable>,
                "ratePerHour": <Rate per hour>,
                "jobStatus": <In-Progress | Completed>,
                "hours": <Estimated hours in HH:mm>,
                "totalhours": <Total hours logged for the job in HH:mm>,
                "owner": <Owner Id>,
                "assignedBy": <Owner name>,
                "isDeleteAllowed": <true | false>,
                "jobDepts": [ (NOTE : this key will be available only if the "includeDept" parameter is set as true in the request)
                    {
                        "deptName": <Department name>,
                        "deptId": <Department Id>
                    }
                ],
                "assignees": [
                    {
                        "hours": <Estimated hours in HH:mm>,
                        "erecno": <Erec no>,
                        "rate": <Assignee rate per hour>,
                        "name": <Name>,
                        "totalhours": <Hours logged by the assignee in HH:mm>
                    },
                ]
            }
        ],
        "message": "Data fetched successfully",
        "uri": "/api/timetracker/getjobdetails",
        "status": 0
    }
}

Error Response Format :

{
    "response": {
        "message": "Error in fetching data",
        "uri": "/api/timetracker/getjobdetails",
        "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

Example :

Request URL:

https://people.zoho.com/people/api/timetracker/getjobdetails?authtoken=9f8d1b973c85dbec3a335ac976319f6d234&jobId=469505000000268001&dateFormat=dd-MMM-yyyy&includeDept=true

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/getjobdetails">
    <status>0</status>
    <message>Data fetched successfully</message>
    <result>
        <job>
            <jobName>System Performance Analysis</jobName>
            <owner>469505000000133005</owner>
            <jobStatus>In-Progress</jobStatus>
            <hours>57:00</hours>
            <assignedBy>Eliza Madison</assignedBy>
            <clientId>469505000000133417</clientId>
            <clientName>Adamo Meyrick</clientName>
            <toDate>12-Apr-2019</toDate>
            <jobDepts>[{"deptName":"HR","deptId":"469505000000133001"}]</jobDepts>
            <description>To analyse the system performance</description>
            <assignees>[{"hours":"07:00","erecno":"469505000000133005","rate":100,"name":"Eliza Madison","totalhours":"12:00"},{"hours":"50:00","erecno":"469505000000133275","rate":70,"name":"Patrick Dohnman","totalhours":"40:00"}]</assignees>
            <jobBillableStatus>Non-Billable</jobBillableStatus>
            <isDeleteAllowed>true</isDeleteAllowed>
            <fromDate>05-Apr-2019</fromDate>
            <jobId>469505000000268001</jobId>
            <ratePerHour>0.0</ratePerHour>
            <totalhours>52:00</totalhours>
            <projectName>Analysis</projectName>
            <projectId>469505000000267333</projectId>
        </job>
    </result>
</response>
 

JSON response:

{
    "response": {
        "result": [
            {
                "jobName": "System Performance Analysis",
                "owner": "469505000000133005",
                "jobStatus": "In-Progress",
                "hours": "57:00",
                "assignedBy": "Eliza Madison",
                "clientId": "469505000000133417",
                "clientName": "Adamo Meyrick",
                "toDate": "12-Apr-2019",
                "jobDepts": [
                    {
                        "deptName": "HR",
                        "deptId": "469505000000133001"
                    }
                ],
                "description": "To analyse the system performance",
                "assignees": [
                    {
                        "hours": "07:00",
                        "erecno": "469505000000133005",
                        "rate": 100,
                        "name": "Eliza Madison",
                        "totalhours": "12:00"
                    },
                    {
                        "hours": "50:00",
                        "erecno": "469505000000133275",
                        "rate": 70,
                        "name": "Patrick Dohnman",
                        "totalhours": "40:00"
                    }
                ],
                "jobBillableStatus": "Non-Billable",
                "isDeleteAllowed": true,
                "fromDate": "05-Apr-2019",
                "jobId": "469505000000268001",
                "ratePerHour": 0,
                "totalhours": "52:00",
                "projectName": "Analysis",
                "projectId": "469505000000267333"
            }
        ],
        "message": "Data fetched successfully",
        "uri": "/api/timetracker/getjobdetails",
        "status": 0
    }
}

Form based API to get jobs

  • 
 Refer API reference page to fetch all the records using the form API.
 

Add job API (deprecated - Instead use this API)

This API is used to add job.

Request URL:

https://people.zoho.com/people/api/timetracker/addjob?authtoken=<authtoken>&jobName=<jobName>&assignees=<assignees>&description=<description>&dateFormat=<dateFormat>&fromDate=<fromDate>&toDate=<toDate>&projectId=<projectId>&ratePerHour=<ratePerHour>

Request parameter:

ParameterDescription
*authtokenSpecify the authentication token
*jobNameSpecify the job name
*assigneesSpecify the assignees in JSON array format as [{"assignedTo":<Email Id> | <Employee Id> | <Erec No>, "hours":<Estimated hours in HH:mm>,"rate":<Rate per hour>},...]
projectIdSpecify the Project Id
dateFormatSpecify the date format
fromDateSpecify the start date
toDateSpecify the end date
descriptionSpecify the description
ratePerHourSpecify the job rate per hour

Example :

Request URL :

https://people.zoho.com/people/api/timetracker/addjob?authtoken=48552851f39b2455991e8eeab1a67d80&jobName=Performance Analysis&assignees=[{"assignedTo": "293141000000061007","hours":"20","rate":"100"}]&description=To analyse the employees' performance&dateFormat=dd-MMM-yyyy&fromDate=01-Apr-2019&toDate=30-Apr-2019&projectId=293141000000065149&ratePerHour=200

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/addjob">
    <status>0</status>
    <message>Job added Successfully</message>
    <result>
        <jobId>293141000000061234</jobId>
    </result>
</response>
 

JSON response:

{
    "response": {
        "result": [
            {
                "jobId": "293141000000061234"
            }
        ],
        "message": "Job added Successfully",
        "uri": "/api/timetracker/addjob",
        "status": 0
    }
}

Form based API to add job

This API is used to add job.

Request URL:

https://people.zoho.com/people/api/forms/<inputType>/<formLinkName>/insertRecord?authtoken=<token>&inputData=<inputData>

Request parameter:

ParameterDescription
*authtokenSpecify the authentication token
*formLinkNameSpecify the formLinkName as "P_TimesheetJob"
*inputTypeSpecify the inputType as either "xml" or "json"
*inputDataXML input: <Request><Record><field name="LabelName1">value1</field><field name="LabelName2">value2</field><field name="LabelName3">value3</field></Record></Request>
JSON input:{LabelName1:'value1',LabelName2:'value2',LabelName3:'value3'}

Example :

XML Request :

https://people.zoho.com/people/api/forms/xml/P_TimesheetJob/insertRecord?authtoken=9f8d1b973c85dbec3a335ac976319f6d&inputData=<Request><Record><field name="Job_Name">Performance Analysis</field><field name="StartDate">01-Apr-2019</field><field name="EndDate">30-Apr-2019</field><field name="Project">469505000000267333</field><field name="Assignees">469505000000133005;469505000000133275</field><field name="AssigneeHours">20;20</field><field name="AssigneeRate">100;100</field><field name="departmentIds">469505000000133001</field></Record></Request>

JSON Request :

https://people.zoho.com/people/api/forms/json/P_TimesheetJob/insertRecord?authtoken=9f8d1b973c85dbec3a335ac976319f6d234&inputData={"Job_Name":"Performance Analysis","StartDate":"01-Apr-2019","EndDate":"30-Apr-2019","Project":"469505000000267333","Assignees":"469505000000133005;469505000000133275",
"AssigneeHours":"20;20","AssigneeRate":"100;100","departmentIds":"469505000000133001"}

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/forms/xml/P_TimesheetJob/insertRecord">
    <status>0</status>
    <message>Data added successfully</message>
    <result>
            <pkId>469505000000271003</code>
            <message>Successfully Added</message>
   </result>
</response>
 

JSON response:

{
    "response": {
        "result": {
            "pkId": "469505000000271003",
            "message": "Successfully Added"
        },
        "message": "Data added successfully",
        "uri": "/api/forms/json/P_TimesheetJob/insertRecord",
        "status": 0
    }
}

Note:

  • Please refer API reference or Use the Fetch Component API to get the list of form components.
  • To assign job to all users mention as 'All' for 'Assignees' in the inputData.

Modify job API (deprecated - Instead use this API)

This API is used to modify job.

Request URL:

https://people.zoho.com/api/timetracker/modifyjob?authtoken=<authtoken>&jobId=<jobId>&jobName=<jobName>&assignees=<assignees>&description=<description>&dateFormat=<dateFormat>&fromDate=<fromDate>&toDate=<toDate>&projectId=<projectId>&ratePerHour=<ratePerHour>

Request parameter:

ParameterDescription
*authtokenSpecify the authentication token
*jobIdSpecify the job Id
jobNameSpecify the job name
assigneesSpecify the assignees in JSON array format as [{"assignedTo":<Email Id> | <Employee Id> | <Erec No>, "hours":<Estimated hours in HH:mm>,"rate":<Rate per hour>},...]
projectIdSpecify the Project Id
dateFormatSpecify the date format
fromDateSpecify the start date
toDateSpecify the end date
descriptionSpecify the description
ratePerHourSpecify the job rate per hour

Example :

Request URL :

https://people.zoho.com/api/timetracker/modifyjob?authtoken=48552851f39b2455991e8eeab1a67d80&jobId=293141000000061234&jobName=Performance Analysis&assignees=[{"assignedTo": "293141000000061007","hours":"20","rate":"100"}]&description=To analyse the employees' performance&dateFormat=dd-MMM-yyyy&fromDate=01-Apr-2019&toDate=30-Apr-2019&projectId=293141000000065149&ratePerHour=200

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/modifyjob">
    <status>0</status>
    <message>Job details modified Successfully</message>
    <result>
        <jobId>293141000000061234</jobId>
    </result>
</response>
 

JSON response:

{
    "response": {
        "result": [
            {
                "jobId": "293141000000061234"
            }
        ],
        "message": "Job details modified Successfully",
        "uri": "/api/timetracker/modifyjob",
        "status": 0
    }
}

Form based API to modify job

This API is used to modify job.

Request URL:

https://people.zoho.com/people/api/forms/<inputType>/<formLinkName>/updateRecord?authtoken=<token>&recordId=<recordId>&inputData=<inputData>

Request parameter:

ParameterDescription
*authtokenSpecify the authentication token
*formLinkNameSpecify the formLinkName as "P_TimesheetJob"
*inputTypeSpecify the inputType as either "xml" or "json"
*recordIdSpecify the job Id
*inputDataXML input: <Request><Record><field name="LabelName1">value1</field><field name="LabelName2">value2</field><field name="LabelName3">value3</field></Record></Request>
JSON input:{LabelName1:'value1',LabelName2:'value2',LabelName3:'value3'}

Example :

XML Request :

https://people.zoho.com/people/api/forms/xml/P_TimesheetJob/updateRecord?authtoken=9f8d1b973c85dbec3a335ac976319f6d234&recordId=469505000000271003&inputData=<Request><Record><field name="Job_Name">Performance Analysis</field><field name="StartDate">01-Apr-2019</field><field name="EndDate">30-Apr-2019</field><field name="Project">469505000000267333</field><field name="Assignees">469505000000133005;469505000000133275</field><field name="AssigneeHours">20;20</field><field name="AssigneeRate">100;100</field><field name="departmentIds">469505000000133001</field></Record></Request>

JSON Request :

https://people.zoho.com/people/api/forms/json/P_TimesheetJob/updateRecord?authtoken=9f8d1b973c85dbec3a335ac976319f6d234&recordId=469505000000271003&inputData={"Job_Name":"Performance Analysis","StartDate":"01-Apr-2019","EndDate":"30-Apr-2019","Project":"469505000000267333","Assignees":"469505000000133005;469505000000133275",
"AssigneeHours":"20;20","AssigneeRate":"100;100","departmentIds":"469505000000133001"}

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/forms/xml/P_TimesheetJob/updateRecord">
    <status>0</status>
    <message>Data updated successfully</message>
    <result>
            <pkId>469505000000271003</code>
            <message>Successfully Updated</message>
   </result>
</response>
 

JSON response:

{
    "response": {
        "result": {
            "pkId": "469505000000271003",
            "message": "Successfully Updated"
        },
        "message": "Data updated successfully",
        "uri": "/api/forms/json/P_TimesheetJob/updateRecord",
        "status": 0
    }
}

Note:

  • Please refer API reference or Use the Fetch Component API to get the list of form components.
  • To assign job to all users mention as 'All' for 'Assignees' in the inputData.

Change job status API

This API is used to change the job status.

Request URL:

https://people.zoho.com/people/api/timetracker/modifyjobstatus?authtoken=<authtoken>&jobId=<jobId>&jobStatus=<jobStatus>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*jobId<jobId><Mandatory>Specify the job Id
*jobStatusIn-Progress | Completed<Mandatory>Specify the job status

Success Response Format :

{
    "response": {
        "message": "Job Status changed Successfully",
        "uri": "/api/timetracker/modifyjobstatus",
        "status": 0
    }
}

Error Response Format :

{
    "response": {
        "message": "Error in changing job status",
        "uri": "/api/timetracker/modifyjobstatus",
        "errors": {
            "code": <Error Code>,
            "message": <Error Message>
        },
        "status": 1
    }
}

Error Codes and Messages :

Error CodeError Message
8000No <parameter name> parameter specified
8001Wrong value for <parameter name> parameter
8006Timer is currently running for this job
8006Cannot reopen the job since the project associated with this job is completed and you do not have permission to reopen the project

Example :

Request URL :

https://people.zoho.com/people/api/timetracker/modifyjobstatus?authtoken=9f8d1b973c85dbec3a335ac976319f6d234&jobId=469505000000267495&jobStatus=In-Progress

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/timetracker/modifyjobstatus">
    <status>0</status>
    <message>Job Status changed Successfully</message>
</response>
 

JSON response:

{
    "response": {
        "message": "Job Status changed Successfully",
        "uri": "/api/timetracker/modifyjobstatus",
        "status": 0
    }
}

Delete jobs API

This API is used to delete jobs.

Request URL:

https://people.zoho.com/people/api/timetracker/deletejob?authtoken=<authtoken>&jobId=<jobId>

Request parameter:

ParameterValues AllowedDefault ValueDescription
*authtoken<authtoken><Mandatory>Specify the authentication token
*jobId<jobIds><Mandatory>Specify the job Id (separated by commas). Maximum number of Ids allowed is 100.

Success Response Format :

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

Error Response Format :

{
    "response": {
        "message": <Message>, (NOTE: Refer the table below)
        "uri": "/api/timetracker/deletejob",
        "errors": {
            "code": <Error Code>,
            "message": <Error Message>
        },
        "status": 1
    }
}
Messages
Error in deleting job(s)
One or more specified jobs are not deleted

Error Codes and Messages :

Error CodeError Message
8000No <parameter name> parameter specified
8001Wrong value for <parameter name> parameter
8004Job cannot be deleted since timer is running

Example :

Request URL:

https://people.zoho.com/people/api/timetracker/deletejob?authtoken=9f8d1b973c85dbec3a335ac976319f6d234&jobId=469505000000223813

XML response:

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

JSON response:

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