Callback

Overview

The Callback endpoint allows you to register callback URL(s) where you can receive the assessee information used to initiate the assessment process and submit subscription details. It allows you to read, write, and delete the callback URL when needed.

Both endpoints need to respond within 20 seconds with an HTTP status indicating the success (200) or failure (4xx or 5xx).

When you initialize the callback URLs, you can set this per companyId to use different endpoints per customer or you can use b6001 here and use the same endpoints for all customers integrated with your platform. Once you have stored a URL within our database, you can retrieve the same URL using the Get method. If you want to change that URL, call the Put method.

The PUT endpoint contains the two payloads that Paylocity could be sending to the Partner. The callbacks are: Job Creation and Order. Please see below for more information.

The request body should contain a JSON object with the following properties:

Property	Type	Required/Optional	Description
CallbackDetails	object	Required	An object containing the success and error callback.
callbackDetails.successCallbackUrl	string Max length = 256	Required	The URL to be called in case of successful execution of the webhook.
callbackDetails.errorCallbackUrl	string Max length = 256	Optional	The URL to be called when the success callback returns an error.
callbackDetails.jobCreationCallbackUrl	string Max length = 256	Optional	URL used to create and register job with partner. Optional URL, used only for partners that require special job validation. Example: Partner has 1 assessment and results are dependent on the job title
callerDetails	object	Required	An object containing the callers name.
CallDetails.callerName	string Max length = 50	Required	The name of the caller.
apiKey	string Max length = 50	Required	The value of the x-api-key header to utilize while executing the callback.
assessmentOrderLevel	Enum	Optional	Indicator if assessment order is based on assessment or individual test(s). Possible values: - Assessment - Test Optional field with default value Package

If call to “success” callback fails and “error” callback is provided, our API will POST an error in the format shown in the Errors section in API Basics

Assessment Order Payload

You can see the Order callback at the bottom of the PUT add or update callback endpoint.

An assessee is an individual who will go through the assessment process as part of the recruitment, onboarding, or compliance related events. Paylocity will post the assessee information for the assessment using the webhook URL registered by the assessment provider.

Paylocity is not responsible for assessee compliance nor PII. It is the sole responsibility of the assessment partner to ensure that all compliance and PII steps are completed on their side. To ensure this, Paylocity recommends that the assessment partners capture the assessees consent and the relevant PII data via their web/mobile experience. Paylocity will provide basic assessee information to the assessment partner so that you can initiate the next steps in the journey by contacting the assessee via email or redirect URL.

Callback URL: The URL registered by your company to receive the assessee information for processing the assessmentrequest.

Request params:

Parameter	Type	Required/Optional	Description
orderId	string	Required	The ID of the assessee assessment order.
packageDetails	object	Required	Details of package associated with the order.
packageId	string Max length = 36	Required	The unique identifier for the package associated with the assessmentorder.
assessmentId	string Max length = 36	Required	The unique identifier for the assessment associated with the assessmentorder.
tests	Array of test ids	Required	The unique identifiers of tests id associated with package and order.
jobId	String Max length = 20	Optional	The ID of job that assessee is applying to.
companyId	String Max length = 9	Optional	The ID of the Paylocity company.
billingCode	String Max length = 16	Optional	The billing code associated with the assessmentorder.
location	String Max length = 250	Optional	The job location associated with the assessment order.
requester	object	Optional	An object containing the details of the requester who created the assessment order.
requester.firstName	String Max length = 40	Optional	The requester’s first name.
requester.lastName	String Max length = 40	Optional	The requester’s last name.
requester.email	String Max length = 50	Optional	The requester’s email address.
assessee	object	Required	An object containing the details of the assessee being screened.
assessee.id	Guid	Required	The assesses id.
assessee.title	String Max length = 50	Required	The assessee’s job title they are applying for.
assessee.firstName	String Max length = 40	Required	The assessee’s first name.
assessee.middleName	String Max length = 40	Optional	The assessee’s middle name.
assessee.lastName	String Max length = 40	Required	The assessee’s last name.
assessee.email	String Max length = 50	Required	The assessee’s email address.
assessee.mobile	String Max length = 25	Optional	The assessee’s mobile number.
assessee.location	String Max length = 250	Optional	The assessee’s location.

Job Creation Payload

You can see the Job Creation callback at the bottom of the PUT add or update callback endpoint.

If a Partner requires a job title confirmation in order to score an assessment, the partner can register a job creation callback URL. In that case, Paylocity will send the job title to the partner for the partner to confirm if that title exists in their database or not. If the job title does not exist, the client will continue to try different job titles until they find one that is present in the Partner's system.

Property	Type	Required/Optional	Description
jobTitle	string	Required	The name of the job that the client is trying to verify.
companyId	string	Required	The ID of the Paylocity company.
jobId	string	Required	The ID of job that the client is verifying.