> ## Documentation Index > Fetch the complete documentation index at: https://developers.cmicglobal.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve PY E-Timesheets By Code > ## 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](https://docs.cmicglobal.com/portal/Content/E_Reference_Material/ESS_Employees/Reference/Overview/ESS_Registration.htm?Highlight=ESS) 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 * [E-Time](https://docs.cmicglobal.com/portal/Content/E_Reference_Material/PYE_-_E-Time/Reference/E-Timesheet/Personal_Time/E_Timesheet_Entry.htm?Highlight=e-timesheet) * [Employee Self-Service (ESS)](https://docs.cmicglobal.com/portal/Content/E_Reference_Material/ESS_Employees/Reference/Overview/ESS_Employees.htm) ## 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 | ## OpenAPI ````json GET /hcm-rest-api/rest/1/pyetimesheet { "openapi": "3.0.0", "info": { "title": "API Catalog", "description": "", "version": "1.0.0" }, "servers": [ { "url": "https://mobtest.cmiccloudr12.com/cmictestrti", "description": "CMIC API Server" } ], "security": [ { "cmicBasicAuth": [] } ], "tags": [ { "name": "Highlights" }, { "name": "Asset Management | Equipment" }, { "name": "Asset Management | Fixed Assets" }, { "name": "Asset Management | Purchase Order" }, { "name": "Asset Management | Inventory" }, { "name": "Asset Management | Requisition" }, { "name": "Asset Management | Purchase Change Order" }, { "name": "Bim Model" }, { "name": "Bim Model Revision" }, { "name": "Bim Tag Model" }, { "name": "Bim Tags" }, { "name": "Bim FileUpload Jersey" }, { "name": "Core System | Business Partners" }, { "name": "Core System | Business Partner Addresses" }, { "name": "Core System | Bank" }, { "name": "Core System | Currency" }, { "name": "Core System | Exchange Rates" }, { "name": "Core System | Global Table Text Codes" }, { "name": "Core System | Global Table Regions" }, { "name": "Core System | Terms" }, { "name": "Core System | System Contact" }, { "name": "Core System | Weight Measures" }, { "name": "Core System | Field User Defined Classifiers" }, { "name": "Core System | User Defined Classifiers by Object" }, { "name": "Core System | User Extension Definitions by Object" }, { "name": "Core System | User Extention Field Data Value" }, { "name": "Core System | User Extension Values by Object" }, { "name": "Core System | User System Role" }, { "name": "Core System | User Project Role" }, { "name": "Core System | Documents by Object" }, { "name": "Core System | Audit Status Log by Object" }, { "name": "Core System | Licensed Users" }, { "name": "Core System | Company Access" }, { "name": "Core System | Copy User Settings" }, { "name": "Core System | User Maintenance" }, { "name": "Core System | User Roles" }, { "name": "Core System | Security Groups" }, { "name": "Core System | Job/Project Security" }, { "name": "Core System | Weight Measure with Conversions Code" }, { "name": "Core System | Weight Measure Conversions Code" }, { "name": "Core System | User-defined-fields" }, { "name": "Core System | User-extension" }, { "name": "ECM and Workflow | Image Manager" }, { "name": "Financials | General Ledger" }, { "name": "Financials | Accounts Payable" }, { "name": "Financials | Accounts Receivable" }, { "name": "Preventative Maintenance | Issue Work Orders" }, { "name": "Preventative Maintenance | Issue Work Items" }, { "name": "Preventative Maintenance | Issue Work Budgets" }, { "name": "Preventative Maintenance | Issue Priorities" }, { "name": "Preventative Maintenance | Issue Status" }, { "name": "Preventative Maintenance | Issue Types" }, { "name": "Preventative Maintenance | Accumulative Equipment" }, { "name": "Preventative Maintenance | Work Orders" }, { "name": "Preventative Maintenance | Work Items" }, { "name": "Preventative Maintenance | Work Budgets" }, { "name": "Preventative Maintenance | Priorities" }, { "name": "Preventative Maintenance | Tasks" }, { "name": "HCM | UKG Pay Deductions" }, { "name": "HCM | UKG Pay Earnings" }, { "name": "HCM | UKG Pay Headers" }, { "name": "HCM | UKG Pay Taxes" }, { "name": "HCM | Payroll Geographical States" }, { "name": "HCM | Payroll Trades" }, { "name": "HCM | Payroll Union" }, { "name": "HCM | Payroll Pay Runs" }, { "name": "HCM | Payroll Pay Groups" }, { "name": "HCM | Payroll Tax" }, { "name": "HCM | Payroll Worker Compensation" }, { "name": "HCM | Payroll Work Locations" }, { "name": "HCM | Payroll Trade Pay Rates" }, { "name": "HCM | Payroll Union Pay Rates" }, { "name": "HCM | Payroll Job Pay Rates" }, { "name": "HCM | Payroll Master Benefits" }, { "name": "HCM | Payroll Master Deductions" }, { "name": "HCM | Payroll Ben/Ded/Leave Base Codes" }, { "name": "HCM | Payroll Ben/Ded Plans" }, { "name": "HCM | Payroll Ben/Ded Plan Options" }, { "name": "HCM | Payroll Company Benefits" }, { "name": "HCM | Payroll Company Deductions" }, { "name": "HCM | Payroll Vertex Geographic Locations" }, { "name": "HCM | Payroll Checks" }, { "name": "HCM | Payroll Timesheets" }, { "name": "HCM | Employee" }, { "name": "HCM | Employee (Minimum payload)" }, { "name": "HCM | Employee History" }, { "name": "HCM | Tax Exemptions" }, { "name": "HCM | Employee Tax Overrides" }, { "name": "HCM | Employee Pay Splits" }, { "name": "HCM | Employee Benefits" }, { "name": "HCM | Employee Clock In and Out" }, { "name": "HCM | Employee Deductions" }, { "name": "HCM | Employee Leaves" }, { "name": "HCM | Employee Leave History" }, { "name": "HCM | Employee Hour Types" }, { "name": "HCM | Employee Pay History" }, { "name": "HCM | Employee Work Statuses" }, { "name": "HCM | Employee Security Group" }, { "name": "HCM | Crewtime Crew" }, { "name": "HCM | Crewtime Employee Timesheet" }, { "name": "HCM | Crewtime Equipment Timesheet" }, { "name": "HCM | Crew Maintenance Activity Assignment" }, { "name": "HCM | Crew Maintenance Member Assignment" }, { "name": "HCM | Crew Maintenance Member Trade and Union Assignment" }, { "name": "HCM | Crew Maintenance Equipment Assignment" }, { "name": "HCM | Crew Maintenance Equipment Detail Assignment" }, { "name": "HCM | HR Requisitions" }, { "name": "HCM | HR Relations" }, { "name": "HCM | HR Employee Skills" }, { "name": "HCM | HR Incident" }, { "name": "HCM | HR Employee Relatives / Dependents" }, { "name": "HCM | HR Employee Positions" }, { "name": "HCM | HR Applicants" }, { "name": "HCM | HR Applications" }, { "name": "HCM | Vertex Location City" }, { "name": "HCM | HR Application History" }, { "name": "HCM | HR Dependent Benefits" }, { "name": "HCM | HR Dependent Deductions" }, { "name": "HCM | HR Employee Elected Plans" }, { "name": "HCM | HR Employee Training Certifications" }, { "name": "HCM | HR Trainings" }, { "name": "HCM | E-Timesheets" }, { "name": "HCM | System Contacts" }, { "name": "HCM | System User Payroll Security Group" }, { "name": "HCM | Payroll Timesheet Posting" }, { "name": "HCM | CrewTimesheet Posting" }, { "name": "HCM | HR Positions Master" }, { "name": "HCM | Payroll Pay Periods" }, { "name": "HCM | Payroll Rate Codes" }, { "name": "HCM | Payroll Overhead Codes and Rates" }, { "name": "HCM | Payroll Assigned Overhead to Jobs" }, { "name": "Materials Management | Material Sale Orders" }, { "name": "Materials Management | Material Sale Orders Details" }, { "name": "Materials Management | Truck Rate Detail" }, { "name": "Opportunity Management | Competitors" }, { "name": "Opportunity Management | Opportunities" }, { "name": "Opportunity Management | Revenue Details" }, { "name": "Opportunity Management | Opportunity History" }, { "name": "Opportunity Management | Organization" }, { "name": "Project Controls | Job Billing" }, { "name": "Project Controls | Job Cost" }, { "name": "Project Controls | PCI Details" }, { "name": "Project Controls | Unposted PCI Details" }, { "name": "Project Controls | PCI Headers" }, { "name": "Project Controls | Owner Change Orders" }, { "name": "Project Controls | CM Statuses" }, { "name": "Project Controls | CM Types" }, { "name": "Project Controls | CM Vendor Details" }, { "name": "Project Controls | Post PCI" }, { "name": "Project Management | Uploading Documents" }, { "name": "Project Management | Downloading Documents" }, { "name": "Project Management | Foreign Bid Item Imports" }, { "name": "Project Management | Communications" }, { "name": "Project Management | Daily Journals" }, { "name": "Project Management | Communications Types" }, { "name": "Project Management | Daily Journal Daily Work Plans" }, { "name": "Project Management | Daily Journal Field Forces" }, { "name": "Project Management | Daily Journal Labour" }, { "name": "Project Management | Daily Journal Materials" }, { "name": "Project Management | Daily Journal Owner Equipment" }, { "name": "Project Management | Daily Journal Quality Control" }, { "name": "Project Management | Daily Journal Tasks" }, { "name": "Project Management | Daily Journal Trade Equipment" }, { "name": "Project Management | Daily Journal Transactions" }, { "name": "Project Management | Daily Journal User Defined Data" }, { "name": "Project Management | Daily Journal Visitors" }, { "name": "Project Management | Daily Journal Bill Details" }, { "name": "Project Management | Field Work Directives" }, { "name": "Project Management | Contract Types" }, { "name": "Project Management | Company Contacts" }, { "name": "Project Management | Distribution BCC" }, { "name": "Project Management | Distribution CC" }, { "name": "Project Management | Field Work Directive Statuses" }, { "name": "Project Management | Issues" }, { "name": "Project Management | Key Players" }, { "name": "Project Management | Meetings" }, { "name": "Project Management | Meeting Attendees" }, { "name": "Project Management | Meeting Item Statuses" }, { "name": "Project Management | Meeting Tracks" }, { "name": "Project Management | Notes" }, { "name": "Project Management | Projects" }, { "name": "Project Management | Project Items" }, { "name": "Project Management | Project Item Phase Segment Sums" }, { "name": "Project Management | Project Partners" }, { "name": "Project Management | Notices" }, { "name": "Project Management | Notice Statuses" }, { "name": "Project Management | Owner JS Query" }, { "name": "Project Management | PCI Real Locations" }, { "name": "Project Management | Project Contacts" }, { "name": "Project Management | RFIs (Requests for Information)" }, { "name": "Project Management | RFI Statuses" }, { "name": "Project Management | Submittal Packages" }, { "name": "Project Management | Submittal Package Details" }, { "name": "Project Management | Submittal Package Status" }, { "name": "Project Management | Submittals" }, { "name": "Project Management | Submittal Status" }, { "name": "Project Management | Transmittals" }, { "name": "Project Management | Subcontract Headers" }, { "name": "Project Management | Subcontract Schedules" }, { "name": "Project Management | Subcontract Sechedule Phase Segment Sums" }, { "name": "Project Management | User Roles" }, { "name": "Project Management | Punchlists" }, { "name": "Project Management | Punchlist Details" }, { "name": "Project Management | Punchlist Statuses" }, { "name": "Project Management | Meeting Items" }, { "name": "Project Management | Self Perform Vendor" }, { "name": "Project Management | Submittal Types" }, { "name": "Project Management | Assign contact and partner to project" }, { "name": "Project Management | Subcontract Prequal" }, { "name": "Project Management | Bid Item Package" } ], "paths": { "/hcm-rest-api/rest/1/pyetimesheet": { "get": { "tags": [ "HCM | E-Timesheets" ], "summary": "Retrieve PY E-Timesheets By Code", "description": "## Overview\n\n 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.\n\n## Notes\n\nTo 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: \n[ESS Registration and Access Setup](https://docs.cmicglobal.com/portal/Content/E_Reference_Material/ESS_Employees/Reference/Overview/ESS_Registration.htm?Highlight=ESS)\n\nFurther, 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.\n\n## UI Navigation\n\nE-time > E-timesheet Entry\n\nESS > Timesheet\n\n## Reference Article\n\n* [E-Time](https://docs.cmicglobal.com/portal/Content/E_Reference_Material/PYE_-_E-Time/Reference/E-Timesheet/Personal_Time/E_Timesheet_Entry.htm?Highlight=e-timesheet)\n* [Employee Self-Service (ESS)](https://docs.cmicglobal.com/portal/Content/E_Reference_Material/ESS_Employees/Reference/Overview/ESS_Employees.htm)\n\n## Path Parameters\n\n| Parameter | Description | Example |\n| --- | --- | --- |\n| /VUUID | The VUuid attribute is the Unique row ID | |\n\n## Query Standards\n\n| Key | Recommended | Description |\n| --- | --- | --- |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n\n## pyetimesheet Finders\n\n| Finder | Parameter | Data Type | Description | Example |\n| --- | --- | --- | --- | --- |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n\n## pyetimesheet Attributes\n\n| CMiC UI Fieldname | Object | Name | Description | Type | Data Length | Example |\n| --- | --- | --- | --- | --- | --- | --- |\n| 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. |\n| 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 |\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 |\n| 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.” |\n| 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. |\n| Date | pyetimesheet | TshDate | The timesheet date is the effective date the productivity is accumulated on. | datetime | | 2025-06-24 |\n| 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’ |\n| Document Code | pyetimesheet | TshDocumentNo | The document code is autopopulated by CMiC on timesheet injection. | string | 30 | GH001202502 |\n| Employee Number | pyetimesheet | TshEmpNo | An existing CMiC employee number associated with the submitted timesheet. | string | 16 | 2415 |\n| General Ledger Account Code | pyetimesheet | TshGlAccCode | The GL account associated with time submitted outside of job costing. | string | 16 | 1000 |\n| 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 |\n| 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. |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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. |\n| 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 |\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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |", "parameters": [ { "name": "finder", "in": "query", "schema": { "type": "string" }, "example": "selectETimeSheet; PrnCode=SM, Period=5, CompCode=001, Year=2015" }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "example": "500" }, { "name": "offset", "in": "query", "schema": { "type": "integer" }, "example": "0" }, { "name": "totalResults", "in": "query", "schema": { "type": "boolean" }, "example": "true" }, { "name": "orderBy", "in": "query", "schema": { "type": "string" }, "example": "TshVUuid:desc" } ], "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/vnd.oracle.adf.resourcecollection+json" } } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } ] } } } } } } } }, "components": { "securitySchemes": { "cmicBasicAuth": { "type": "http", "scheme": "basic", "description": "Basic authentication" } } } } ````