Overview
We're excited to announce a change to simplify how you manage Employee Numbers in our system. This change to our system results in a new version of several API endpoints.
Previously, Employee Numbers were limited to 6 digits. Soon, you can extend the employee number to up to 10 characters and configure the format to fit your needs.
You can restrict to less than 10 characters or make the Employee Number all digits, for example. By default, each Paycor customer's Employee Number will be set to 6 digits. To prepare for this change, review the Action to Take section in this article. This change is required regardless of if you are extending your Employee Numbers or keeping them the same.
Action to Take
If you currently have an integration between Paycor and a third party, review the Version 2 endpoints and connect with your technical resources that have built your integration solution with Paycor and adjust to begin consuming the Version 2’s of these APIs, if you are consuming them.
Notes:
- The employee number, going forward in version 2 and any newly introduced Public API endpoint, will be provided as a string rather than as an integer.
- In case your system cannot support letters, or certain number of characters that Paycor now does (10), be aware that each customer can configure this on their own, and by default the employee number is limited to 6 digits.
- The activation process will not need to be completed to access Version 2 of these endpoints, as the data being accessed remains the same.
Follow these steps to switch from version 1 to version 2:
1. Go to the Developer Portal and sign in.
- To learn how to create your Developer Portal account, see the Developer Portal Account Creation guide.
2. Click APIs.
3. Using the dropdown menu, select Version 2.
- Version 1 Example:
- Version 2 Example:
Notes:
- Not every endpoint has a Version 2 available.
- If Version 2 of an endpoint isn't available, you can use Version 1 instead.
- Review this spreadsheet for technical details of the affected Public API endpoints.
| Public API Name | Data Access Name | Public API URL | Documentation Link |
|---|---|---|---|
| Get Employee by EmployeeID | View Employee Information | https://apis.paycor.com/v2/employees/{employeeId} | Documentation |
| Get Employees by Legal Entity ID | View Legal Entity Employees | https://apis.paycor.com/v2/legalentities/{legalEntityId}/employees | Documentation |
| Get Employees By TenantID | View Tenant Employees | https://apis.paycor.com/v2/tenants/{tenantId}/employees | Documentation |
| GET Identifying Employee Data by Legal Entity Id | View Legal Entity Employees Identifying Data | https://apis.paycor.com/v2/legalentities/{legalEntityId}/employeesIdentifyingData | Documentation |
| Add Employee Hours And Earnings To Paygrid | Import Employee Hours and Earnings to Paygrid | https://apis.paycor.com/v/legalentities/{legalEntityId}/payrollhours | Documentation |
| Import Payroll Hours to Employee | Import Payroll Hours to Employee | https://apis.paycor.com/v2/employees/{employeeId}/payrollhours | Documentation |
| Get Legal Entity Employees Time Card Punches by Employee ID | View Employee Time Card Punches By Legal Entity Id | https://apis.paycor.com/v2/employees/{employeeId}/punches | Documentation |
| Get Legal Entity Employees Time Card Punches by Legal Entity ID | View Employee Time Card Punches By Legal Entity Id | https://apis.paycor.com/v2/legalEntities/{legalEntityId}/punches | Documentation |
| Get Employee Accruals by EmployeeID | View Employee Timeoff Accruals by Employee Id | https://apis.paycor.com/v2/employees/{employeeId}/timeoffaccruals | Documentation |
| Get Employee Accruals by Legal Entity ID | View Employee Timeoff Accruals by Legal Entity Id | https://apis.paycor.com/v2/legalentities/{legalEntityId}/timeoffaccruals | Documentation |
| Create Employee | Create Employee | https://apis.paycor.com/v2/employees | Documentation |
| Get employees in the onboarding state | View Legal Entity Onboarding Employees | https://apis.paycor.com/v2/legalentities/{legalEntityId}/onboardingemployees | Documentation |
These Employee Events are the only events impacted by this change:
- Employee Created
- Employee Deleted
- Employee Updated
- Get Employee by Employee ID
If you are using Event Subscriptions, note that the resource reference URL field will be updated to point to Version 2 of this endpoint. There is no need to update or change your data access or activate the application again, as these endpoints are backwards compatible.
Note: Version 1 Endpoints will no longer be supported after July 2025. Make sure all changes have been completed prior to that date.
Updated: June 2nd, 2025 2137 views 2 likes