---
updatedAt: 2026-05-11T22:22:56.000Z
agentTools:
  siteIndex: https://developer.paylocity.com/llms.txt
  projectIndex: https://developer.paylocity.com/integrations/llms.txt
---

# Create Webhook for Candidate Screening Order

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

# OpenAPI definition

```json
{
  "openapi": "3.0.4",
  "info": {
    "title": "Background Check API",
    "version": "v1"
  },
  "servers": [
    {
      "url": "dc1demogwext.paylocity.com"
    }
  ],
  "paths": {
    "/compliance/v1/companies/b6001/backgroundCheck/candidateScreeningOrders/subscription": {
      "post": {
        "tags": [
          "Subscription"
        ],
        "summary": "Create Webhook for Candidate Screening Order",
        "description": "> 🚧 Partner Restricted\n> 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.\n\n**Summary Description**\n\nRegister 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.\n\n**Use Cases**\n\n- **Webhook Registration**\nPartner provides the webhook URL for new candidate orders\n\n- **Callback Response (below Responses section at bottom of page)**\nWhen 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.\n\n- **Example Use Case:**\nA 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.",
        "x-explorer-enabled": false,
        "operationId": "ComplianceBackgroundCheckCandidateScreeningOrdersSubscriptionCreate",
        "parameters": [
          {
            "name": "testMode",
            "in": "header",
            "description": "If true all responses are mocked and generated randomly",
            "schema": {
              "type": "boolean"
            },
            "example": false
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Authorization token. Ex. Bearer ...",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Bearer <token>"
          }
        ],
        "requestBody": {
          "description": "The callback information",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscribeNewCandidateScreeningOrderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns the details of the registration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscribeNewCandidateScreeningOrderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request Error - Returns the details of the error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericErrorResponse"
                },
                "examples": {
                  "UnsupportedXmlContentType": {
                    "summary": "The API only supports JSON, but XML was provided.",
                    "value": {
                      "correlationId": "unsupported-media-type-xml-correlation-id",
                      "value": {
                        "code": "UNSUPPORTED_MEDIA_TYPE",
                        "message": "The request content type is not supported."
                      },
                      "count": 1,
                      "values": [
                        {
                          "fields": "Content-Type: application/xml",
                          "code": "UNSUPPORTED_MEDIA_TYPE",
                          "message": "The request content type is not supported."
                        }
                      ]
                    }
                  },
                  "MissingContentTypeHeader": {
                    "summary": "The Content-Type header is missing or empty.",
                    "value": {
                      "correlationId": "unsupported-media-type-missing-header-correlation-id",
                      "value": {
                        "code": "UNSUPPORTED_MEDIA_TYPE",
                        "message": "The request content type is not supported."
                      },
                      "count": 1,
                      "values": [
                        {
                          "fields": "Content-Type",
                          "code": "UNSUPPORTED_MEDIA_TYPE",
                          "message": "The request content type is not supported."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "415": {
            "description": "Unsupported Media Type - Returns the details of the error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericErrorResponse"
                },
                "examples": {
                  "UnsupportedXmlContentType": {
                    "summary": "The API only supports JSON, but XML was provided.",
                    "value": {
                      "correlationId": "unsupported-media-type-xml-correlation-id",
                      "value": {
                        "code": "UNSUPPORTED_MEDIA_TYPE",
                        "message": "The request content type is not supported."
                      },
                      "count": 1,
                      "values": [
                        {
                          "fields": "Content-Type: application/xml",
                          "code": "UNSUPPORTED_MEDIA_TYPE",
                          "message": "The request content type is not supported."
                        }
                      ]
                    }
                  },
                  "MissingContentTypeHeader": {
                    "summary": "The Content-Type header is missing or empty.",
                    "value": {
                      "correlationId": "unsupported-media-type-missing-header-correlation-id",
                      "value": {
                        "code": "UNSUPPORTED_MEDIA_TYPE",
                        "message": "The request content type is not supported."
                      },
                      "count": 1,
                      "values": [
                        {
                          "fields": "Content-Type",
                          "code": "UNSUPPORTED_MEDIA_TYPE",
                          "message": "The request content type is not supported."
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "callbacks": {
          "New candidateScreeningOrder background check request": {
            "https://example.com": {
              "post": {
                "summary": "This is a webhook that occurs when new request for candidateScreeningOrder background checks occurs",
                "requestBody": {
                  "content": {
                    "application/json": {
                      "schema": {
                        "$ref": "#/components/schemas/NewCandidateScreeningOrderEventPayloadData"
                      }
                    }
                  }
                },
                "responses": {
                  "200": {
                    "description": "Your server implementation should return this HTTP status code if the data was received successfully"
                  },
                  "400": {
                    "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted.",
                    "content": {
                      "application/json": {
                        "schema": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "string",
                              "description": "Error code. Optional.",
                              "nullable": true
                            },
                            "message": {
                              "type": "string",
                              "description": "Error message. Optional.",
                              "nullable": true
                            }
                          },
                          "description": "Error response object definition."
                        }
                      }
                    }
                  },
                  "500": {
                    "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. No retries are attempted.",
                    "content": {
                      "application/json": {
                        "schema": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "string",
                              "description": "Error code. Optional.",
                              "nullable": true
                            },
                            "message": {
                              "type": "string",
                              "description": "Error message. Optional.",
                              "nullable": true
                            }
                          },
                          "description": "Error response object definition."
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CallbackDetailsDto": {
        "type": "object",
        "properties": {
          "successCallbackUrl": {
            "type": "string",
            "description": "Your callback POST endpoint URL where you will receive new screening orders. Required.\n    **Allowable Values:**\n    256 char max",
            "nullable": true
          },
          "errorCallbackUrl": {
            "type": "string",
            "description": "Your callback POST endpoint where you will receive errors occurred during the POST a new screening order. Required.\n    **Allowable Values:**\n    256 char max",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Callback Details"
      },
      "CallerDetailsDto": {
        "type": "object",
        "properties": {
          "callerName": {
            "type": "string",
            "description": "This is a field used to identify the partner, this typically is the company name.\n    **Allowable Values:**\n    50 char max",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "CandidateExternalDto": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Holds the title of the candidate, e.g., Mr., Ms., Dr.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "firstName": {
            "type": "string",
            "description": "Candidate's first name.",
            "nullable": true,
            "x-pcty-filterable": true,
            "x-pcty-filter-operators": "eq,ne,in"
          },
          "middleName": {
            "type": "string",
            "description": "Candidate's middle name.",
            "nullable": true,
            "x-pcty-filterable": true,
            "x-pcty-filter-operators": "eq,ne,in"
          },
          "lastName": {
            "type": "string",
            "description": "Candidate's last name.",
            "nullable": true,
            "x-pcty-filterable": true,
            "x-pcty-filter-operators": "eq,ne,in"
          },
          "email": {
            "type": "string",
            "description": "Candidate's email address.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "mobile": {
            "type": "string",
            "description": "Candidate's mobile phone number.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "location": {
            "type": "string",
            "description": "Location of the candidate.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "address": {
            "type": "string",
            "description": "Address of the candidate.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "country": {
            "type": "string",
            "description": "Country of the candidate.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "city": {
            "type": "string",
            "description": "City of the candidate.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "province": {
            "type": "string",
            "description": "Province of the candidate.",
            "nullable": true,
            "x-pcty-filterable": false
          }
        },
        "additionalProperties": false
      },
      "ErrorDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code associated with the error.",
            "nullable": true
          },
          "message": {
            "type": "string",
            "description": "Descriptive message detailing the error.",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "GenericErrorResponse": {
        "type": "object",
        "properties": {
          "correlationId": {
            "type": "string",
            "description": "A unique identifier used for tracing and correlation purposes.",
            "nullable": true
          },
          "value": {
            "$ref": "#/components/schemas/ErrorDto"
          },
          "count": {
            "type": "integer",
            "description": "Gets the count of items in the Values list.",
            "format": "int32",
            "nullable": true,
            "readOnly": true
          },
          "values": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ValidationErrorDto"
            },
            "description": "A list of items.",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "NewCandidateScreeningOrderEventPayloadData": {
        "type": "object",
        "properties": {
          "candidateScreeningOrder": {
            "$ref": "#/components/schemas/PartnerCandidateScreeningOrderDto"
          }
        },
        "additionalProperties": false
      },
      "PartnerCandidateScreeningOrderDto": {
        "type": "object",
        "properties": {
          "candidateScreeningOrderId": {
            "type": "string",
            "description": "Unique identifier for the candidate screening order.",
            "format": "uuid"
          },
          "candidate": {
            "$ref": "#/components/schemas/CandidateExternalDto"
          },
          "companyId": {
            "type": "string",
            "description": "Identifier for the company associated with the screening.",
            "nullable": true
          },
          "packageId": {
            "type": "string",
            "description": "Identifier for the screening package selected.",
            "nullable": true
          },
          "billingCode": {
            "type": "string",
            "description": "Billing code associated with the screening order.",
            "nullable": true
          },
          "location": {
            "type": "string",
            "description": "Location associated with the screening order.",
            "nullable": true
          },
          "recruiter": {
            "$ref": "#/components/schemas/RecruiterDto"
          },
          "workAddress": {
            "type": "string",
            "description": "WorkAddress associated with the screening order.",
            "nullable": true
          },
          "workCity": {
            "type": "string",
            "description": "WorkCity associated with the screening order.",
            "nullable": true
          },
          "workCountry": {
            "type": "string",
            "description": "WorkCountry associated with the screening order.",
            "nullable": true
          },
          "workProvince": {
            "type": "string",
            "description": "WorkProvince associated with the screening order.",
            "nullable": true
          },
          "jobData": {
            "$ref": "#/components/schemas/PartnerJobDataDto"
          },
          "businessUnitId": {
            "type": "string",
            "description": "Business Unit ID associated with the screening order. Optional.",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "PartnerJobDataDto": {
        "type": "object",
        "properties": {
          "jobTitle": {
            "type": "string",
            "description": "The position name that identifies the individual’s role in the company. Optional.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "positionCode": {
            "type": "string",
            "description": "A unique code or identifier that represents the individual’s position or job role within an organization. Optional.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "costCenter1Name": {
            "type": "string",
            "description": "The name or title of the cost center, offering a clear and descriptive label for easy recognition and understanding of its role and responsibilities. Optional.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "costCenter2Name": {
            "type": "string",
            "description": "The name or title of the cost center, offering a clear and descriptive label for easy recognition and understanding of its role and responsibilities. Optional.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "costCenter3Name": {
            "type": "string",
            "description": "The name or title of the cost center, offering a clear and descriptive label for easy recognition and understanding of its role and responsibilities. Optional.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "costCenter1Code": {
            "type": "string",
            "description": "A code or label representing the cost center, aiding in its categorization and differentiation within the organization's financial and operational framework. Optional.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "costCenter2Code": {
            "type": "string",
            "description": "A code or label representing the cost center, aiding in its categorization and differentiation within the organization's financial and operational framework. Optional.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "costCenter3Code": {
            "type": "string",
            "description": "A code or label representing the cost center, aiding in its categorization and differentiation within the organization's financial and operational framework. Optional.",
            "nullable": true,
            "x-pcty-filterable": false
          }
        },
        "additionalProperties": false,
        "description": "Job data associated with the screening order."
      },
      "RecruiterDto": {
        "type": "object",
        "properties": {
          "recruiterId": {
            "type": "string",
            "description": "Unique identifier for the recruiter.",
            "nullable": true,
            "x-pcty-filterable": true,
            "x-pcty-filter-operators": "eq,ne,in"
          },
          "firstName": {
            "type": "string",
            "description": "First name of the recruiter.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "lastName": {
            "type": "string",
            "description": "Last name of the recruiter.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "email": {
            "type": "string",
            "description": "Email address of the recruiter.",
            "nullable": true,
            "x-pcty-filterable": false
          },
          "certificationDateTime": {
            "type": "string",
            "description": "The date and time when the recruiter was certified. Date format in ISO 8601.",
            "format": "date-time",
            "x-pcty-filterable": false
          }
        },
        "additionalProperties": false
      },
      "SubscribeNewCandidateScreeningOrderRequest": {
        "type": "object",
        "properties": {
          "apiKey": {
            "type": "string",
            "description": "Optional. The value of the x-api-key header to utilize while executing the callback.\n                **Allowable Values:**\n                50 char max",
            "nullable": true
          },
          "callbackDetails": {
            "$ref": "#/components/schemas/CallbackDetailsDto"
          },
          "callerDetails": {
            "$ref": "#/components/schemas/CallerDetailsDto"
          }
        },
        "additionalProperties": false
      },
      "SubscribeNewCandidateScreeningOrderResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "Status",
            "nullable": true
          },
          "webhookCallbackId": {
            "type": "string",
            "description": "GUID of the callback.",
            "format": "uuid"
          },
          "requestObject": {
            "$ref": "#/components/schemas/SubscribeNewCandidateScreeningOrderRequest"
          }
        },
        "additionalProperties": false,
        "description": "Response of successfully registed webhook."
      },
      "ValidationErrorDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code associated with the error.",
            "nullable": true
          },
          "message": {
            "type": "string",
            "description": "Descriptive message detailing the error.",
            "nullable": true
          },
          "fields": {
            "type": "string",
            "description": "A string detailing the fields involved in the validation error.",
            "nullable": true
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "Bearer": {
        "type": "apiKey",
        "description": "CC JWT Authorization header using the bearer scheme",
        "name": "Authorization",
        "in": "header"
      }
    }
  },
  "security": [
    {
      "Bearer": []
    }
  ]
}
```