Order

Overview

The patch operation on the assessee status endpoint allows you to update the status of the overall assessment order and relay the results of the assessment. You can also send the URL where the requester can view the complete assessment result.

Property	Type	Required/Optional	Description
partnerTrackingId	string	Optional	Partner tracking id used for troubleshooting.
overallScore	string Max length = 30	Optional	An indication of if the assessee met all necessary predetermined ranges set for the job.
overallScoreDescription	string Max length = 250	Optional	Description of the overall score.
overallReport	object	Optional	Combined report of all of the assessments within a package.
overallReport.name	string Max length = 50	Optional	The name of the report.
overallReport.url	string Max length = 250	Optional	The URL of the report that can be viewed on the partners web application.
assessmentResults	Object of assessments results	Optional	The object of the results for an assessment.
assessmentResults.Score	string Max length = 30	Optional	Score for the assessment, which could be made up of one or multiple tests.
assessmentResults.ScoreDescription	string Max length = 250	Optional	Description of the assessment score.
assessmentResults.Report	Object	Optional	Report for the assessment order, could contain one or multiple tests.
assessmentResults.report..name	string Max length = 50	Optional	The name of the report
assessmentResults.report..url	string Max length = 250	Optional	The URL of the report that can be viewed on the partners web application.
tests	Array of tests results	Optional
tests.id	String Max length = 36	Required	ID of the test
tests.score.value	String Max length = 50	Required	The value of the score
tests.score.description	String Max length = 250	Optional	The description of the score This is an optional field where you can add description of what the score means for the assessee relative to the job posting.
tests.score.attempt	int	Required	Partners are responsible for sending the test attempt count if they support retest functionality. This field is for the count of The number of attempts the assessee has had on the test
tests.score.reports.name	String Max length = 50	Optional	The name of the report
tests.score.reports.url	String Max length = 250	Optional	The URL of the report that can be viewed on the partners web application.
tests.status	object	Optional	Test status with test.
tests.status.updatedAt	string (date-time format. Ex: 2023-01-13T11:45:44.815Z)	Required	The date and time when the assessment test was updated.
tests.status.value	string	Required	The new status of the assessment test.

Business Logic Notes

Tests collection update logic is the following: every new combination of id and attempt creates a new record in AssessmentOrderTests table (which represents test attempts); if API gets a request to update a test with id and attempt number already existing in the database, then it updates the corresponding record;
Reports collection for already existing test attempt always gets updated by simply adding newly provided items to the existing collection.

For statuses and their application see the below example:

Software Engineer II (name of package)
- Software Engineer Skills (name of the assessment battery)
  - JavaScript code challenge (name of test)
  - Ruby code challenge (name of test)

There will not be a status on the name of package, but there will be the ability to provide a status on the assessment battery level and the individual test level. The above example would translate into the below for statuses:

Software Engineer Skills - In Progress
- JavaScript code challenge – Complete
- Ruby code challenge - Not started

Assessment Battery Level: The table below explains the order statuses with the relevant definitions.

Status	Definition
Ordered	Default status when the assessmentrequest is submitted. Assessmentpartner doesnt have to send this back to PCTY since its the default status.
WaitingOnAssessee	When the assessment partner has initiated the assessment process by emailing the assessee.
InProgress	When the assessee started at least one test in the assessment battery. At this point the assessment is in progress, and we are waiting for the candidate to complete all tests part of the assessment battery.
Hold	When more information is requested from the assessee or employee to run the assessment.
Complete	When the assessment is complete. At this point all the underlying assessment tests are completed and a final report is available to the client.
Complete - Review	This can be used when all the tests that are part of the assessment are taken but at least one but not all tests are flagged for retest.
Retest Recommended	This can be used when all tests in the assessment are recommended for retesting.
Expired	This will be used when the assessment was sent to the assessee, but the assessee never started the assessment and/or it was started but never completed. This is up to the partner and clients to determine when expired status should be sent. This status will function the same as a ‘complete’ status.

Individual Test Level: The table below explains the order statuses with the relevant definitions.

Status	Definition
Pending	Default status when the assessment request is submitted. Assessment partner doesn’t have to send this back to PCTY since it’s the default status.
InProgress	This can be used when the assessee has started the assessment. At this point the assessment is in progress, and we are waiting for the candidate to complete.
Hold	When more information is requested from the assessee and/or client to send the assessment.
Complete	When the assessment is complete. At this point all the underlying assessment tests are completed and a final report is available to the client.
Retest Recommended	Used when partner recommends that a certain test the assessee took should be retaken.
Expired	Used when the assessment test invite expired and candidate would need to be resent an assessment test to complete.

Completed Statuses Business Logic

There is API validation that happened for completed statuses for assessment level statuses. This is a requirement when a partner is sending one of the completed statuses on the assessment level. It will mean that in order for an assessment level status to be changed to status 'complete' that all tests encompassed in that assessment package will need to be in a 'completed' status as well, or a status that maps to complete.

Assessment level: Complete statuses

Complete
Complete - Review
Expired

Test level statuses: tests need to be in one of the below statuses in order for the assessment level status to be changed one of the 3 above:

Complete
Retest Recommended
Expired

Please note, this is not a requirement that all tests need to have the same status, just all tests need to be in any of those test statuses listed above. For example we could have the below on an assessment package with 2 tests:

If assessment status is Complete - Review, Then the test statuses could be

Test 1: Complete
Test 2: Retest Recommended

If assessment status is Expired, Then the test statuses could be:

Test 1: Complete
Test 2: Expired

These don’t include all scenarios, but it is to show that any ‘complete’ assessment level status can be paired with any ‘complete’ test level status

Package Statuses Business Logic

Partners will not send Package level statuses, instead those will be calculated in the UI for clients to see. Package level statuses and logic is below to provide context. The Global Status page will show this package level status, but also group these packages into the correct tabs based on this status.

Package level statuses:

In Progress
Actions Needed
Completed

For the package level statuses:

If any assessment status is in any of the ‘In Progress’ statuses mapped below, ‘In Progress’ will always trump Completed or Action Needed
If all assessments are in any of the ‘Completed’ (complete status also include Actions Needed) statuses, but there is at least one ‘Action Needed’ then the ‘Action Needed’ will always trump a 'completed' status
If all assessments are complete and there are no ‘action needed’ statuses, then the package status should map to ‘Completed’

Assessment level status (left) -> Mapped for package status (right)

Ordered – In Progress
Waiting On Assessee – In Progress
In Progress – In Progress
Complete – Completed
Hold – Actions Needed
Complete - review – Actions Needed
Retest Recommended – Actions Needed
Expired – Actions Needed

Report URLs

All report URLs must be secured, Paylocity will not support pre-authorized URLs. Users must be forced to login, or there must be some verification of the user on the partner's side, to display the report results.