Introduction
The Assessment API product enables you to integrate pre-hire assessments into Paylocity's platform, receive the assessment request, and post updates to an assessment order.
Using the Assessment API product, you can build an integrated experience that allows Paylocitys customers to:
Onboard your integrated solution via Paylocity’s integration marketplace.
Initiate assessments on candidates or employees when needed.
Receive real-time updates for the assessments they have initiated.
Getting Started
Access to the Paylocity Assessment API can be provided by sending a request to our team using the following link: Request Credentials– [email protected]
Once you receive your Client ID and Client Secret, these are the steps that you should follow to start receiving new assessment orders:
Client Onboarding
For information on how to onboard a client please review the Partner Onboarding API
Step 1: POST Authentication
curl --location --request POST https://gwext.paylocity.com/public/security/v1/token \
--header Content-Type: application/x-www-form-urlencoded \
--data-urlencode client_id=<your client id> \
--data-urlencode client_secret=<your secret> \
--data-urlencode grant_type=client_credentials
Once you send an auth request with your Client ID and Client Secret, the response contains an access token which can be used to send other requests to the API.
Step 2: PUT
/performanceManagement/v1/companies/b6001/assessmentOrders/callback
Register your endpoint where you will receive the assessment orders for all assessees:
curl --location --request PUT https://gwext.paylocity.com/apiHub/performanceManagement/v1/companies/b6001/assessmentOrders/callback\
--header Authorization: Bearer <token returned in step 1> \
--header Content-Type: application/json \
--data-raw {
"callbackDetails": {
"successCallbackUrl": "<your POST endpoint where you want to receive new AssessmentOrders>",
"errorCallbackUrl": "<optional your POST endpoint where you want to receive errors>",
"jobCreationCallbackUrl": "<optional your POST endpoint where you want to receive created jobs>"
},
"callerDetails": {
"callerName": "<your name>"
}
}
Note that your Endpoint for new assessmentorders receives this JSON on the success url registered with Paylocity. If the call to success url fails, then we will update the error url. The Assessee AssessmentOrder payload section provides more insights into the assessee information Paylocity will share with you.
{
"assessmentOrder": {
"orderId": "string",
"packageId": "string",
“tests”: [
“testId” : “string”
]
“jobId”: “string”,
"companyId": "string",
"billingCode": "string",
"location": "string",
"requester": {
"firstName": "string",
"lastName": "string",
"email": "string",
"certificationDateTime": "2012-10-28T00:30:00.0000000Z"
},
"assessee": {
"title": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"email": "string",
"mobile": "string",
"location": "string"
}
}
}
Step 3: PUT
/apiHub/performanceManagement/v1/companies/{companyId}/assessmentPackages/{packageId}
A PUT on the /packages endpoint inserts or updates a list of the packages defined for Paylocitys customers. A Package is essentially a combined group of assessment services that Paylocitys customer will be paying for.
This step can either be done for all companies that will be using your integration by using company ID B6001, or it can be done on an individual company basis using that company’s specific company ID. More information regarding the assessmentPackages endpoint can be found in the Package endpoint.
For inserting or updating existing Packages
curl --location --request PUT https://gwext.paylocity.com /apiHub/performanceManagement/v1/companies/b6001/assessmentPackages/123
--header Authorization: Bearer <token returned in step 1> \
--header Content-Type: application/json \
--data-raw {
"assessments": [
{
"id": "d23e310f-f49a-43db-988f-f083689e3865",
"name": "Business Analyst Assessment",
"summary": "Set of test for Business Analysts"
"tests": [
{
"id": " fb92492b-dcb3-4490-b077-edaa7f73e9e7",
"name": "SQL",
"category": "Data Skills",
"description": "Test SQL Skills"
},
{
"id": "15c27b77-5c71-4527-95bd-9bf034aa1f45",
"name": "Analyzing data with Excel",
"category": "Data Skills",
"description": "Excel Skills"
},
...
}
]
}
Step 4: PUT – Subscription details
/apiHub/performanceManagement/v1/companies/{companyId}/assessmentOrders/subscription
A PUT on the assessmentOrders/subscription endpoint inserts or updates a subscription details per company. It includes pricing, currency, expirationDate and billingCodes.
For inserting or updating subscription
curl --location --request PUT https://gwext.paylocity.com /apiHub/performanceManagement/v1/companies/b6001/assessmentOrders/subscription
--header Authorization: Bearer <token returned in step 1> \
--header Content-Type: application/json \
--data-raw {
"level":"some level",
"price": 100.5,
"currency": "USD",
"term":"term",
"expirationDate":"2012-10-28T00:30:00.0000000Z",
“billingCodes”: [
“code”: “code1”,
“code”: “code2”
]
}
}
Errors
Assessment API product uses HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate a success, codes in the 4xx range indicate a request that failed given the information provided (e.g., a required parameter was omitted, format issues, etc.), and codes in the 5xx range indicate a server error.
NOTE: The error message contains a CorrelationId field. This field helps to troubleshoot errors and it should always be provided when you contact support.
In the case of 4XX errors, the body contains additional information in the following format:
{
"CorrelationId": "170f69a9-1319-4e10-877f-90d4aaa555ba",
"Count": 2,
"Values": [
{
"Fields": " price",
"Code": "field_required",
"Message": "The field was required"
},
{
"Fields": "price",
"Code": "greater_then",
"Message": "Value must be greater than 1."
}
]
}
In the case of 5xx errors, the format is the following:
{
"CorrelationId": "50bda3ea-9a63-441d-9663-fada5cafab28",
"Value": {
"Code": "internal_error",
"Message": "You need to add a request body!"
}
}
Versioning
Assessment API product follows major version number included in the URI route:
..../apiHub/performanceManagement/v1/companies/{companyId}/assessment....
Query strings or header values will not be utilized to identify versions of resources.
Non-Breaking Changes
Non-breaking changes will not increment the major version number. Examples of non-breaking changes include:
- Adding a non-required field
- Additions of new fields in the response
Breaking Changes
Unavoidable breaking changes will increment a resources major version number.
..../apiHub/performanceManagement/v1/companies/{companyId}/assessment....
To
..../apiHub/performanceManagement/v2/companies/{companyId}/assessment....
Examples include:
- Adding a required field without a default value
- Removing a field
- Changing the data type of a field
For a major version, although fields will not be removed from responses, fields may be added to introduce new capabilities. Applications consuming this API should use permissive deserialization techniques when parsing JSON responses. It is always safe to ignore unrecognized, optional fields.
Authentication
Please refer to the Authentication page in the API Basics section
Sandbox
You can use it to simulate the production environment to call the API.
The Sandbox domain is the following:
https://demogwext.paylocity.com
Testing
Paylocity supports test mode with every API.
To use Paylocity endpoints in test mode its required to add “testmode” header with value “true” to the request. Please note that the request should still contain a valid authorization token and request body with valid format.
All the responses in test-mode are mocked and are generated randomly, therefore you cant expect that mocked results would be relevant to previously created data.
CURL example:
curl --request GET https://gwext.paylocity.com/apiHub/performanceManagement/v1/companies/b6001/assessmentPackages\
--header Authorization: Bearer <access_token>
--header testmode: true