Write a performance review

`overallScore` is not accepted — it is the mean of the criteria you send, to one decimal, so the number on the record can never disagree with the ratings under it. `status: "SHARED"` notifies the employee; `"DRAFT"` deliberately does not, which is the whole difference between the two. Only the employee’s manager or HR may review them.

Required scope

The access token must carry this scope. A token missing it gets 403 Forbidden. Grant them to an API client under Settings → Company → API, and to a teammate under Employee → Permissions.

hr:write

Request Body

Property	Type	Required	Description
`employeeId`	string	Required	Who is being reviewed.
`reviewDate`	string	Required	`YYYY-MM-DD`.
`summary`	string	Required	The write-up.
`strengths`	string	Optional
`improvements`	string	Optional
`status`	string	Required	SHARED notifies the employee; DRAFT does not.
`ratings`	array	Required	At least one `{ criterion, score }`, each score 1–5. Their mean becomes `overallScore`.

POSTExample request

curl

curl -X POST "https://www.pxb.app/api/public/v1/performance-reviews" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeId": "emp_44f1",
    "reviewDate": "2026-08-01",
    "summary": "Strong quarter on delivery.",
    "status": "SHARED",
    "ratings": [
      {
        "criterion": "Communication",
        "score": 4
      },
      {
        "criterion": "Delivery",
        "score": 5
      }
    ]
  }'

200Example response

json

{
  "message": "Review shared.",
  "content": {
    "reviewId": "rev_77cc",
    "shared": true
  }
}

403Example response

json

{
  "message": "Only this employee’s manager or HR can review them."
}

In the console

The same thing done by hand, for anyone comparing the API against the screen they already use.

Employees → Performance

/employee/performance

Open Performance.
Start a review for someone you manage.
Save or share it.