API Reference
API Reference

/candidates/:id/ratings

Creates a rating for a candidate. Required scope: w_candidates. Accessible with all token types.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

A complete request would be:

{
  "member_id": "13e0eb0e",
  "comment": "Good, I guess",
  "scale": "thumbs",
  "grade": 1,
  "score_card": {
    "settings": {
      "questions_rateable": true
    },
    "sections": [
      {
        "id": 1,
        "name": "Critical Thinking",
        "traits": [
          {
            "id": 2,
            "name": "Analytical Skills",
            "score": "positive",
            "note": "Demonstrates strong reasoning and structure",
            "questions": [
              {
                "id": 3,
                "body": "Please give an example of how your analytical abilities helped you resolve a difficult situation.",
                "score": "positive"
              },
              {
                "id": 4,
                "body": "Tell me about a complex problem where you were able to find a simple and effective solution.",
                "score": "definite",
                "note": "Looks for clarity and simplification"
              }
            ]
          },
          {
            "id": 5,
            "name": "Decision making",
            "score": "definite",
            "note": "Evaluates judgment under uncertainty",
            "questions": [
              {
                "id": 6,
                "body": "Describe a time when you had to make a complex decision. How did you approach it?",
                "score": "definite"
              },
              {
                "id": 7,
                "body": "Describe a poor decision you made and what you did to correct the outcome.",
                "score": "positive",
                "note": "Assesses accountability and learning"
              }
            ]
          }
        ]
      },
      {
        "id": 8,
        "name": "Personal Effectiveness",
        "traits": [
          {
            "id": 9,
            "name": "Adaptable / Flexible",
            "score": "positive",
            "questions": [
              {
                "id": 10,
                "body": "What strategies have you used to adapt to unexpected changes in your work plans?",
                "score": "positive",
                "note": "Change management and resilience"
              }
            ]
          },
          {
            "id": 11,
            "name": "Tenacity",
            "score": "positive",
            "note": "Persistence in challenging situations",
            "questions": [
              {
                "id": 12,
                "body": "Tell me about a significant work-related setback you have faced and how you handled it.",
                "score": "definite"
              }
            ]
          },
          {
            "id": 13,
            "name": "Ambition",
            "score": "definite",
            "questions": [
              {
                "id": 14,
                "body": "What are your long-term career goals, and how does this role fit into them?",
                "score": "positive"
              },
              {
                "id": 15,
                "body": "Why do you believe you are a strong fit for this role?",
                "score": "definite",
                "note": "Evaluates motivation and role alignment"
              }
            ]
          }
        ]
      }
    ]
  }
}

Grade

Grades should fall within the following range, depending on the scale:

thumbs: 0 - 2. Interpreted as “negative” (0), “positive” (1) and “definite” (2) respectively

stars : 0 - 4. Interpreted as “one star” to “five stars” respectively

numbers : 0 - 9. Interpreted as “1 out of 10” to “10 out of 10” respectively


Scorecard IDs

Each section, trait, and question within a score_card is assigned to a random but unique identifier (integer). These IDs have no semantic meaning, and exist solely to uniquely identify individual elements for referencing, updates, and tracking across API interactions and internal systems.


Required fields

Each scorecard consists of sections, each section contains traits, and each trait may include questions. All levels must be present in the payload. If a trait has no questions, include "questions": [] to maintain a consistent and valid schema.

Path Params
string
required

The candidate's id

Body Params
string
required

The member adding the rating

string
required

A comment about the scoring of the candidate

string
enum
Defaults to thumbs

The rating scale that corresponds to the grade. One of thumbs (graphic rating), stars (star rating) or numbers (numeric rating)

Allowed:
int32
required

The candidate grade. View details in the Grade paragraph above

string

DEPRECATED One of negative, positive or definite. If the request payload includes score, the scale and grade fields are ignored

score_card
object
Responses

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json