> ## 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. # List job candidates > Retrieve a paginated list of ALL candidates in a specific job — no filtering. **When to use**: Only when you need every candidate regardless of stage, tags, or other criteria. **For filtered queries** (by pipeline stage, custom attributes/tags, name, location, etc.), use `POST /v1/persons/search` with `job_id` and `include: ["candidates"]` instead — it supports all person search filters and can return candidate-level fields in a single call. ## OpenAPI ````yaml /api-reference/openapi-v1.json get /v1/jobs/{id}/candidates 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/jobs/{id}/candidates: get: tags: - Jobs summary: List job candidates description: >- Retrieve a paginated list of ALL candidates in a specific job — no filtering. **When to use**: Only when you need every candidate regardless of stage, tags, or other criteria. **For filtered queries** (by pipeline stage, custom attributes/tags, name, location, etc.), use `POST /v1/persons/search` with `job_id` and `include: ["candidates"]` instead — it supports all person search filters and can return candidate-level fields in a single call. operationId: listJobCandidates parameters: - in: path name: id required: true schema: type: string description: Job ID - schema: type: - integer - 'null' minimum: 0 default: 0 description: Records to skip for pagination. Defaults to 0. required: false name: offset in: query - schema: type: integer minimum: 1 maximum: 100 default: 100 description: Max records per page (1–100). Defaults to 100. required: false name: limit in: query responses: '200': description: Candidates fetched content: application/json: schema: $ref: '#/components/schemas/JobCandidatesResponse' example: success: true data: - id: 234e5678-e90a-12b3-c456-789012345678 person_id: 345e6789-e01b-23c4-d567-890123456789 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 created_at: '2024-01-12T14:30:00Z' meta: total: 12 offset: 0 limit: 20 '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: JobCandidatesResponse: type: object properties: success: type: boolean enum: - true data: type: array items: $ref: '#/components/schemas/JobCandidate' 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 JobCandidate: type: object properties: id: type: string description: >- Candidate UUID. Use in GET /v1/candidates/{id} for full stage history. person_id: type: string description: >- Associated person UUID. Use in GET /v1/persons/{id} for full profile. 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 in this job. current_pipeline_stage_id: type: - string - 'null' description: UUID of the current pipeline stage. created_at: type: string description: ISO 8601 timestamp when candidate was added to this job. required: - id - person_id - name - current_job_title - current_company_name - current_company_id - current_pipeline_stage_name - current_pipeline_stage_id - created_at securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````