---
title: "Create Webhook for Candidate Screening Order"
method: POST
path: "/compliance/v1/companies/b6001/backgroundCheck/candidateScreeningOrders/subscription"
tags: ["Subscription"]
---

# Create Webhook for Candidate Screening Order

`POST /compliance/v1/companies/b6001/backgroundCheck/candidateScreeningOrders/subscription`

> 🚧 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**

Register the webhook URL for subscribing to new *CandidateScreeningOrder* events. Once registered, the partner’s webhook will receive real-time notifications whenever a new candidate order is placed.

**Use Cases**

- **Webhook Registration**
Partner provides the webhook URL for new candidate orders

- **Callback Response (below Responses section at bottom of page)**
When an order is placed for a candidate within a Paylocity module, the partner’s webhook will receive a callback URL response containing the order payload. This payload includes the details of the order and can be used by the partner to initiate their own workflows.

- **Example Use Case:**
A client places a background check order for a candidate in the Recruiting module. The partner receives the order payload through their registered webhook URL and can process the request immediately.

## Headers

- `testMode` boolean
- `Authorization` string, required

## Request body

- SubscribeNewCandidateScreeningOrderRequest
  - `apiKey` string, nullable — Optional. The value of the x-api-key header to utilize while executing the callback. **Allowable Values:** 50 char max
  - `callbackDetails` CallbackDetailsDto — Callback Details
    - `successCallbackUrl` string, nullable — Your callback POST endpoint URL where you will receive new screening orders. Required. **Allowable Values:** 256 char max
    - `errorCallbackUrl` string, nullable — Your callback POST endpoint where you will receive errors occurred during the POST a new screening order. Required. **Allowable Values:** 256 char max
  - `callerDetails` CallerDetailsDto
    - `callerName` string, nullable — This is a field used to identify the partner, this typically is the company name. **Allowable Values:** 50 char max

## Response `200`

Returns the details of the registration

- SubscribeNewCandidateScreeningOrderResponse — Response of successfully registed webhook.
  - `status` string, nullable — Status
  - `webhookCallbackId` string, uuid — GUID of the callback.
  - `requestObject` SubscribeNewCandidateScreeningOrderRequest
    - `apiKey` string, nullable — Optional. The value of the x-api-key header to utilize while executing the callback. **Allowable Values:** 50 char max
    - `callbackDetails` CallbackDetailsDto — Callback Details
      - `successCallbackUrl` string, nullable — Your callback POST endpoint URL where you will receive new screening orders. Required. **Allowable Values:** 256 char max
      - `errorCallbackUrl` string, nullable — Your callback POST endpoint where you will receive errors occurred during the POST a new screening order. Required. **Allowable Values:** 256 char max
    - `callerDetails` CallerDetailsDto
      - `callerName` string, nullable — This is a field used to identify the partner, this typically is the company name. **Allowable Values:** 50 char max

## 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/versions/dd22ab229153/schema)