---
updatedAt: 2026-06-18T14:49:46.000Z
agentTools:
  siteIndex: https://developer.paylocity.com/llms.txt
  projectIndex: https://developer.paylocity.com/integrations/llms.txt
---

# Update Assessment Order

> 🚧 Partner Restricted
> All assessment API endpoints are restricted to assessment providers that have signed a Paylocity technology partnership agreement. 
[Please reach out to our team](https://www.paylocity.com/contact/partner-form/) if you would like to discuss partnership opportunities.

**Summary Description**

This endpoint updates the Assessment Order status for the given companyId and OrderId. The patch operation on the candidate status endpoint allows you to update the status of the overall assessment order (package) and the related tests. You can also send the URL where the PCTY user can view the complete assessment result.

**Use Cases**

- Customizable Endpoints: The Partner would use this to provide a general endpoint for all Paylocity clients by specifying b6001
- Notification Management: The Partner would use this endpoint to receive notifications about new orders, errors, and job creation events
- Please note: When using the ‘Complete’ statuses (Complete, Complete- Review, Expired) on Assessment level, all tests statuses must be in a ‘Complete’ status as well (Complete, Retest Recommended, Expired). See the Order Overview page for more information

# OpenAPI definition

```json
{
  "openapi": "3.0.4",
  "info": {
    "title": "Assessments API",
    "version": "v1"
  },
  "servers": [
    {
      "url": "dc1demogwext.paylocity.com"
    }
  ],
  "paths": {
    "/apiHub/performanceManagement/v1/companies/{companyId}/assessmentOrders/{orderId}": {
      "patch": {
        "tags": [
          "Order"
        ],
        "summary": "Update Assessment Order",
        "description": "> 🚧 Partner Restricted\n> All assessment API endpoints are restricted to assessment providers that have signed a Paylocity technology partnership agreement. \n[Please reach out to our team](https://www.paylocity.com/contact/partner-form/) if you would like to discuss partnership opportunities.\n\n**Summary Description**\n\nThis endpoint updates the Assessment Order status for the given companyId and OrderId. The patch operation on the candidate status endpoint allows you to update the status of the overall assessment order (package) and the related tests. You can also send the URL where the PCTY user can view the complete assessment result.\n\n**Use Cases**\n\n- Customizable Endpoints: The Partner would use this to provide a general endpoint for all Paylocity clients by specifying b6001\n- Notification Management: The Partner would use this endpoint to receive notifications about new orders, errors, and job creation events\n- Please note: When using the ‘Complete’ statuses (Complete, Complete- Review, Expired) on Assessment level, all tests statuses must be in a ‘Complete’ status as well (Complete, Retest Recommended, Expired). See the Order Overview page for more information",
        "x-explorer-enabled": false,
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "description": "The Paylocity Company Identifier. This is the unique value provided by Paylocity to each specific Payroll Entity.\r\n                **Allowable Values:**\r\n                9 char max.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "A12345"
          },
          {
            "name": "orderId",
            "in": "path",
            "description": "Unique identifier of the assessment order that was sent to you, the partner.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "testMode",
            "in": "header",
            "description": "If true all responses are mocked and generated randomly.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Authorization token. Ex. Bearer ...",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Assessment order request payload..",
          "content": {
            "application/json-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/PatchOrderRequest"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchOrderRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchOrderRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PatchOrderRequest"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "No Content - Resource has been updated."
          },
          "400": {
            "description": "Bad Request - Returns the details of the error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found - Returns the details of the error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericErrorResponse"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported Media Type - Returns the details of the error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AssessmentResultsDto": {
        "type": "object",
        "properties": {
          "tests": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TestDto"
            },
            "description": "Collection of tests associated with the assessment order. Optional.",
            "nullable": true
          },
          "score": {
            "type": "string",
            "description": "An indication of whether the assessee met all necessary predetermined ranges set for the assessment. Optional.",
            "nullable": true
          },
          "scoreDescription": {
            "type": "string",
            "description": "Description of the assessment score. Optional.",
            "nullable": true
          },
          "reports": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OverallReportDto"
            },
            "description": "Reports of the assessment. Optional.",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        }
      },
      "AssessmentStatusDto": {
        "type": "object",
        "properties": {
          "updatedAt": {
            "type": "string",
            "description": "The date and time when the assessment order was updated. Required.",
            "format": "date-time"
          },
          "value": {
            "enum": [
              "Ordered",
              "WaitingOnAssessee",
              "InProgress",
              "Hold",
              "Complete",
              "CompleteReview",
              "RetestRecommended",
              "Expired"
            ],
            "type": "string",
            "description": "The new status of the assessment order. Required.",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        },
        "description": "Assessment order status payload."
      },
      "ErrorDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "nullable": true
          },
          "message": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        }
      },
      "GenericErrorResponse": {
        "type": "object",
        "properties": {
          "correlationId": {
            "type": "string",
            "nullable": true
          },
          "value": {
            "$ref": "#/components/schemas/ErrorDto"
          },
          "count": {
            "type": "integer",
            "description": "Gets the count of items in the Values list.",
            "format": "int32",
            "nullable": true,
            "readOnly": true
          },
          "values": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ValidationErrorDto"
            },
            "description": "A list of items.",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        }
      },
      "OverallReportDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the report. Max length = 250. Optional.",
            "nullable": true
          },
          "url": {
            "type": "string",
            "description": "The URL of the report that can be viewed on the partners web application. Max length = 2048. Required.",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        },
        "description": "Assessment order overall report payload."
      },
      "PatchAssessmentDto": {
        "type": "object",
        "properties": {
          "assessmentId": {
            "type": "string",
            "description": "ID of the assessment. Required.",
            "nullable": true
          },
          "assessmentStatus": {
            "$ref": "#/components/schemas/AssessmentStatusDto"
          },
          "assessmentResults": {
            "$ref": "#/components/schemas/AssessmentResultsDto"
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        }
      },
      "PatchOrderRequest": {
        "type": "object",
        "properties": {
          "partnerTrackingId": {
            "type": "string",
            "description": "Partner tracking id used for troubleshooting. Optional.",
            "nullable": true
          },
          "overallScore": {
            "type": "string",
            "description": "An indication of whether the assessee met all necessary predetermined ranges set for the job.\r\nMax length = 30. Optional.",
            "nullable": true
          },
          "overallScoreDescription": {
            "type": "string",
            "description": "Description of the overall score.\r\nMax length = 250. Optional.",
            "nullable": true
          },
          "overallReports": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OverallReportDto"
            },
            "description": "Reports of the assessment order. Optional.",
            "nullable": true
          },
          "assessments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PatchAssessmentDto"
            },
            "description": "Collection of assessment results. Required.",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        },
        "description": "Assessment order patch payload."
      },
      "ReportDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the report. Max length = 250. Optional.",
            "nullable": true
          },
          "url": {
            "type": "string",
            "description": "The URL of the report that can be viewed on the partners web application. Max length = 2048. Required.",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        },
        "description": "Report payload."
      },
      "ScoreDto": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "description": "The value of the score. Max length = 50. Optional.",
            "nullable": true
          },
          "description": {
            "type": "string",
            "description": "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. Max length = 250. Optional.",
            "nullable": true
          },
          "attempt": {
            "type": "integer",
            "description": "The attempt of the test. Required.",
            "format": "int32"
          },
          "reports": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReportDto"
            },
            "description": "Score reports. Optional.",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        },
        "description": "Score payload."
      },
      "TestDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Assessment order test id. Max length = 150. Required.",
            "nullable": true
          },
          "score": {
            "$ref": "#/components/schemas/ScoreDto"
          },
          "testStatus": {
            "$ref": "#/components/schemas/TestStatusDto"
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        },
        "description": "Assessment order test payload."
      },
      "TestStatusDto": {
        "type": "object",
        "properties": {
          "updatedAt": {
            "type": "string",
            "description": "The date and time when the assessment test was updated. Required.",
            "format": "date-time"
          },
          "value": {
            "enum": [
              "Ordered",
              "Pending",
              "InProgress",
              "Hold",
              "Complete",
              "RetestRecommended",
              "Expired"
            ],
            "type": "string",
            "description": "The new status of the assessment test. Required.",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        },
        "description": "Assessment order test status payload."
      },
      "ValidationErrorDto": {
        "type": "object",
        "properties": {
          "fields": {
            "type": "string",
            "description": "Gets or sets a string detailing the fields involved in the validation error.",
            "nullable": true
          },
          "code": {
            "type": "string",
            "nullable": true
          },
          "message": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {
          "type": "object",
          "nullable": true
        }
      }
    }
  }
}
```