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.
UI Navigation
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 | Data Filtering requirements |
| 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 | Data Filtering requirements |
| 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 | Data Filtering requirements |
| 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 | Data Filtering requirements |
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
OK
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