> ## 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. # Get candidate by ID > Retrieve detailed information about a single candidate including their full pipeline stage history (all stages they have been through with dates). **When to use**: Use this when you need the stage history timeline for one specific candidate. For querying multiple candidates with filtering, use `POST /v1/persons/search` with `job_id` and `include: ["candidates"]` instead. ## OpenAPI ````yaml /api-reference/openapi-v1.json get /v1/candidates/{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/candidates/{id}: get: tags: - Candidates summary: Get candidate by ID description: >- Retrieve detailed information about a single candidate including their full pipeline stage history (all stages they have been through with dates). **When to use**: Use this when you need the stage history timeline for one specific candidate. For querying multiple candidates with filtering, use `POST /v1/persons/search` with `job_id` and `include: ["candidates"]` instead. operationId: getCandidateById parameters: - in: path name: id required: true schema: type: string description: Candidate ID responses: '200': description: Candidate fetched content: application/json: schema: $ref: '#/components/schemas/CandidateByIdResponse' example: success: true data: id: 234e5678-e90a-12b3-c456-789012345678 person_id: 345e6789-e01b-23c4-d567-890123456789 job_id: 123e4567-e89b-12d3-a456-426614174000 name: Jane Smith current_job_title: Software Engineer current_company_name: Tech Corp current_company_id: 456e7890-e12b-34d5-a678-901234567890 current_pipeline_stage_name: Technical Interview current_pipeline_stage_id: 567e8901-e23c-45d6-e789-012345678901 current_pipeline_stage_date: '2024-01-15T10:00:00Z' created_at: '2024-01-12T14:30:00Z' pipeline_stage_history: - stage_id: 345e6789-e01b-23c4-d567-890123456789 stage_name: Application Review stage_date: '2024-01-12T14:30:00Z' - stage_id: 567e8901-e23c-45d6-e789-012345678901 stage_name: Technical Interview stage_date: '2024-01-15T10: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: CandidateByIdResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/CandidateById' required: - success - data CandidateById: type: object properties: id: type: string description: Candidate UUID. person_id: type: string description: >- Associated person UUID. Use in GET /v1/persons/{id} for full profile. job_id: type: string description: >- Associated job UUID. Use in GET /v1/jobs/{id} for job details and pipeline stages. name: type: - string - 'null' description: Candidate full name. current_job_title: type: - string - 'null' description: Current job title from their person profile. current_company_name: type: - string - 'null' description: Current employer name. current_company_id: type: - string - 'null' description: Current employer company UUID. current_pipeline_stage_name: type: - string - 'null' description: Name of the current pipeline stage. current_pipeline_stage_id: type: - string - 'null' description: >- UUID of the current pipeline stage. Stage IDs from GET /v1/jobs/{id} → pipeline_stages. current_pipeline_stage_date: type: - string - 'null' description: ISO 8601 timestamp when the candidate entered the current stage. created_at: type: string description: >- ISO 8601 timestamp when the person was added as a candidate to this job. pipeline_stage_history: type: array items: $ref: '#/components/schemas/PipelineStageHistoryItem' description: >- Complete history of all pipeline stages this candidate has been through, ordered chronologically. required: - id - person_id - job_id - name - current_job_title - current_company_name - current_company_id - current_pipeline_stage_name - current_pipeline_stage_id - current_pipeline_stage_date - created_at - pipeline_stage_history PipelineStageHistoryItem: type: object properties: stage_id: type: string description: Pipeline stage UUID. stage_name: type: string description: Stage display name. stage_date: type: string description: ISO 8601 timestamp when the candidate entered this stage. required: - stage_id - stage_name - stage_date securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````