This operation returns a candidate by email. You can use this operation to check whether an email address is already associated with a candidate profile in UKG Pro Recruiting. When you send the request, UKG Pro Recruiting searches for the email address of the candidate.
You can use this to:
- Look up the ID of an existing external candidate, so you can use that ID when adding applications or other documents to attach to the candidate.
- Check to see if an email address is already associated with an existing candidate before sending candidate information with a POST candidates request. However, this is optional; you can send a POST candidates request without performing a lookup first.
If you choose not to perform a lookup, you might attempt to add a candidate whose email is already associated with a candidate record in UKG Pro Recruiting. When this happens, the POST candidates request returns a duplicate error, and does not create a candidate record.
When you perform a lookup for an email address:
- If the email address matches only one external candidate record, the response to your lookup request includes the candidate's unique identifier. Retain that unique identifier and use it for submitting applications and other documents for the candidate.
- If the email address does not match any external candidate records, submit a Create Candidate request to create a new record for the candidate in UKG Pro Recruiting.
- If the email address matches more than one candidate record, the response to your lookup request includes a 409 conflict response code.
- If there is no corresponding user account for an existing candidate record, a 409 conflict response will be returned. Use the Retrieve Candidates endpoint to find the candidate ID for the candidate.
Permissions
To access this operation, your access token must contain one of the following scopes:
- recruiting.domain.candidates.read
- recruiting.easy-apply
- recruiting.domain.candidate-import.create
Refer to the Onboarding and Recruiting Authorization and Permissions topic for more information.