This endpoint lets you look up the "hiring status" for an employee or contractor. It's useful in Applicant Tracking and similar hiring workflows to determine whether a worker has been added to payroll in the past, and what action to take next.
Simply provide a taxpayer identifier (usually an SSN), an email address, or a phone number, 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 worker at a time, using one query field. Passing multiple query fields (e.g. both phoneNumber and email) at the same time is an error. This behavior ensures that you can choose which data field you trust to use as a lookup key and apply that behavior consistently.
This endpoint has no "error" cases. If no worker 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 a worker 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.
Generally speaking, the preferred order of data fields to look up is:
- Taxpayer identifier
- Phone number
- Email address
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 worker 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 worker. |
ACTIVE | A worker with that data exists in payroll, and they are actively employed (if an employee) or under contract (if a contractor). ❌ You should not create a new profile for this worker because it would be a duplicate. Instead, link it to your system using the workerId and externalWorkerId fields. |
ELIGIBLE_FOR_REHIRE | A worker with that data exists in payroll. They were active and subsequently terminated. ✅ You may create a new profile for the worker, 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 | A worker with that data exists in payroll. They were active and subsequently terminated. ❌ You should not create a new profile for this worker 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 worker. |