---
title: "Update Screening Order Status"
method: PATCH
path: "/compliance/v1/companies/{companyId}/backgroundCheck/candidateScreeningOrders/status"
tags: ["Candidate Screening Order"]
---

# Update Screening Order Status

`PATCH /compliance/v1/companies/{companyId}/backgroundCheck/candidateScreeningOrders/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](https://www.paylocity.com/contact/partner-form/) 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

## Path parameters

- `companyId` string, required

## Headers

- `Authorization` string, required

## Request body

- CandidateScreeningOrderStatusUpdateRequest — The update information for the screening order
  - `candidateScreeningOrderId` string, uuid — Unique identifier of the screening order that was sent to you.
  - `updatedAt` string, 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.
  - `note` string, nullable — This is an optional field if a partner needs to send additional details with an order status. **Allowable Values:** 250 char max
  - `services` ServiceStatusUpdateDto[], nullable — The array of services in scope of which the screening order will be processed.
    - `serviceName` string, nullable — The name of the specific service within a background check package that the users will see. **Allowable Values:** 150 char max
    - `oldStatus` 'Pending' | 'InProgress' | 'Completed' | 'Cancelled' | 'Suspended' | 'Disputed' | 'Expired' | 'NeedsReview' | 'NotEligible' | 'Deleted', nullable — The previous status of the service.
    - `newStatus` 'Pending' | 'InProgress' | 'Completed' | 'Cancelled' | 'Suspended' | 'Disputed' | 'Expired' | 'NeedsReview' | 'NotEligible' | 'Deleted', nullable — The new status of the service.
    - `note` string, nullable — This is an optional field if the partner needs to send additional details with status of a service **Allowable Values:** 250 char max
  - `screeningReportDocuments` string[], nullable — An array of strings representing the URL of the screening report that can be viewed on the partner’s web application.

## Response `200`

Returns screening order id and status that were updated

- CandidateScreeningOrderStatusUpdateResponse — The response of the update screening order
  - `candidateScreeningOrderId` string, uuid — The Id of the screening order that was updated
  - `status` string, nullable — The updated status

## Other responses

- `400` — Bad Request Error - Returns the details of the error
- `401` — Unauthorized
- `415` — Unsupported Media Type - Returns the details of the error

---

[API](https://skmtc.net/paylocity/apis/assessments-api.md) · [All operations](https://skmtc.net/paylocity/apis/assessments-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/paylocity/assessments-api/revisions/dd22ab229153/schema)