To access this operation, your access token must contain one of the following scopes. Please refer to the Authorization Token Endpoint for more detail.
• recruiting.domain.candidates.background-checks
Supplemental documentation available in the UKG Community
UKG provides customer with integration details (an offline process). Refer to Authentication Guide.
UKG registers Third Party Integration App within UKG Pro Recruiting (an offline process).
The following information is necessary from developer to complete the registration:
A Background Check Request Redirect URL. A URL in Third Party Integration App that will be used by UKG Pro Recruiting to redirect recruiters requesting a new background check.
A Background Check Results Redirect URL. A URL in Third Party Integration App that will be used by UKG Pro Recruiting to redirect recruiters requesting to view a background check report.
Following registration, the customer must enable the integration for their Recruiting tenant in the UKG Pro Recruiting web app by going to the Recruiting Settings > Integrations > Background Checks page and choosing the integration from the list of background check vendors.
Process Flow:
-
A Recruiter user requests a background check in the UKG Pro Recruiting web app for a specific application.
-
UKG Pro Recruiting redirects the recruiter to the Background Check Request Redirect URL with a Temporary Request Token and HMAC signature created by UKG Pro Recruiting in the URL.
{{background_check_request_url}}?tenant-alias={{tenant-alias}}&token={{temporary-request-token}&application-domain-name={{clusterURL}}&hmac={{sha256-hmac}}
The Temporary Request Token expires after 5 minutes or the first use, whichever comes first.
- In real time as the page is loaded, obtain Candidate, Application, Opportunity and Recruiter details associated with the background check order by making the GET /talent/recruiting/v2/background-check-order-requests?token={{temporary_request_token} request.
Use the integration_user_id received in the GET /talent/recruiting/v2/background-check-order-requests response to identify and the user requesting the background check
Request details received in the GET background-check-order-requests response may be used to pre-populate the background check order
-
The Recruiter fills in remaining details and submits the background check order on the third party web portal.
-
Third party processes the background check order and posts background check status updates to Third party Integration App via the POST/PUT candidates/:id/background-checks/:id web service requests.
-
A recruiter clicks the View Details button in UKG Pro Recruiting to view a candidate's background check report.
-
UKG Pro Recruiting redirects the recruiter to the Background Check Results Redirect URL in Third Party Integration App along with a Temporary Results Token.
{{background_check_results_url}}?tenant-alias={{tenant-alias}}&token={{temporary-results-token}&application-domain-name={{clusterURL}}&hmac={{sha256-hmac}}
The Temporary Results Token expires after 5 minutes or the first use, whichever comes first.
- In real time as the page is loaded, details of the request may be obtained by calling GET /talent/recruiting/v2/background-check-order-results?token={{temporary_results_token}}
Recruiter details are retrieved from the Creator section of the response.
For Both Redirects:
An HMAC signature is included in the query string when requesting a background check and requesting to view a background check report. To create the signature, we hashed the generated secure redirect token using SHA256 and some secret key (TBD) and appended it to the query string as "hmac".
It is then possible to perform the same hashing algorithm on the redirect token using the secret key to verify that the request is coming from a valid source.
Integration App Determines a Recruiting cluster by application-domain-name in the Background Check Request Redirect URL.