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

# Get a candidate

> Returns one candidate by Evalezy id.

**Scope:** `evaluation:read`



## OpenAPI

````yaml /api-reference/openapi.json get /candidates/{candidateId}
openapi: 3.0.1
info:
  title: Evalezy AI Evaluation API
  version: v1
  description: >-
    Create exams, register candidates, submit scanned answer copies or typed
    answers, and read question-wise AI marks with feedback. Results are drafts
    until you finalize them.


    Server-to-server only: never ship an API key inside a browser or mobile app.
    English answers only for now (Hindi and regional languages are on the
    roadmap).
  contact:
    name: Evalezy
    email: hello@evalezy.com
    url: https://evalezy.com
servers:
  - url: https://api.evalezy.com/v1
    description: Production
security:
  - ApiKey: []
tags:
  - name: Exams
    description: Create, open, edit and look up exams.
  - name: Questions
    description: Add, edit and remove the questions of an exam.
  - name: Rubrics
    description: Marking criteria and model answers for long-answer questions.
  - name: Choice groups
    description: Internal choice ("attempt any N of M"). Beta, enabled on request.
  - name: Candidates
    description: >-
      Your students, keyed by your own external_id, and their exam
      registrations.
  - name: Uploads
    description: Presigned uploads for scanned answer copies (PDF).
  - name: Submissions
    description: Submit a copy or typed answers for a candidate and track its evaluation.
  - name: Results
    description: Question-wise marks, feedback and the checked (annotated) copy.
  - name: Review
    description: Teacher overrides, approval, finalize and unfinalize.
  - name: Credits
    description: Credit balance, rate card and price quotes.
  - name: Account
    description: Check which institute and scopes an API key has.
paths:
  /candidates/{candidateId}:
    get:
      tags:
        - Candidates
      summary: Get a candidate
      description: |-
        Returns one candidate by Evalezy id.

        **Scope:** `evaluation:read`
      operationId: getCandidate
      parameters:
        - name: candidateId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Evalezy candidate id (UUID), not your external_id.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Candidate'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
components:
  schemas:
    Candidate:
      type: object
      properties:
        id:
          type: string
          format: uuid
        external_id:
          type: string
        name:
          type: string
        roll_number:
          type: string
        section_or_class:
          type: string
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Error:
      type: object
      description: >-
        Every error uses this envelope. Branch on `error.code`; the message is
        for humans.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Stable machine code, e.g. `validation_failed`.
              example: validation_failed
            message:
              type: string
              description: Human-readable explanation.
              example: questions[1].max_marks must be a multiple of 0.5.
            request_id:
              type: string
              description: >-
                Quote this when you contact support (also sent as the
                X-Request-Id header).
            details:
              type: object
              description: >-
                Extra context. For `validation_failed`, `details.errors` lists
                every failing field.
              additionalProperties: true
  responses:
    Error401:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_api_key
              message: The API key is not valid.
              request_id: req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f
    Error403:
      description: >-
        The key lacks the required scope, or the API is not enabled for the
        institute.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: insufficient_scope
              message: This API key lacks the evaluation:write scope.
              request_id: req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f
              details:
                required_scope: evaluation:write
    Error404:
      description: Not found (ids of other institutes are also 404).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: The resource was not found.
              request_id: req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f
    Error429:
      description: Rate limit or daily quota reached. Retry after the Retry-After header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Too many requests. Retry after 2 s.
              request_id: req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your institute's API key, `vak_eval_` followed by 48 hex characters. An
        institute admin creates keys in the dashboard under Settings ->
        Integrations -> API keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.