GuidesAPI ReferenceChangelog



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:

CallbackDetails objectRequiredAn object containing the success and error callback.

Max length = 256
RequiredThe URL to be called in case of successful execution of the webhook.

Max length = 256
OptionalThe URL to be called when the success callback returns an error.

Max length = 256
OptionalURL 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
callerDetailsobjectRequiredAn object containing the callers name.

Max length = 50
RequiredThe name of the caller.

Max length = 50
RequiredThe value of the x-api-key header to utilize while executing the callback.
assessmentOrderLevelEnumOptionalIndicator 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:

orderIdstringRequiredThe ID of the assessee assessment order.
packageDetailsobjectRequiredDetails of package associated with the order.

Max length = 36
RequiredThe unique identifier for the package associated with the assessmentorder.

Max length = 36
RequiredThe unique identifier for the assessment associated with the assessmentorder.
testsArray of test idsRequiredThe unique identifiers of tests id associated with package and order.

Max length = 20
OptionalThe ID of job that assessee is applying to.

Max length = 9
OptionalThe ID of the Paylocity company.

Max length = 16
OptionalThe billing code associated with the assessmentorder.

Max length = 250
OptionalThe job location associated with the assessment order.
requesterobjectOptionalAn object containing the details of the requester who created the assessment order.

Max length = 40
OptionalThe requester’s first name.

Max length = 40
OptionalThe requester’s last name.

Max length = 50
OptionalThe requester’s email address.
assesseeobjectRequiredAn object containing the details of the assessee being screened.
assessee.idGuidRequiredThe assesses id.

Max length = 50
RequiredThe assessee’s job title they are applying for.

Max length = 40
RequiredThe assessee’s first name.

Max length = 40
OptionalThe assessee’s middle name.

Max length = 40
RequiredThe assessee’s last name.

Max length = 50
RequiredThe assessee’s email address.

Max length = 25
OptionalThe assessee’s mobile number.

Max length = 250
OptionalThe 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.

jobTitlestringRequiredThe name of the job that the client is trying to verify.
companyIdstringRequiredThe ID of the Paylocity company.
jobIdstringRequiredThe ID of job that the client is verifying.

Copyright © 2024 Paylocity. All Rights Reserved. Privacy Center | Terms and Conditions | Accessibility