> ## 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. # Update scorecard > Update an existing scorecard. Only provided fields are modified. **Criterion ratings**: when `criterion_ratings` is provided, all existing criterion ratings on this scorecard are replaced. Pass an empty array to clear them. **Team member assignment**: `last_updated_by` defaults to the calling team member. Pass `team_member_id` to override. ## OpenAPI ````yaml /api-reference/openapi-v1.json patch /v1/scorecards/{id} 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/{id}: patch: tags: - Scorecards summary: Update scorecard description: >- Update an existing scorecard. Only provided fields are modified. **Criterion ratings**: when `criterion_ratings` is provided, all existing criterion ratings on this scorecard are replaced. Pass an empty array to clear them. **Team member assignment**: `last_updated_by` defaults to the calling team member. Pass `team_member_id` to override. operationId: updateScorecard parameters: - in: path name: id required: true schema: type: string description: Scorecard ID requestBody: content: application/json: schema: $ref: '#/components/schemas/ScorecardUpdateRequest' responses: '200': description: Scorecard updated content: application/json: schema: $ref: '#/components/schemas/ScorecardUpdateResponse' 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' '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: ScorecardUpdateRequest: type: object properties: job_id: type: - string - 'null' format: uuid description: >- Job UUID to scope this scorecard to. Pass null to clear. When changed, candidate_id is auto-resolved from the new (person_id, job_id) pair. overall_rating: type: - number - 'null' minimum: 0 maximum: 10 description: Overall score (0 to template rating_scale). Pass null to clear. overall_comment: type: - string - 'null' description: Plain-text overall summary note. Pass null to clear. is_starred: type: boolean description: Toggle the starred flag. visible_in_client_share_link: type: boolean description: >- Toggle client share link visibility. Only effective when a job_id is set on the scorecard. team_member_id: type: string format: uuid description: >- Team member UUID to record as last_updated_by. Defaults to the caller. criterion_ratings: type: array items: type: object properties: criterion_id: type: string format: uuid description: >- Criterion UUID from the template (assessment_template_criteria.id). rating: type: - number - 'null' minimum: 0 maximum: 10 description: >- Numeric score from 0 to the template rating_scale (max 10). At least one of rating or comment must be set. comment: type: - string - 'null' description: >- Plain-text comment for this criterion. Pass null or omit to leave only a numeric rating. required: - criterion_id description: >- When provided, REPLACES all criterion ratings on this scorecard. Pass an empty array to clear all criterion ratings. ScorecardUpdateResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/Scorecard' required: - success - data 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. ````