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

# Get candidate

> Returns a single candidate if it belongs to the authenticated company.



## OpenAPI

````yaml api-reference/openapi.yaml get /api/v1/candidates/{id}
openapi: 3.1.0
info:
  title: Outhire Public API
  version: 0.1.0
  description: >
    OpenAPI description of the currently implemented public API under `/api/v1`.


    Authentication uses bearer API keys generated from the Outhire app settings
    UI.

    All resource access is scoped to the company that owns the API key.


    Notes about current implementation:

    - Cursor pagination is offset-based and the cursor is an opaque
    base64url-encoded object.

    - Duplicate candidate detection is implemented at the application layer and
    is not concurrency-safe yet.
servers:
  - url: https://app.outhire.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Jobs
  - name: Candidates
paths:
  /api/v1/candidates/{id}:
    get:
      tags:
        - Candidates
      summary: Get candidate
      description: Returns a single candidate if it belongs to the authenticated company.
      parameters:
        - name: id
          in: path
          required: true
          description: Numeric candidate id.
          schema:
            type: integer
      responses:
        '200':
          description: Candidate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CandidateResponse:
      description: Wrapper for a single candidate resource.
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/Candidate'
    Candidate:
      description: Public representation of a candidate.
      type: object
      required:
        - id
        - public_id
        - name
        - email
        - phone
        - linkedin
        - location
        - stage
        - rating
        - fit_score
        - application_source
        - ats_candidate_id
        - job
        - created_at
        - updated_at
      properties:
        id:
          type: integer
          description: Internal numeric candidate id.
          example: 419
        public_id:
          type: string
          description: Public UUID-like candidate identifier.
          example: e3745169-a137-4b99-8fcc-373d6d4c8d60
        name:
          type:
            - string
            - 'null'
          description: Candidate name.
          example: Jane Doe
        email:
          type:
            - string
            - 'null'
          format: email
          description: Candidate email.
          example: jane@example.com
        phone:
          type:
            - string
            - 'null'
          description: Candidate phone number after normalization where possible.
          example: '+61412345678'
        linkedin:
          type:
            - string
            - 'null'
          format: uri
          description: LinkedIn profile URL.
          example: https://linkedin.com/in/janedoe
        location:
          type:
            - string
            - 'null'
          description: Candidate location string.
          example: Sydney, Australia
        stage:
          type:
            - string
            - 'null'
          description: Current candidate stage.
          example: applied
        rating:
          type:
            - integer
            - 'null'
          minimum: 1
          maximum: 5
          description: Candidate rating if set.
          example: 4
        fit_score:
          type:
            - number
            - 'null'
          description: Candidate fit score if present.
          example: 82
        application_source:
          $ref: '#/components/schemas/ApplicationSource'
        ats_candidate_id:
          type:
            - string
            - 'null'
          description: Optional external ATS identifier.
          example: ext-456
        job:
          description: The job associated with the candidate.
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/JobSummary'
        created_at:
          type: string
          format: date-time
          description: Candidate creation timestamp.
          example: '2026-03-11T10:21:54.289003Z'
        updated_at:
          type: string
          format: date-time
          description: Candidate last update timestamp.
          example: '2026-03-11T10:21:54.544000Z'
        applied_at:
          type: string
          format: date-time
          description: >-
            Present on detailed candidate responses. Mirrors the candidate
            creation timestamp.
          example: '2026-03-11T10:21:54.289003Z'
        resume_url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            Present on detailed candidate responses when a resume file exists.
            Signed URL expires.
          example: >-
            https://api.outhire.ai/storage/cv/example.pdf?token=eyJhbGciOiJIUzI1NiIs...
        resume_data:
          description: >-
            Present on detailed candidate responses after async resume
            extraction completes.
          oneOf:
            - type: 'null'
            - type: object
              additionalProperties: true
        resume_status:
          type:
            - string
            - 'null'
          description: >-
            Present on detailed candidate responses when resume processing is
            relevant.
          example: processed
      example:
        id: 419
        public_id: e3745169-a137-4b99-8fcc-373d6d4c8d60
        name: Jane Doe
        email: jane@example.com
        phone: '+61412345678'
        linkedin: https://linkedin.com/in/janedoe
        location: Sydney, Australia
        stage: applied
        rating: 4
        fit_score: 82
        application_source: public_api
        ats_candidate_id: ext-456
        job:
          id: 40
          title: Senior Engineer
        created_at: '2026-03-11T10:21:54.289003Z'
        updated_at: '2026-03-11T10:21:54.544000Z'
        applied_at: '2026-03-11T10:21:54.289003Z'
        resume_url: >-
          https://api.outhire.ai/storage/cv/example.pdf?token=eyJhbGciOiJIUzI1NiIs...
        resume_data:
          personalInfo:
            name: Jane Doe
            email: jane@example.com
          summary: Senior engineer with 8 years of experience
        resume_status: processed
    ErrorResponse:
      description: Top-level API error response.
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      example:
        error:
          code: validation_error
          message: Request validation failed.
          details:
            - field: email
              message: Invalid email
    ApplicationSource:
      description: Candidate application source value set by this API.
      type: string
      enum:
        - public_api
    JobSummary:
      description: Minimal job object embedded in candidate responses.
      type: object
      required:
        - id
        - title
      properties:
        id:
          type:
            - integer
            - 'null'
          description: Internal numeric job id.
          example: 40
        title:
          type:
            - string
            - 'null'
          description: Job title.
          example: Senior Engineer
    ErrorBody:
      description: Standard error envelope payload.
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Stable machine-readable error code.
          enum:
            - validation_error
            - bad_request
            - unauthorized
            - not_found
            - conflict
            - unprocessable_entity
            - internal_error
        message:
          type: string
          description: Human-readable description of the error.
          example: Request validation failed.
        details:
          type: array
          description: Optional field-level validation details.
          items:
            $ref: '#/components/schemas/ErrorDetail'
    ErrorDetail:
      description: Validation detail for a specific request field.
      type: object
      required:
        - field
        - message
      properties:
        field:
          type: string
          description: Request field path that failed validation.
          example: email
        message:
          type: string
          description: Human-readable validation message.
          example: Invalid email
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: unauthorized
              message: Missing or invalid API key.
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

````