> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search scorecards

> Search and filter scorecards (candidate evaluations) with pagination and sorting.

**Filters**: `person_id`, `job_id`, `candidate_id`, `template_id`, `created_by_ids`, `is_starred`.

**Sorting**: `sort_by` — `created_at` (default), `updated_at`, or `overall_rating`. `sort_order` — `asc` or `desc` (default).

**Pagination**: `offset` and `limit` (max 100).



## OpenAPI

````yaml /api-reference/openapi-v1.json post /v1/scorecards/search
openapi: 3.1.0
info:
  title: Stardex API (v1)
  version: 1.0.0
  description: >-
    Stardex ATS API — manage candidates, jobs, companies, and recruiting
    workflows.
servers:
  - url: https://api.stardex.ai
    description: Production API server
security:
  - bearerAuth: []
tags:
  - name: Persons
    description: Manage person records — contacts, work history, and custom fields.
  - name: Jobs
    description: Manage job postings — pipeline stages, team members, and custom fields.
  - name: Candidates
    description: Manage candidate records and pipeline stage transitions.
  - name: Companies
    description: Browse and retrieve company records.
  - name: Lists
    description: Create, search, and retrieve saved person and company lists.
  - name: Person Activities
    description: Create and manage activity records (notes, emails, meetings) for persons.
  - name: Team Members
    description: List team members for use in search filters and assignments.
  - name: Custom Fields
    description: Retrieve custom field definitions and tag options for search filters.
paths:
  /v1/scorecards/search:
    post:
      tags:
        - Scorecards
      summary: Search scorecards
      description: >-
        Search and filter scorecards (candidate evaluations) with pagination and
        sorting.


        **Filters**: `person_id`, `job_id`, `candidate_id`, `template_id`,
        `created_by_ids`, `is_starred`.


        **Sorting**: `sort_by` — `created_at` (default), `updated_at`, or
        `overall_rating`. `sort_order` — `asc` or `desc` (default).


        **Pagination**: `offset` and `limit` (max 100).
      operationId: searchScorecards
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScorecardsSearchBody'
      responses:
        '200':
          description: Scorecards found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScorecardsSearchResponse'
              example:
                success: true
                data:
                  - id: ddddeeee-1111-2222-3333-444444444444
                    person_id: 123e4567-e89b-12d3-a456-426614174000
                    job_id: 456e7890-e12b-34d5-a678-901234567890
                    candidate_id: eeeeffff-1111-2222-3333-444444444444
                    assessment_template_id: aaaa1111-2222-3333-4444-555555555555
                    template:
                      id: aaaa1111-2222-3333-4444-555555555555
                      name: Senior Backend Engineer Scorecard
                      rating_scale: 5
                    job:
                      id: 456e7890-e12b-34d5-a678-901234567890
                      title: Senior Backend Engineer
                      company_name: Acme Inc.
                    created_by:
                      id: 567e8901-e23c-45d6-e789-012345678901
                      first_name: Jane
                      last_name: Smith
                    overall_rating: 4.5
                    overall_comment: >-
                      Strong systems-design depth and excellent async
                      collaboration. Recommend moving forward.
                    is_starred: true
                    visible_in_client_share_link: false
                    criterion_ratings:
                      - id: cc11aa22-3333-4444-5555-666666666666
                        criterion_id: bbbb1111-2222-3333-4444-555555555555
                        criterion_name: System design depth
                        importance: must_have
                        position: 1
                        rating: 5
                        comment: >-
                          Designed a multi-region payments service with clear
                          failure-mode reasoning.
                      - id: cc11aa22-3333-4444-5555-777777777777
                        criterion_id: cccc1111-2222-3333-4444-555555555555
                        criterion_name: Async collaboration
                        importance: nice_to_have
                        position: 2
                        rating: 4
                        comment: >-
                          Strong written communication; decision log was
                          thorough.
                    created_at: '2026-06-01T10:00:00Z'
                    updated_at: '2026-06-01T10:00:00Z'
                meta:
                  total: 1
                  offset: 0
                  limit: 100
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                    description: Always false for error responses.
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Machine-readable error code (e.g. "VALIDATION_ERROR",
                          "NOT_FOUND").
                      message:
                        type: string
                        description: Human-readable error description.
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                    description: Always false for error responses.
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Machine-readable error code (e.g. "VALIDATION_ERROR",
                          "NOT_FOUND").
                      message:
                        type: string
                        description: Human-readable error description.
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                    description: Always false for error responses.
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Machine-readable error code (e.g. "VALIDATION_ERROR",
                          "NOT_FOUND").
                      message:
                        type: string
                        description: Human-readable error description.
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
components:
  schemas:
    ScorecardsSearchBody:
      type: object
      properties:
        offset:
          type:
            - integer
            - 'null'
          minimum: 0
          default: 0
          description: Records to skip for pagination. Defaults to 0.
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
          description: Max records per page (1–100). Defaults to 100.
        person_id:
          type: string
          format: uuid
          description: Return only scorecards for this person UUID.
        job_id:
          type: string
          format: uuid
          description: Return only scorecards scoped to this job UUID.
        candidate_id:
          type: string
          format: uuid
          description: Return only scorecards for this candidate UUID.
        template_id:
          type: string
          format: uuid
          description: Return only scorecards created from this template UUID.
        created_by_ids:
          type: array
          items:
            type: string
            format: uuid
          description: >-
            Filter by creator team member UUIDs. Get IDs from GET
            /v1/team-members.
        is_starred:
          type: boolean
          description: Filter by starred status.
        sort_by:
          type: string
          enum:
            - created_at
            - updated_at
            - overall_rating
          default: created_at
          description: >-
            Column to sort by. One of: created_at (default), updated_at,
            overall_rating.
        sort_order:
          type: string
          enum:
            - asc
            - desc
          default: desc
          description: Sort direction. Defaults to desc.
    ScorecardsSearchResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: array
          items:
            $ref: '#/components/schemas/Scorecard'
        meta:
          type: object
          properties:
            total:
              type: number
              description: Total matching records across all pages.
            offset:
              type: number
              description: Current pagination offset.
            limit:
              type: number
              description: Page size used for this request.
          required:
            - total
            - offset
            - limit
      required:
        - success
        - data
        - meta
    Scorecard:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Scorecard UUID.
        person_id:
          type: string
          format: uuid
          description: Person UUID being evaluated.
        job_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Job UUID this scorecard is scoped to, or null for a person-level
            scorecard.
        candidate_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Candidate UUID (person+job) — auto-resolved when job_id is set and
            the person is a candidate on that job.
        assessment_template_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Scorecard template UUID used to score.
        template:
          allOf:
            - $ref: '#/components/schemas/ScorecardTemplateRef'
            - type:
                - object
                - 'null'
              description: Embedded template summary.
        job:
          allOf:
            - $ref: '#/components/schemas/ScorecardJobRef'
            - type:
                - object
                - 'null'
              description: Embedded job summary (when job_id is set).
        created_by:
          allOf:
            - $ref: '#/components/schemas/ScorecardSubmissionCreator'
            - type:
                - object
                - 'null'
              description: Team member who created the scorecard.
        overall_rating:
          type:
            - number
            - 'null'
          description: >-
            Overall numeric score (0 to template rating_scale). Null when only
            criterion-level ratings or a note were left.
        overall_comment:
          type:
            - string
            - 'null'
          description: Plain-text overall summary note. Null when not provided.
        is_starred:
          type: boolean
          description: >-
            Whether this scorecard is starred (highlighted as the primary
            scorecard).
        visible_in_client_share_link:
          type: boolean
          description: >-
            Whether this scorecard is included on the client share link for the
            linked job.
        criterion_ratings:
          type: array
          items:
            $ref: '#/components/schemas/ScorecardCriterionRating'
          description: Per-criterion ratings and comments, sorted by criterion position.
        created_at:
          type: string
          description: ISO 8601 creation timestamp.
        updated_at:
          type: string
          description: ISO 8601 last-updated timestamp.
      required:
        - id
        - person_id
        - job_id
        - candidate_id
        - assessment_template_id
        - template
        - job
        - created_by
        - overall_rating
        - overall_comment
        - is_starred
        - visible_in_client_share_link
        - criterion_ratings
        - created_at
        - updated_at
    ScorecardTemplateRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Scorecard template UUID.
        name:
          type: string
          description: Template name.
        rating_scale:
          type: integer
          description: Template rating scale (3, 4, 5, or 10).
      required:
        - id
        - name
        - rating_scale
    ScorecardJobRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Job UUID.
        title:
          type: string
          description: Job title.
        company_name:
          type:
            - string
            - 'null'
          description: Company name attached to the job.
      required:
        - id
        - title
        - company_name
    ScorecardSubmissionCreator:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Team member UUID.
        first_name:
          type:
            - string
            - 'null'
          description: First name.
        last_name:
          type:
            - string
            - 'null'
          description: Last name.
      required:
        - id
        - first_name
        - last_name
    ScorecardCriterionRating:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Criterion rating UUID.
        criterion_id:
          type: string
          format: uuid
          description: Assessment template criterion UUID.
        criterion_name:
          type:
            - string
            - 'null'
          description: Display name of the criterion.
        importance:
          type:
            - string
            - 'null'
          enum:
            - must_have
            - nice_to_have
          description: Criterion importance weighting.
        position:
          type:
            - number
            - 'null'
          description: Display position of the criterion.
        rating:
          type:
            - number
            - 'null'
          description: >-
            Numeric score (0 to rating_scale). Null when only a comment was
            left.
        comment:
          type:
            - string
            - 'null'
          description: >-
            Plain-text comment for this criterion. Null when no comment was
            left.
      required:
        - id
        - criterion_id
        - criterion_name
        - importance
        - position
        - rating
        - comment
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Authenticate with a Bearer token: API key, OAuth token, or session
        token.

````