For AI agents: markdown of this page — /docs-content-en/performan/peer-reviews.md documentation index — /llms.txt

Peer-review cards

GET /v1/performan/review/peer-reviews

Returns the peer-review stage cards of a campaign where the key owner is the reviewer. The campaign ID parameter is required, and the listing is cursor-based.

Parameters

Parameter Type Required Default Description
campaignId (query) number yes — Campaign ID. The campaign list — GET /v1/performan/review/campaigns
limit (query) number no 50 Records per page, 200 at most
afterCursorId (query) number no — The next-page cursor. The value comes from meta.nextCursor.id of the previous response. The first request omits it
  1. The first request carries no afterCursorId — it returns the first page.
  2. Pass meta.nextCursor.id from the response as the afterCursorId parameter of the next request. Copy the cursor whole, never assemble it from record fields.
  3. A response whose meta.nextCursor is null marks the end of the listing. The method has no offset parameter and no total count.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/performan/review/peer-reviews?campaignId=1&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/performan/review/peer-reviews?campaignId=1&limit=20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/performan/review/peer-reviews?campaignId=1&limit=20', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const body = await res.json()

if (!body.success) {
  throw new Error(`${body.error.code}: ${body.error.message}`)
}

for (const card of body.data) {
  console.log(card.id, card.revieweeUserName, card.status)
}

console.log(body.meta.nextCursor)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/performan/review/peer-reviews?campaignId=1&limit=20', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const body = await res.json()

if (!body.success) {
  throw new Error(`${body.error.code}: ${body.error.message}`)
}

console.log(body.data, body.meta.nextCursor)

Response fields

Field Type Description
success boolean Always true on success
data array Array of peer-review cards
data[].id number Card ID
data[].campaignId number The card's campaign. The list — GET /v1/performan/review/campaigns
data[].campaignStageId number The campaign stage the card belongs to
data[].stageType string Stage type. For this method — peerReview
data[].revieweeUserId number The employee being reviewed. Employee card — GET /v1/users/:id
data[].revieweeUserName string Name of the employee being reviewed
data[].reviewerUserId number The reviewing employee. Employee card — GET /v1/users/:id
data[].reviewerUserName string Name of the reviewing employee
data[].managerUserId number The reviewee's manager. Employee card — GET /v1/users/:id
data[].managerUserName string Manager name
data[].status string Card state: new — not filled in, completed — finished, rejected — rejected, published — published
data[].rate number The final rate from the rating question. 0 — no rate set
data[].comment string Card comment
data[].answers array Answers to the stage questions. On an unfilled card the array is empty
data[].answers[].questionId number Question ID
data[].answers[].questionTitle string Question wording
data[].answers[].questionDescription string Question note
data[].answers[].questionType string Question type as a string: 1 — single choice, 2 — multiple choice, 3 — text answer
data[].answers[].questionTypeLabel string Question type name in the Bitrix24 account language
data[].answers[].isRating boolean Whether the answer forms the card's final rate
data[].answers[].answerText string Answer text. Empty for a choice question
data[].answers[].selectedOptions array The chosen options. Empty for a text question
data[].answers[].selectedOptions[].id number Option ID
data[].answers[].selectedOptions[].text string Option text
data[].answers[].selectedOptions[].value number Numeric option value; rate is computed from it
data[].ratingScale array The rating scale of the stage
data[].ratingScale[].value number Scale value
data[].ratingScale[].label string Value caption
meta.nextCursor object | null The next-page cursor. null — no more records
meta.nextCursor.id number The value for the afterCursorId parameter of the next request

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 9,
      "campaignId": 1,
      "campaignStageId": 4,
      "stageType": "peerReview",
      "revieweeUserId": 42,
      "revieweeUserName": "Mary Jones",
      "reviewerUserId": 7,
      "reviewerUserName": "John Smith",
      "managerUserId": 7,
      "managerUserName": "John Smith",
      "status": "new",
      "rate": 0,
      "comment": "",
      "answers": [],
      "ratingScale": [
        { "value": 1, "label": "Well below expectations" },
        { "value": 2, "label": "Below expectations" },
        { "value": 3, "label": "Meets expectations" },
        { "value": 4, "label": "Above expectations" },
        { "value": 5, "label": "Well above expectations" }
      ]
    }
  ],
  "meta": { "nextCursor": null }
}

Error response example

400 — a required parameter was not sent:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`campaignId` is required and must be a positive integer"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS campaignId was not sent, or the value of campaignId or afterCursorId is not a positive integer, or limit is outside the 1–200 range
401 MISSING_API_KEY The X-Api-Key header was not sent
401 TOKEN_MISSING The key has no portal tokens. An OAuth application key requires the Authorization: Bearer header
403 SCOPE_DENIED The key has no performan scope
404 ROUTE_NOT_FOUND The Performance Review section is not enabled for the portal. The answer is indistinguishable from the answer to any address that does not exist
404 ENTITY_NOT_FOUND The section is enabled, but the portal has no Performance Review module: Bitrix24 answers that the performan.review.* method was not found
403 BITRIX_ACCESS_DENIED Bitrix24 denied access. The permissions the key uses to reach the portal do not include performan
409 PERFORMAN_SCOPE_JUST_GRANTED A Cowork key was granted the performan scope by this very request. Repeat it and it goes through
422 BITRIX_ERROR Bitrix24 rejected the request. The cause is in error.message, the machine code from Bitrix24 in error.b24Code
429 RATE_LIMITED The request rate on the Bitrix24 side was exceeded
429 QUEUE_OVERFLOW, QUEUE_TIMEOUT The portal request queue is full or the request did not get through the queue in time. The Retry-After header suggests the delay
503 BITRIX_TIMEOUT Bitrix24 accepted the request but did not answer in time. A read is safe to retry
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable

The full list of common API errors — Errors.

Known specifics

Unknown query parameters are ignored. The method reads campaignId, limit and afterCursorId and drops everything else without an error: a request with a typo in a parameter name answers 200 with an unfiltered listing. For instance, revieweeUserId narrows the listing only on manager review cards — on the other lists it is dropped silently.

Only the peer cards you review. The method returns the cards where the key owner is recorded in reviewerUserId. Cards where colleagues review the key owner do not appear. An empty data array means the key owner has nobody to review in this campaign.

This stage has no write method in the API. The section provides a write method only for the manager stage — POST /v1/performan/review/manager/answers. Peer-review cards are read-only.

See also