Background Checking
Contents
- Overview
- Background Check Workflow
- Requirements
- Working with the Api
- Request Examples
- Development Notes
- Troubleshooting
Overview
The background check API enables external background checking suppliers to integrate directly with PageUp. Whilst the purpose of this API was designed for the background checking market, the standard workflow may be applicable to reference checking and medical check suppliers pending a verification process.
The Background Check API allows for:
- Polling of our end point for new unprocessed background/reference/medical check requests.
- Updating the status of those requests to reflect progress of the background/reference/medical check .
- To understand more about the standard user experience workflow that is supported, refer to the “background check workflow” guide below.
Background Check Workflow
- Creating check packages in PageUp
- Triggering/Requesting a check in PageUp
- Check progress, completion and failure notifications in PageUp
Functional/Experience clarification
Q: Is it possible to provide partial results and have that visible in the system?
A: To provide partial results, set the status of the check to “in progress” and then provide the partial results within the results attributes.
Q: I have observed that there is a “note” field available within the background invitation details. How do we provide content for this field?
A: This note field is a legacy field and support for this field within the Background Check API is not currently available.
Requirements
Technical
- API's are secured using oAuth (client credentials grant flow)
- Integrators must handle common errors and support surfacing of error messages back to the user when a job is not successful
- Integrators must log all relevant errors and be able to provide a copy to PageUp to assist with troubleshooting when required
Functional
- The background check workflow is well defined and by integrating with PageUp’s background check API, you are agreeing to this workflow.
- Support notification of background check invitation status change through the API.
- On completion of a background check, the result should be made accessible from the PageUp RMS platform.
- Support resume file sizes up to 20 MB
- Support multiple mutual customers
- URLs to the result/report must be authenticated URLs and must not be publicly accessible.
Testing
- Integrators must ensure appropriate levels of testing prior to the onboarding of a mutual customer.
- During the build stage, integrators will validate against a test system issued by PageUp in a UAT environment
- Prior to the Go Live of a mutual customer, the integrator must validate a working end to end workflow in that mutual customer's production environment
- It is recommended that integrators secure sign-off from the mutual customer of a working end to end integration workflow.
Monitoring
- Integrators must have in place monitoring processes to alert them of failed requests, updates and notifications.
Working with the API
The background check API supports two high level operations:
- Getting a list of background check invitations to be processed (who has been asked to undergo a background check)
When a person is asked to undergo a background check, PageUp will make the relevant details available for the background check provider to consume.
The API supports this through an endpoint which will return a maximum of 5 background check invitations waiting to be processed.
Details on how to retrieve checks that have been requested can be found in the "Get" section of current API documentation below.
- Updating the status of the background check as it progresses and results when completed.
Upon receiving the background check invitation, we understand there are several steps happening to complete the process. PageUp RMS system allows these steps and corresponding status updates to be transparent to the recruiter and its organisation.
When a background check invitation is completed, a status update of "Completed" along with the link for viewing the result should be provided.
Note: The link for viewing the results must be an authenticated link.
Details on how to provide status updates / let us know a check is completed can be found in the "PUT" section of current API documentation below.
Authenticating the API
Please refer to the authentication documentation for additional details.
Retrieving an access token
URL to get an authentication token:
https://login[environment].dc[data centre number].pageuppeople.com/connect/token. Please contact PageUp to confirm environment and data centre number.
I.e.
UAT - `https://loginuat.dc2.pageuppeople.com/connect/token`
LIVE - `https://login.dc2.pageuppeople.com/connect/token`
Body
client_id:<client_id>
client_secret:<client_secret>
grant_type:client_credentials
instanceId:<instanceId>
scope: <scope_of_the_operation_to_perform>
Notes:
- Client ID and Client secret will be different for each mutual client so ensure that the integration is built out in a way that caters to this.
- The oAuth token has an expiry period of 300 seconds.
Background check API workflow
URL format
https://<environment>.<dataCentreId>.pageuppeople.com/v3/<tenantId>/backgroundchecking
Where
environment = specify 'api' for production or 'apiuat' for development
dataCentreId = the data centre to connect to (e.g. dc2)
tenantId = the organisation's tenant Id (normally a 3-digit number. e.g. 218)
Example - connect to the 218 production environment on dc2
https://api.dc2.pageuppeople.com/v3/218/backgroundchecking
Request Examples
Retrieving the background checks
Retrieve the list of pending background checks for provider 'bg'. Note that the provider parameter is optional.
Request
Url: https://api.dc2.pageuppeople.com/v3/218/backgroundchecking?status=pending&provider=bg
Method: GET
Updating a background check
Updates a background check instance
Background check failed
Set the background check with id=12345 to "failed"
Request
Url: https://api.dc2.pageuppeople.com/v3/218/backgroundchecking/12345
Method: PUT
Body:
{
"status": "failed",
"reasonForFail": "background check invitation failed to create at bg.com due to missing mandatory fields. Please fill in xx and try again."
}
Background check created
Set the background check with id=12345 to "created"
Request
Url: https://api.dc2.pageuppeople.com/v3/218/backgroundchecking/12345
Method: PUT
Body:
{
"status": "new",
"referenceNumber": "ProviderIdentifier"
}
Background check in progress / cancelled / expired
Set the background check with id=12345 to "in progress", "cancelled" or "expired"
Request
Url: https://api.dc2.pageuppeople.com/v3/218/backgroundchecking/12345
Method: PUT
Body:
{
"status": "inprogress/cancelled/expired"
}
Background check completed
Set the background check with id=12345 to completed
Request
Url: https://api.dc2.pageuppeople.com/v3/218/backgroundchecking/12345
Method: PUT
Body:
{
"status" : "completed",
"referenceNumber": "ProviderIdentifier",
"reasonForFail" : "",
"results" : [
{
"reportLink" : "http://result.bg.com/123",
"reportType" : "result",
"status" : "pass"
},
{
"reportLink" : "http://result.bg.com/123",
"reportType" : "additional",
"status" : "pass"
}
]
}
Revert a background check state to pending
Set a background check status back to pending. This is normally used for integration testing (to avoid having to create new background check instances for each test). This is NOT designed for production workflow purpose.
Please note that there are 2 steps involved: set the state to queued and set the state to pending. Going from other statuses straight to pending is not supported.
Step 1 Request
Url: https://api.dc2.pageuppeople.com/v3/218/backgroundchecking/12345
Method: PUT
Body:
{
"status": "queued"
}
Step 2 Request
Url: https://api.dc2.pageuppeople.com/v3/218/backgroundchecking/12345
Method: PUT
Body:
{
"status": "pending"
}
Development Notes
Preventing inconsistent data caused by a "404 The underlying connection was closed" exception
APIs may encounter temporary connectivity issues resulting in failed operations. It is recommended to have an implementation with some solution in place like retry patterns with an exponential backoff.
Preventing the same background check request being processed multiple times
If your integration has multiple processes to interact with PageUp API, it is possible to end up in a state where the same "pending" requests are picked up multiple times. To avoid this, please set the status to "queued" as soon as they are reteieved from GET end point. This will ensure the request disappear from GET and prevent aother process to pick it up.
Troubleshooting
My test call to the GET end point returns a successful status code (200), but I'm not seeing anything in response, why?
This is because there is no invitation currently in the status of Pending. If you know the test invitation ID, you can use PUT end point to reset the status to Pending. If not, you will need to contact PageUp to have test data setup for you.
Why am I not getting all background check requests waiting to be processed when I call the GET endpoint?
For performance reasons we limit the result set to a maximum of 5 reviews per request. In order to get a full list of outstanding background checks waiting to be processed, you must mark the items as "Queued" so that the rest of the results can be returned in subsequent requests.
I'm getting a "403 Forbidden" error, why?
When retrieving authentication token, make sure you have used the correct scope for the right end point. GET end point requires Public.BackgroundCheck.Read scope. PUT end point required Public.BackgroundCheck.Write scope. Moreover, GET and PUT endpoints also require the partner ID as claim. If the generated authentication token doesn't have one, please contact PageUp to have it setup for you.
Is it possible to provide the outcome for each type of check?
Yes, we now support the /results/status field to specify the outcome of each background check
Is "ReportType" mandatory?
"ReportType is used to present the types of checks conducted (i.e. Medical Check, Employment Check, Credit Check, etc.) so this is required. If it is not provided, then the person won't have an understanding on the types of checks conducted.
The GET endpoint fields are not sequential and there are UUID fields that are not documented, why?
The GET endpoint JSON response is subject to a fuzzy serializer to loosen coupling (https://www.abhayachauhan.com/2017/10/fuzzy-serializer/) and as part of this operation, two things happen: a random property is added and the response is shuffled
Is there a dashboard for background check providers for viewing the background check results?
There is currently no dashboard available for background check providers nor does the API provide a means for accessing background checks moved out of the pending state. The only front-end available is through the PageUp admin pages.
Why is there missing data (e.g. reference number)?
One possible cause is that a subsequent PUT request reset the data. The PUT endpoint is not expected to support a partial update hence the payload should be the full object representation (and this is treated as an override). On a side note, the API does not have a PATCH endpoint for partial updates.