GuidesRecipesAPI ReferenceChangelog
API Reference

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:

PropertyTypeRequired/OptionalDescription
CallbackDetails objectRequiredAn object containing the success and error callback.
callbackDetails.successCallbackUrlstring

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

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

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.
CallDetails.callerNamestring

Max length = 50
RequiredThe name of the caller.
apiKeystring

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:

ParameterTypeRequired/OptionalDescription
orderIdstringRequiredThe ID of the assessee assessment order.
packageDetailsobjectRequiredDetails of package associated with the order.
packageIdstring

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

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

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

Max length = 9
OptionalThe ID of the Paylocity company.
billingCodeString

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

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

Max length = 40
OptionalThe requester’s first name.
requester.lastNameString

Max length = 40
OptionalThe requester’s last name.
requester.emailString

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

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

Max length = 40
RequiredThe assessee’s first name.
assessee.middleNameString

Max length = 40
OptionalThe assessee’s middle name.
assessee.lastNameString

Max length = 40
RequiredThe assessee’s last name.
assessee.emailString

Max length = 50
RequiredThe assessee’s email address.
assessee.mobileString

Max length = 25
OptionalThe assessee’s mobile number.
assessee.locationString

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.


PropertyTypeRequired/OptionalDescription
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