This endpoint lets you look up the "hiring status" for an employee. It's useful in Applicant Tracking and similar hiring workflows to determine whether an employee already has a payroll profile history, and what action to take next.
Simply provide a demographic data field and we'll let you know whether a worker with that data exists in the company's worker census. If so, we'll return basic information about that worker's profile, so you can take appropriate action.
How to query this endpoint
This endpoint is designed to look up one employee at a time. You can provide multiple data fields in the same request to allow us to locate an employee profile using as much data as possible.
This endpoint has no "error" cases. If no employee is found with the given lookup data, it will return a "New Hire" response (see below) indicating that you may create a new profile for an employee with that info.
Always use the most static data you can!It's important to use the most "static" data field possible when looking up worker hiring status, because when data changes over time, it becomes impossible to locate worker profiles containing the old data. This can cause hiring discrepancies and manual work to resolve them.
The preferred order of data fields to look up is:
- Social security number (either complete or the last 4 digits)
- First name
- Last name
- Date of birth
- Phone number
- Email address
You can also provide an "external worker ID" field, which is useful if you manage your own employee IDs and provide them to Everee when you create employee profiles. You should provide all the fields you can in a single call, including the "external worker ID" if you have one.
The four hiring scenarios
There are four "hiring scenarios", and you'll always receive one of these four scenarios back in the hiringScenario field. The possible values are:
| Value | What it means |
|---|---|
NEW_HIRE | No employee with that data exists in payroll, so this is a brand new hire, and not a re-hire. ✅ You may create a profile for the new employee. |
ACTIVE | An employee with that data exists in payroll, and they are actively employed. ❌ You should not create a new profile for this employee because it would be a duplicate. Instead, link it to your system using the workerId and externalWorkerId fields. |
ELIGIBLE_FOR_REHIRE | An employee with that data exists in payroll. They were active and subsequently terminated. ✅ You may create a new profile for the employee, which will record them as re-hired. When creating the new profile, provide a hireDate equal to or later than hiringStatus.earliestValidHireDate. |
NOT_ELIGIBLE_FOR_REHIRE | An employee with that data exists in payroll. They were active and subsequently terminated. ❌ You should not create a new profile for this employee because they were marked as "not eligible for rehire" when they were terminated, usually because they were terminated for cause . Generally, you should not proceed with hiring this employee. |
Validation rules & errors
| Validation rule & error message | HTTP code |
|---|---|
| At least one lookup field must be populated. | 400 |
You must provide both firstName and lastName fields, not just one or the other. | 400 |
You must provide at least one field in addition to firstName and lastName. | 400 |
You must provide at least one field in addition to dateOfBirth. | 400 |
You must provide either: at least one field in addition to the last 4 digits of taxpayerIdentifier, or a complete 9-digit taxpayerIdentifier. | 400 |
The field taxpayerIdentifier doesn't match any of the valid formats. | 400 |