API Catalog

Retrieve PY E-Timesheets By Code

18 Jul 2025
9 Minutes to read

Print
Dark
Light

Retrieve PY E-Timesheets By Code

Updated on 18 Jul 2025
9 Minutes to read

Print
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback!

Get

/hcm-rest-api/rest/1/pyetimesheet

Overview

This API enables querying timesheet records within CMiC’s Payroll E-time and Employee Self-Service (ESS) applications. It provides programmatic access to manage time entries, allowing integrations to maintain accurate and up-to-date timesheet data across both platforms.

Notes

To use this API, the API service account must have both ESS security and user security permissions configured. For detailed guidance on setting up access to ESS, please visit:
ESS Registration and Access Setup

Further, to efficiently query this view, it is essential to use finders, as the view supports querying only through primary keys such as 'year', ‘period’, ‘payrun’, ‘employee'. This design ensures precise and targeted data retrieval based on key identifiers.

E-time > E-timesheet Entry

ESS > Timesheet

Reference Article

Path Parameters

Parameter	Description	Example
/VUUID	The VUuid attribute is the Unique row ID

Query Standards

Key	Recommended	Description
finder	Yes	Filters data based on attributes. See finder details below. Finders can be combined using a comma delimiter between parameters that implies an "and" statement. For more information on using the finder functionality please see Best Practice
limit	Yes	A limit restricts the number of resources returned inside the resource collection. If the limit exceeds the resource count, then the framework will return all available resources. For additional information on using the limit functionality please visit Best Practice
offset	Yes	The offset skips a specified number of items in a data list before it starts showing results. For example, if you set an offset of 10, it skips the first 10 items and begins showing from the 11th item. For additional information on using Offset functionality please visit Best Practice
orderBy	Yes	The orderBy attribute retrieves rows using an order ensuring the response payload displays data in the order supplied in the URL parameter using the GET method. For more information on using orderBy functionality please visit Best Practice

pyetimesheet Finders

Finder	Parameter	Data Type	Description	Example
PrimaryKey	TshVUuid	string	This optional query parameter enables you to retrieve records by specifying the 'VUuid'. Use this to directly access a specific record when you know its unique identifier.	/12FFD2D774D9F19DE06327261DACDB17
selectETimeSheet	CompCode	string	This finder is designed to retrieve records based on the company code.	/hcm-rest-api/rest/1/pyetimesheet?finder=selectETimeSheet;CompCode=ZZ
selectETimeSheet	Period	integer	This finder is designed to retrieve records based on the pay period code.	/hcm-rest-api/rest/1/pyetimesheet?finder=selectETimeSheet;Period=3
selectETimeSheet	PrnCode	string	This finder is designed to retrieve records based on the pay run code.	/hcm-rest-api/rest/1/pyetimesheet?finder=selectETimeSheet;PrnCode=BIWK
selectETimeSheet	Year	integer	This finder is designed to retrieve records based on the pay year code.	/hcm-rest-api/rest/1/pyetimesheet?finder=selectETimeSheet;Year=2024

pyetimesheet Attributes

CMiC UI Fieldname	Object	Name	Description	Type	Data Length	Example
Access Code	pyetimesheet	TshAccessCode	The users access code allowing them permission to create, edit and/or approve a timesheet	string	30	For example, INTEGRATIONSUSER. Note: due to security reasons, this value returns ‘null’ in the API response.
Approval Status	pyetimesheet	TshAprvStatus	The status of the timesheet from Approved to Unapproved.Note: To be able to insert a timesheet as approved, the access code used for the API service account must be setup as an approver under Access Code Administration.	string	1	Scenario 1: A timesheet is created by a 3rd-party system and must be inserted in CMiC as fully approved — skipping internal submission/approval workflow.TshAprvStatus = ATshSubmitFlag = YScenario 2: Timesheets are created in CMiC from the 3rd party, but NOT approved yet — they must enter the CMiC workflow as submitted and pending approval.TshAprvStatus = PTshSubmitFlag = YScenario 3: Timesheets are created but not submitted and not approved — they’re just drafts/saved only.TshAprvStatus = YTshSubmitFlag = N
Category type	pyetimesheet	TshCategory	A unique identified code assigned to a cost code. This code is used to reference and manage job/cost code/category combination for tracking posted units & costs. Ex: L, M, E, W etc, corresponding to Labor, Subcontract, Equipment, Material etc.The category code setup is user-defined alphanumeric text field and can be different by customer.	string	16	L – LaborM – MaterialE – EquipmentW – Work Order
Comments	pyetimesheet	TshComment	A free-text field used to capture additional context, notes, or explanations related to a specific timesheet entry. Comments can be used for approvals, clarifications, or internal tracking purposes.	string	2000	“Hours split between 2 jobs for this week.”
Company Code	pyetimesheet	TshCompCode	The company is the entity in CMiC that the employee or time should be allocated to.	string	8	‘001’ CMiC Construction, ltd.
Date	pyetimesheet	TshDate	The timesheet date is the effective date the productivity is accumulated on.	datetime		2025-06-24
Department	pyetimesheet	TshDeptCode	The Department Code is used if the time created should be reported is not job costed, but should be charged to GL Department and Account instead.	string	6	‘00’‘040’
Document Code	pyetimesheet	TshDocumentNo	The document code is autopopulated by CMiC on timesheet injection.	string	30	GH001202502
Employee Number	pyetimesheet	TshEmpNo	An existing CMiC employee number associated with the submitted timesheet.	string	16	2415
General Ledger Account Code	pyetimesheet	TshGlAccCode	The GL account associated with time submitted outside of job costing.	string	16	1000
Hours	pyetimesheet	TshHours	The number of timesheet hours entered for the employee associated with this submission. Time must be entered in whole numbers or increments of 0.25 (e.g., 1.00, 1.25, 1.50, 1.75)	number		8.25
Hours Code	pyetimesheet	TshHoursCode	The hour code determines the multiplier used by CMiC to calculate the hours once created. For example, for regular hours, NWHR is used, which is defined in the system by default at 1.0 X hours.	string	4	NWHR – Normal (regular) hoursOVHR – Overtime hoursDTHR – Double Time hoursOTHR – Other hours; self-defined hours beyond the standards Normal, Overtime and Double time.
Job Code	pyetimesheet	TshJobCode	Job Code - A code that uniquely identifies the job within a company or business unit. Each job can consist of one or many phase/cost codes and categories assigned to it.The Job code setup is user-defined alphanumeric text field and can be different by customer.	string	10	100
Other Hours Type	pyetimesheet	TshOhType	Other hours type are user defined hours used to assign hours beyond the standard, regular, overtime or double-time hours. For a listing of other hour types predefined in CMiC use the Employee Hour Types API	string	4	Default OTHR
Phase Code	pyetimesheet	TshPhase	Also known as ‘Cost Code’ - A unique code under a given job used to track the posted costs and units. Each phase code (Also known as cost code) can have one or more categories assigned and can give more flexibility and help track the job’s cost elements at a finer level.	string	16	15090
Pay Period	pyetimesheet	TshPprPeriod	Defined time intervals, ‘pay periods’ (e.g., weekly, biweekly) during which employees record their hours worked. These periods align with payroll cycles to ensure accurate calculation and processing of wages.	integer	2	For weekly timesheets – 1 to 52
Pay Year	pyetimesheet	TshPprYear	The calendar or fiscal year in which payroll transactions, such as timesheets and pay runs, are recorded and reported for tax and accounting purposes.	integer	4	2025
Pay run Code	pyetimesheet	TshPrnCode	A unique identifier assigned to a specific payroll processing cycle, used to group and track employee payments, deductions, and related payroll transactions within a given pay period.	string	4	WK – weekly,BIWK – BiweeklyMTH - Monthly
Sequence Number	pyetimesheet	TshSeqNo	The timesheet sequence number auto-generated by CMiC on insert. It’s used to sort timesheets created for a given combination of company, document number, period, and year.	integer		1, 2, 3, 4, etc.
Submitted Flag	pyetimesheet	TshSubmitFlag	The Submit flag, when set to ‘Y’, marks the timesheet as complete and ready for approval. Once submitted, the record becomes locked for editing via the API and must be unsubmitted by an approver within CMiC before any further changes can be made.	string	1	Scenario 1: A timesheet is created by a 3rd-party system and must be inserted in CMiC as fully approved — skipping internal submission/approval workflow.TshAprvStatus = ATshSubmitFlag = YScenario 2: Timesheets are created in CMiC from the 3rd party, but NOT approved yet — they must enter the CMiC workflow as submitted and pending approval.TshAprvStatus = PTshSubmitFlag = YScenario 3: Timesheets are created but not submitted and not approved — they’re just drafts/saved only.TshAprvStatus = YTshSubmitFlag = N
Unique Identifier	pyetimesheet	TshVUuid	The unique identifier (ID) for the timesheet record, automatically generated by CMiC when the record is created. This ID can be used to query or reference the specific timesheet record.	string	64	12FFD2D774D9F19DE06327261DACDB17
Work Company code	pyetimesheet	TshWorkCompCode	The work company code is used to specify a different company for the timesheet entry than the one defined in the company code (tshcompcode) field. This allows productivity costs to be allocated to a company other than the one the employee reports to.	string	8	002
Trade Code	pyetimesheet	TshTradeCode	The trade code identifies the construction craft group an employee belongs to. In CMiC, trades are used to group associated pay rates, benefits, and classifications.To query predefined trades in CMiC, use Retrieve PY Trades by VUUID	string	30	CARP
Union Code	pyetimesheet	TshUnionCode	The union code identifies the union an employee belongs to. In CMiC, unions are also used to group associated pay rates, benefits, and deductions.	string	4	614
Work Breakdown Structure Code 1	pyetimesheet	TshWbsvCode1	This field indicates whether the timesheet line has access to Work Breakdown Structure (WBS) codes. CMiC supports up to four WBS codes, which can be used to default various values onto the timesheet line. By default, WBS Code 1 is set to the Potential Change Item (PCI) number.	string	60	WBS1
Work Breakdown Structure Code 2	pyetimesheet	TshWbsvCode2	This field indicates whether the timesheet line has access to Work Breakdown Structure (WBS) codes. CMiC supports up to four WBS codes, which can be used to default various values onto the timesheet line.	string	60	WBS2
Work Breakdown Structure Code 3	pyetimesheet	TshWbsvCode3	This field indicates whether the timesheet line has access to Work Breakdown Structure (WBS) codes. CMiC supports up to four WBS codes, which can be used to default various values onto the timesheet line.	string	60	WBS3
Work Breakdown Structure Code 4	pyetimesheet	TshWbsvCode4	This field indicates whether the timesheet line has access to Work Breakdown Structure (WBS) codes. CMiC supports up to four WBS codes, which can be used to default various values onto the timesheet line.	string	60	WBS4

Security

HTTP

Type basic

Basic authentication

Query parameters

finder

string

ExampleselectETimeSheet; PrnCode=SM, Period=5, CompCode=001, Year=2015

limit

integer

Example500

offset

integer

Example0

totalResults

boolean

Exampletrue

orderBy

string

ExampleTshVUuid:desc

Responses

200

Headers

Content-Type

string

Exampleapplication/vnd.oracle.adf.resourcecollection+json

{
  "items": [
    {
      "TshAccessCode": null,
      "TshAprvStatus": "A",
      "TshCategory": "L",
      "TshComment": null,
      "TshCompCode": "001",
      "TshDate": "2015-03-01",
      "TshDeptCode": "113",
      "TshDocumentNo": "MASTER201505",
      "TshEmpNo": "1010",
      "TshGlAccCode": "50010",
      "TshHours": null,
      "TshHoursCode": "NWHR",
      "TshJobCode": "14001",
      "TshOhType": null,
      "TshPhase": "00020",
      "TshPprPeriod": 5,
      "TshPprYear": 2015,
      "TshPrnCode": "SM",
      "TshSeqNo": 73323,
      "TshSubmitFlag": "Y",
      "TshVUuid": "B41F554B69E1A908E053B08610AC2C73",
      "TshWorkCompCode": "001",
      "TshBatchFlag": null,
      "TshTradeCode": "DIR2",
      "TshUnionCode": null,
      "TshWbsvCode1": null,
      "TshWbsvCode2": null,
      "TshWbsvCode3": null,
      "TshWbsvCode4": null,
      "links": [
        {
          "rel": "self",
          "href": "http://mobtest.cmiccloudr12.com:80/cmictestrti/hcm-rest-api/rest/1/pyetimesheet/B41F554B69E1A908E053B08610AC2C73",
          "name": "pyetimesheet",
          "kind": "item"
        },
        {
          "rel": "canonical",
          "href": "http://mobtest.cmiccloudr12.com:80/cmictestrti/hcm-rest-api/rest/1/pyetimesheet/B41F554B69E1A908E053B08610AC2C73",
          "name": "pyetimesheet",
          "kind": "item"
        }
      ]
    }
  ],
  "count": 1,
  "hasMore": false,
  "limit": 25,
  "offset": 0,
  "links": [
    {
      "rel": "self",
      "href": "http://mobtest.cmiccloudr12.com:80/cmictestrti/hcm-rest-api/rest/1/pyetimesheet",
      "name": "pyetimesheet",
      "kind": "collection"
    }
  ]
}

object

What's Next

Retrieve a Specific PY E-Timesheet

Retrieve PY E-Timesheets By Code

Overview

Notes

UI Navigation

Reference Article

Path Parameters

Query Standards

pyetimesheet Finders

pyetimesheet Attributes

What's Next

Contact Us