Sign in

v1

latestOpenAPI 3.0.42026-07-2481154567.6 KB
Candidate Screening Order

Update Screening Order Status

🚧 Partner Restricted All background check API endpoints are restricted to background check providers that have signed a Paylocity technology partnership agreement. Please reach out to our team if you would like to discuss partnership opportunities.

Summary Description

This endpoint updates the Screening Order status for the given companyId and candidateScreeningOrderId. The patch operation on the candidate status endpoint allows you to update the status of the overall screening order and the related services. You can also send the URL where the recruiter can view the complete screening result. Using this endpoint, partners will be able to add new services to orders that have already been placed.

Use Cases

  • Partner sends the initial status of the order and services, i.e. Ordered and Pending
  • Partner needs to update the status of an order or services of an order
  • Partner is updating the order with new statuses and wants to add on additional services that were added to the order after it was placed
patch/compliance/v1/companies/{companyId}/backgroundCheck/candidateScreeningOrders/status

Path parameters

companyIdstring required

The Paylocity Company Identifier. This is the unique value provided by Paylocity to each specific Payroll Entity. Allowable Values: 9 char max

Headers

Authorizationstring required

Authorization token. Ex. Bearer ...

Request body

candidateScreeningOrderIdstring uuid

Unique identifier of the screening order that was sent to you.

updatedAtstring date-time

The date time of the update.Example: 2023-01-04T04:23:11.586Z

oldStatus'Ordered' | 'WaitingOnCandidate' | 'InProgress' | 'Hold' | 'Complete' | 'CompleteWithCancelled' | 'Cancelled' | 'CompleteNeedsReview' | 'CompleteNotEligible' | 'Suspended' | 'Resumed' | 'CompleteDisputed' | 'InvitationExpired' | 'InvitationCancelled' | 'PreAdverseActionSent' | 'AdverseActionCancelled' | 'Dispute' | 'AdverseActionSent' nullable

The previous status of the screening order.

newStatus'Ordered' | 'WaitingOnCandidate' | 'InProgress' | 'Hold' | 'Complete' | 'CompleteWithCancelled' | 'Cancelled' | 'CompleteNeedsReview' | 'CompleteNotEligible' | 'Suspended' | 'Resumed' | 'CompleteDisputed' | 'InvitationExpired' | 'InvitationCancelled' | 'PreAdverseActionSent' | 'AdverseActionCancelled' | 'Dispute' | 'AdverseActionSent' nullable

The new status of the screening order.

notestring nullable

This is an optional field if a partner needs to send additional details with an order status. Allowable Values: 250 char max

screeningReportDocumentsstring[] nullable

An array of strings representing the URL of the screening report that can be viewed on the partner’s web application.

Example request

{
  "candidateScreeningOrderId": "e72f7918-20c5-4bd2-9a5f-9bee67bd304d",
  "updatedAt": "2023-01-04T04:23:11.586Z"
}

Response

Returns screening order id and status that were updated

candidateScreeningOrderIdstring uuid

The Id of the screening order that was updated

statusstring nullable

The updated status

Example response

{
  "candidateScreeningOrderId": "9de5efb4-3ede-4b92-97f7-71389c31abff",
  "status": "Ordered, WaitingOnCandidate, InProgress, Hold, Complete, PreAdverseActionSent, AdverseActionCancelled, Dispute, AdverseActionSent"
}