Create a new PY Employee

Published on Feb 9, 2026

15 minute(s) read

Post

/hcm-rest-api/rest/1/pyemployee

Overview

The Employee profile is a master record that not only retains employee demographic details but is central to populating employee default functionality for timesheet and payroll cost allocations. This endpoint is used to create and update employee records within the CMiC US Payroll Module.

Notes

This POST method is used to both create and update records in CMiC; when updating, include the Effective Date and Action Code fields in the payload along with any other required updates.

Human Capital Management > Setup > Employees > Employee Profile

Reference Article

US Payroll – Employee Profile

Required Body Parameters

CMiC UI Fieldname	Object	Name	Description	Type	Data Length	Example	Required
Employee Number	pyemployee	EmpNo	This is the employee identification number in CMiC. If the 'Payroll/HR Auto Numbering' box has been checked in the Payroll tab of System Options (standard Treeview Path: System > Setup > System Options – Payroll tab), this field will not be accessible and the system will automatically number any new employees with the next available, sequential number.	string	16	1	Yes
Hire Date	pyemployee	EmpHireDate	This is the hire date of the employee. Format must be in YYYY-MM-DD	datetime	YYYY-MM-DD	2025-10-28	Yes
Date of Birth	pyemployee	EmpDateOfBirth	This is the birth date of the employee. Format must	datetime	YYYY-MM-DD	1975-05-15	Yes
Social Security Number (SSN)	pyemployee	EmpSinNo	This is the government issued Social Security Number/Social Insurance Number for the employee. Must be a valid number issued by the employee’s residing country.	string	16	###-##-####, an example could be 123-45-6789	Yes
First Name	pyemployee	EmpFirstName	This is the employee’s First Name	string	60	Dan	Yes
Last Name	pyemployee	EmpLastName	This is the employee’s Last Name.	string	60	Li	Yes
Status	pyemployee	EmpStatus	This is the employee’s status in CMiC.	string	1	A – ActiveT – TerminatedR – RetiredD – DeceasedS – SickU – Unpaid LeaveP – Paid LeaveL – Temporary LayoffO - Other	Yes
Type	pyemployee	EmpType	This identifies if the employee is an hourly or salaried employee. Hourly: Employees are paid based on hours entered in timesheets for the payroll period. Date sensitive pay rates, charge out, and billing rates for hourly employees can default from the Customer, Job, Trade, Union, or Employee Pay Rate screens (see the Pay Rates section for further details). If date sensitive pay rates are not required then static hourly, charge out, and billing rates can be entered in the Rates/Salary tab.Salaried: Timesheets are not required and employee wages are based on the annual salary entered on the Rates/Salary tab divided by the number of periods in the pay run. Timesheets can still be entered if payroll costs must be transferred to a job.	string	1	H – HourlyS - Salary	Yes
Eligibility Flag	pyemployee	EmpEligibilityFlag	This flag determines if the employee is eligible to record overtime on timesheets,	string	1	Y – EligibleN – Not Eligible	Yes
Flsa Type	pyemployee	EmpFlsaType	This flag determines if the employee is exempt from overtime. Employees are non-exempt by default. Non-exempt employees are entitled to work overtime, and their timesheets are included when processing overtime.By contrast, all timesheets for exempt employees validate the hours based on the employee pay run frequency and overtime hours are disallowed. For example, if the employee belongs to a weekly pay run, then timesheets do not allow entry of more than 40 normal working hours per week.	string	1	N – Non-ExemptY - Exempt	Yes
Benefit Type	pyemployee	EmpHemplType		string	10	H- Hourly S- Salary	Yes
Unionized Flag	pyemployee	EmpUnionized	This flag determines if the employee is unionized. If checked Y, the EmpUniCode must also be created. The EmpUniCode must be a valid code in CMiC.	string	1	Y – UnionizedN – Not Unionized	Yes
Federal Filing Status	pyemployee	EmpFilingStatus	This is the employee’s W4 federal filing status. Must be a valid value in CMiC.	string	2	01 – Single02 – Married03 – Head of Household16 – Married Filing Jointly62- Single or Married Filing Separately	Yes
State Filing Status	pyemployee	EmpStateFilingStatus	This is the employee’s W4 state filing status. Must be a valid value in CMiC and correspond with the State Code (EmpStateCode). See State Code for further details.	String	2	United StatesAlabama 01Alaska 02Arizona 03Arkansas 04California 05Colorado 06Connecticut 07Delaware 08District of Columbia 09Florida 10Georgia 11Hawaii 12Idaho 13Illnois 14Indiana 15Iowa 16Kansas 17Kentucky 18Louisiana 19Maine 20Maryland 21Massachusetts 22Michigan 23Minnesota 24Mississipi 25Missouri 26Montana 27Nebraska 28Nevada 29New Hampshire 30New Jersey 31New Mexico 32New York 33North Carolina 34North Dakota 35Ohio 36Oklahoma 37Oregon 38Pennyslvania 39Rhode Island 40South Carolina 41South Dakota 42Tennessee 43Texas 44Utah 45Vermont 46Virginia 47Washington 48West Virginia 49Wisconsin 50Wyoming 51American Samoa 60F.S. of Micronesia 61Guam 66Marshal Islands 67N. Mariana Islands 68Palau 69Puerto Rico 72United States Minor Outlying 1 74Virgin Islands 78	Conditional Yes
State Code	pyemployee	EmpStateCode	This is the employee’s address state code. The code selected here will influence the employee’s State Filing Status (EmpStateFilingStatus) and State Filing Status should be updated for tax purposes.	string	4	AK – AlaskaAL – AlabamaAR – ArkansasAS – American SamoaAZ – ArizonaCA – CaliforniaCO – ColoradoCT – ConnecticutCZ – Canal ZoneDC – District of ColumbiaDE – DelawareFL – FloridaFM – Federated States of MicronesiaGA – GeorgiaGU – GuamHI – HawaiiIA – IowaID – IdahoIL – IllinoisIN – IndianaKS – KansasKY – KentuckyLA – LouisianaMA – MassachusettsMD – MarylandME – MaineMH – Marshall IslandsMI – MichiganMN – MinnesotaMO – MissouriMP – Northern Mariana IslandsMS – MississippiMT – MontanaNC – North CarolinaND – North DakotaNE – NebraskaNH – New HampshireNJ – New JerseyNM – New MexicoNV – NevadaNY – New YorkOH – OhioOK – OklahomaOR – OregonPA – PennsylvaniaPR – Puerto RicoPW – PalauRI – Rhode IslandSC – South CarolinaSD – South DakotaTN – TennesseeTX – TexasUT – UtahVA – VirginiaVI – Virgin IslandsVT – VermontWA – WashingtonWI – WisconsinWV – West VirginiaWY - Wyoming	Yes
Country Code	pyemployee	EmpCountryCode	This is the Country assigned on the employee address.	string	4	US – United States	Yes
Zip Code	pyemployee	EmpZipCode	This is the zip code of the employee’s address.	string	13	92357	Yes
Phone Number	Pyemployee	EmpPhone	This is the employee’s home phone number.	string	24	347-258-8945	Yes
Work Phone Number	pyemployee	EmpWorkPhone	This is the employee’s work number.	string	24	325-412-7895	Yes
Cellphone Number	pyemployee	EmpCellPhone	This is the employee’s cell number.	string	24	347-758-1112	Yes
Work Email Address	pyemployee	EmpWorkEmailAddress	This is the employee’s work email address. This email address is used to manage ESS access for the employee. Should be a valid email address to receive ESS notifications.	string	100	Dan.Li@constructioncompany.com	Yes
Gender Code	pyemployee	EmpSex	This is the employee’s gender. Used for EEO-1 reporting. Must be a valid value in CMiC.	string	1	F- FemaleM- MaleU - Unknown	Yes
Marital Status Code	pyemployee	EmpMaritalStatus	This is the employee’s Marital Status, used for tax and benefit calculations. Must be a valid value in CMiC.	string	1	S – SingleM – MarriedC – Common Law	Yes
Military Status Code	pyemployee	EmpMilitaryStatus	This is the Military Status of the employee. Used in VETS-4212 reporting. Must be a valid Military Status in CMiC.	string	20	VE – VeteranNV – Not VeteranDV – Disabled VeteranVV – Vietnam VeteranMV – Service & Medal VeteranOV – Active Duty Wartime or Campaign Badge VeteranPV – Newly Separated VeteranIR – Inactive ReserveRR – Ready ReserveHV – Disability/HandicapNS – I do not wish to self-identify	Yes
Ethnicity Code	pyemployee	EmpEthnicCode	This is the Ethnic Code of the employee. Used in EEO-1 Component 1 reporting. Must be a valid Ethnicity in CMiC.	string	2	W – WhiteI – Aboriginal/IndigenousA – AsianB – Black/African AmericanH – Hispanic/LatinoX – Not applicableP – Hawaiian/Pacific IslanderM – Two or more races	Yes
Dominant Hand	pyemployee	EmpDominantHand	This is the employee’s dominant hand. Used for HR Safety module in CMiC.	string	1	R – RightL - Left	Yes
Employee Company Code	pyemployee	EmpComment	This is the employee’s payroll company. Used for allocating payroll expenses during payroll processing and committing. Must be a valid Payroll Company in CMiC.	string	2000	10	Yes
Home Company Code	pyemployee	EmpHomeCompCode	This is the reporting company of the employee; where the employee reports to work. Must be a valid company in CMiC.	string	8	11	Yes
Home Department Code	pyemployee	EmpHomeDeptCode	This is the employee’s reporting department. Must be a valid department in CMiC.	string	6	10 – Project Management	Yes
Department Code	pyemployee	EmpDeptCode	This is the employee’s payroll department. Used for allocating payroll expenses during payroll processing and committing. Must be a valid Payroll Company in CMiC.	string	6	01 - Payroll	Yes
Payrun Code	pyemployee	EmpPrnCode	This is the payroll run the employee belongs to. Used for allocating payroll expenses during payroll processing and committing. Must be a valid Payroll Company in CMiC.	string	4	WK – WeeklyBW – BiweeklyMN - Monthly	Yes
Trade Code	pyemployee	EmpTrdCode	This is the employee’s union classification in CMiC. Also used to identify non-union classification for building compensation hierarchies in CMiC. Must be a valid Trade in CMiC.	string	30	CARP - Carpenter	Yes
Timesheet Code	pyemployee	EmpTshCode	This is the time sheet code the employee record belongs to. Can match the Payrun Code. Must be a valid Timesheet Code in CMiC.	string	4	WK – WeeklyBW – BiweeklyMN - Monthly	Yes
Paygroup Code	pyemployee	EmpPygCode	This the payroll grouping the employee record is assigned to. Used for grouping time away (leaves), benefits and deductions in CMiC. Must be a valid Paygroup CMiC.	string	4	Hourly - HourlySalrd - SalariedCorp – CorporateUnion – UnionCont – ContractPT – Part-time	Yes
Workers Comp Code	pyemployee	EmpWcbCode	This is the workers’ compensation code assigned to the employee record. Must be a valid compensation code in CMiC.	string	4	3224 – Millwright	Yes
Worklocation Code	pyemployee	EmpWrlCode	This is the work location the employee record belongs to. This is the work location used by the system for calculating taxes. Must be a valid work location in CMiC.	string	15	HQ – HeadquartersPT - Pittsburg	Yes
Annual Salary	pyemployee	EmpAnnualSalary	This the annual salary compensation amount. Although not a required field by default, if the EmpType value is ‘S’, then this field must be populated.	number	18	42000.00	Conditional Yes
Hourly Rate	pyemployee	EmpHourlyRate	This is the base compensation hourly rate assigned to the employee.	number	16	25.00	Yes
Charge out Rate	pyemployee	EmpChargeOutRate	This is the hourly charge rate assigned to the employee.The rate is used to post costs for jobs for the hours worked on those jobs. Also used by GC (General Conditions) Monitoring Module for forecasting productivity costs.	number	16	30.00	Yes
Billing Rate	pyemployee	EmpBillingRate	This is the hourly billing rate assigned to the employee. The rate used to post billing amounts against jobs for the hours worked on those jobs. Also used by GC (General Conditions) Monitoring Module for forecasting productivity costs.	number	16	35.00	Yes
GC Monitor Charge Rate	pyemployee	EmpGcChargeRate	This is GC (General Conditions) Monitor Charge Rate used in GC Monitor calculations for forecasting productivity costs.	number	16	30.00	Yes
GC Monitor Billing Rate	pyemployee	EmpGcBillRate	This is GC (General Conditions) Monitor Bill Rate used in GC Monitor calculations for forecasting productivity costs.	number	16	35.00	Yes
Rate Code	pyemployee	EmpRateCode	This is the normal (regular) rate code assigned to the employee record. It is used by the system to automatically apply the correct rate when calculating dollar amounts from hourly timesheets. Must be a valid Rate Code in CMiC.	string	4	REG	Yes
Overtime Rate Code	pyemployee	EmpOtRateCode	This is the overtime rate code assigned to the employee record. It is used by the system to automatically apply the correct rate when calculating dollar amounts from hourly timesheets. Must be a valid Rate Code in CMiC.	string	4	OVT	Yes
Doubletime Rate Code	pyemployee	EmpDotRateCode	This is the double-time rate code assigned to the employee record. It is used by the system to automatically apply the correct rate when calculating dollar amounts from hourly timesheets. Must be a valid Rate Code in CMiC.	string	4	DVT	Yes
Other Rate Code	pyemployee	EmpOthRateCode	This is the other rate code assigned to the employee record. The other rate code is for other hour types outside of Normal, overtime and double time that are defined in the system. It is used by the system to automatically apply the correct rate when calculating dollar amounts from hourly timesheets. Must be a valid Rate Code in CMiC.	string	4	OTH	Yes
Effective Date	pyemployee	EmhEffectiveDate	This the effective date of when the employee record was created in CMiC. Also used as the ‘as of’ date to identify modifications made to the employee record.	datetime	YYYY-MM-DD	2025-10-31	Conditional Yes
Action Code	pyemployee	EmhActionCode	The action code is used by the system to identify the change being applied. This is a conditional field where other fields must also be updated/passed in the payload when and update is being made to a record. Must be a valid Action Code in CMiC.	string	2	CH – ChangeRH – RehireHR – HireT – TerminateTR – Transfer	Conditional Yes
Create Access Code Flag	pyemployee	EmpCreateAccessCode	This field is used to auto-generate a ID to be used in ESS e-timesheets for assigning timesheet privileges in ESS. If ‘Y’ value is passed will impact ESS E-time licenses available.	string	1	Y – auto- generate a Timesheet Access Code.N – do not auto-generate a Timesheet Access Code.	Yes
Employee User Login	pyemployee	EmpUser	This is the employee’s user ID in CMiC. Must be a valid System User in CMiC.	string	30	DLI	Yes
Security Group Code	pyemployee	EmpSecGrpEmpCode	This is the security group assigned to the employee record. Every employee must belong to a security group to be visible in the system when a user accesses that group. If left blank, the employee will not appear in payroll, even after setup. Once assigned, the employee will be visible in timesheets, payroll processing, and all related HR and payroll module screens.	string	200	FIELD	No

Security

HTTP

Type basic

Basic authentication

Header parameters

Content-Type

string

Exampleapplication/vnd.oracle.adf.resourceItem+json

Body parameters

object

Example{ "EmpNo": "GEO-TEST-053", "EmpPrimaryEmpNo": "GEO-TEST-053", "EmpUser": "DA", "EmpFirstName": "API", "EmpLastName": "Test", "EmpSinNo": "331601053", "EmpStatus": "A", "EmpDateOfBirth": "2000-01-01", "EmpHireDate": "2023-10-03", "EmpCompCode": "ZZ", "EmpDeptCode": "00", "EmpPrnCode": "ZZWK", "EmpPygCode": "WK", "EmpTrdCode": "ZZ10", "EmpWrlCode": "ZCHI", "EmpHourlyRate": 50, "EmpChargeOutRate": 100, "EmpBillingRate": 150, "EmpSecGrpEmpCode": "MASTER", "EmpFilingStatus": "02", "EmpVUuid": "", "EmpCountryCode": "US", "EmpStateCode": "OH", "EmpZipCode": "43055", "EmpAddress3": "Newark", "EmpCalcPref": "S", "EmpResLoc": "SNY", "EmpFullName": "Liam Kinder", "EmpFlsaType": "N", "EmpHemplYearlySal": 0, "EmpHemplType": "H", "EmpLastTshJobCode": "ZZ-SWJOB", "EmpVertexGeocodeSource": "M", "EmpType": "S", "EmpFullPartTime": "F", "EmpSubStatus": "W", "EmpCalcAccruedLeave": "Y", "EmpUnionized": "N", "EmpRehireEligible": "Y", "EmpAdjustedSeriviceDate": "2005-01-01", "EmpYearWorkingDays": 260, "EmpYearWorkingHours": 2080, "EmpUeValidFlag": "Y", "EmpHomeDeptCode": "00", "EmpGlAccCode": "6000.100", "EmpPayrollClearAccCode": "6000.200", "EmpDrClearAccCode": "6000.200", "EmpLevAcruGlAccCode": "6002.101", "EmpLevClearAccCode": "6002.101", "EmpTshCode": "ZZWK", "EmpWcbCode": "WC", "EmpPlCode": "PL", "EmpPlName": "Public Liab NY", "EmpWcbByJob": "Y", "EmpPlByJob": "Y", "EmpWrlFlag": "Y", "EmpExcpInclFlag": "N", "EmpInclCertPyRepFlag": "Y", "EmpAutogenerateTimesheet": "Y", "EmpDispatchFlag": "N", "EmpAnnualSalary": 80000, "EmpRateCode": "Z100", "EmpOtRateCode": "Z200", "EmpDotRateCode": "Z300", "EmpOthRateCode": "Z400", "EmpPreferPayRate": "J", "EmpPreferChargeRate": "J", "EmpPreferBillRate": "J", "EmpDirectDepMethod": "M", "EmpJobCompCode": "ZZ", "EmpEmailAddress": "william.palo@cmic.ca", "EmpPrefContactMth": "E", "EmpResidentStatus": "C", "EmpPrimExemp": 0, "EmpNrCertificate": "Y", "EmpSex": "M", "EmpMaritalStatus": "S", "EmpEthnicCode": "W", "EmpMilitaryStatus": "NV", "EmpDominantHand": "R", "EmpLeaveCalcPref": "R" }

Responses

201

Created

Headers