GuidesRecipesAPI ReferenceChangelog
API Reference

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.

PropertyTypeRequired/OptionalDescription
partnerTrackingIdstringOptionalPartner tracking id used for troubleshooting.
overallScorestring

Max length = 30
OptionalAn indication of if the assessee met all necessary predetermined ranges set for the job.
overallScoreDescriptionstring

Max length = 250
OptionalDescription of the overall score.
overallReportobjectOptionalCombined report of all of the assessments within a package.
overallReport.namestring

Max length = 50
OptionalThe name of the report.
overallReport.urlstring

Max length = 250
OptionalThe URL of the report that can be viewed on the partners web application.
assessmentResultsObject of assessments resultsOptionalThe object of the results for an assessment.
assessmentResults.Scorestring

Max length = 30
OptionalScore for the assessment, which could be made up of one or multiple tests.
assessmentResults.ScoreDescriptionstring

Max length = 250
OptionalDescription of the assessment score.
assessmentResults.ReportObjectOptionalReport for the assessment order, could contain one or multiple tests.
assessmentResults.report..namestring

Max length = 50
OptionalThe name of the report
assessmentResults.report..urlstring

Max length = 250
OptionalThe URL of the report that can be viewed on the partners web application.
testsArray of tests resultsOptional
tests.idString
Max length = 36
RequiredID of the test
tests.score.valueString
Max length = 50
RequiredThe value of the score
tests.score.descriptionString
Max length = 250
OptionalThe 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.attemptintRequiredPartners 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.nameString
Max length = 50
OptionalThe name of the report
tests.score.reports.urlString
Max length = 250
OptionalThe URL of the report that can be viewed on the partners web application.
tests.statusobjectOptionalTest status with test.
tests.status.updatedAtstring (date-time format. Ex: 2023-01-13T11:45:44.815Z)RequiredThe date and time when the assessment test was updated.
tests.status.valuestringRequiredThe 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.

StatusDefinition
OrderedDefault status when the assessmentrequest is submitted. Assessmentpartner doesnt have to send this back to PCTY since its the default status.
WaitingOnAssesseeWhen the assessment partner has initiated the assessment process by emailing the assessee.
InProgressWhen 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.
HoldWhen more information is requested from the assessee or employee to run the assessment.
CompleteWhen the assessment is complete. At this point all the underlying assessment tests are completed and a final report is available to the client.
Complete - ReviewThis 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 RecommendedThis can be used when all tests in the assessment are recommended for retesting.
ExpiredThis 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.

StatusDefinition
PendingDefault status when the assessment request is submitted. Assessment partner doesn’t have to send this back to PCTY since it’s the default status.
InProgressThis 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.
HoldWhen more information is requested from the assessee and/or client to send the assessment.
CompleteWhen the assessment is complete. At this point all the underlying assessment tests are completed and a final report is available to the client.
Retest RecommendedUsed when partner recommends that a certain test the assessee took should be retaken.
ExpiredUsed 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.

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