🚧

Partner Restricted

All assessment API endpoints are restricted to assessment providers that have signed a Paylocity technology partnership agreement. Please reach out to [email protected] if you would like to discuss partnership opportunities.

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

Client Onboarding: Company Sets

Paylocity has individual companies and something referred to as company sets, which is a group of individual company IDs that roll up into the main "company set". Company sets can have any number of company IDs. When onboarding Paylocity clients it is important to note that the Assessment integration is based on company ID and not company set ID. This means that Partners will need to work with clients to make sure that they capture ALL Paylocity company IDs and onboard each one of those companies one at a time using the Partner Onboarding API. The Partner will also have to sync packages on each company ID.

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, this can be found under the PUT Callback endpoint at the bottom of the page in the section called: Callbacks: Submit assessment order to partners.

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

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

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:

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!" 
  } 
} 

Retry Logic

There are 2 ways that clients can enable assessment orders. Either through automatic assign, which sends the assessment to every candidate that completes a job application, or through manual assign, which the recruiter will order the assessment on a per candidate basis as needed. The order API remains the same for either flow, but the retry logic is different to account for the needs of these different scenarios.

Retry logic from the automatic assign flow:

• We will retry to send the order 6 times in five minute increments at at 5, 10, 15, 20, 25, and 30 minutes. If all six retries are unsuccessful, the order request will fail and be logged as such.

Retry logic from the manual order flow:

• Our policy retries up to 3 times, with exponentially increasing delays:
  • 1st retry: 2 seconds
  • 2nd retry: 4 seconds
  • 3rd retry: 8 seconds
    If order creation fails after 3 attempts, we will try to submit the order to the error callback without any retries. If job creation fails after 3 attempts, we will not submit it to the error callback. We do not retry if the API returns a BadRequest, Unauthorized, Forbidden, or NotFound status code.

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