---
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`

## Request

- Base URL: `dc1demogwext.paylocity.com` (relative, and the document’s source URL is not known)
- URL: `dc1demogwext.paylocity.com/compliance/v1/companies/b6001/backgroundCheck/candidateScreeningOrders/subscription`
- Auth: API key in header `Authorization`

> 🚧 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.dev/paylocity/apis/background-check-api.md) - [All operations](https://skmtc.dev/paylocity/apis/background-check-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paylocity/apis/background-check-api/revisions/8d585de5e05e?raw)