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:

1. Social security number (either complete or the last 4 digits)
2. First name
3. Last name
4. Date of birth
5. Phone number
6. 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:

---

How matching works, and how to use externalWorkerId

The lookup returns the single best match for the data you send. It's a best-effort match, not an exact one, so treat the answer as a recommendation to verify, not as proof of identity.

• More matching fields make a better match. A complete 9-digit taxpayerIdentifier is the strongest, followed by your externalWorkerId, email, phone, date of birth, and name.
• A different externalWorkerId rules a worker out. If you send an externalWorkerId and a worker already has a different one on file, that worker isn't returned, so that two people with the same name aren't confused. The exception is a worker whose complete 9-digit taxpayerIdentifier matches the one you sent. That is returned even if the external IDs differ, and externalWorkerIdMismatch is true. A last-4 taxpayerIdentifier does not make this exception.
• A worker with no external ID on file is never ruled out by this check.

🚧

An external ID that is wrong in Everee can hide a worker

If an existing worker's external ID in Everee doesn't match yours, and you don't send a complete taxpayerIdentifier, the lookup can return NEW_HIRE for a person who already exists. Creating a profile in that case produces a duplicate. Before you create a profile for someone you already track, check the worker directly, or look them up again with their full taxpayerIdentifier.

When the returned externalWorkerId isn't yours

If externalWorkerIdMismatch is true, or the externalWorkerId in the response isn't the one you sent:

1. Confirm it's the right person by comparing the name, email, and phone in the response.
2. If it is, don't overwrite your own mapping with the returned value. Correct the ID in Everee with Update external worker ID so both systems agree.
3. If it isn't, don't use the returned workerId.

To rebuild your mapping in bulk, list your workers with List workers and match on stable data, rather than relying on lookup results.

---

Validation rules & errors