> ## 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. # Search candidates across jobs > List candidates (people on a job pipeline) across every job in the workspace, one row per candidate and job, with their current stage, stage dates, person and job. **Filters**: `job_ids_included`, current stage (`pipeline_stage_ids_included` / `_excluded`), stage category (`stage_categories_included` / `_excluded`: interviewing, offer, placement, rejection), `owner_ids`, `sourced_by_ids`, `exclude_archived_jobs`, and date ranges on when the candidate was added (`created_at_*`), when they entered their current stage (`stage_date_*`) and the current stage's Stage Date (`custom_stage_date_*`). **Stage Date** is the date and time set on a stage by a person or the calendar; on interview stages it is usually the interview time. For upcoming interviews, pass `stage_categories_included: ["interviewing"]`, `custom_stage_date_gte` set to the start of today with its timezone offset, `sort_by: "custom_stage_date"` and `sort_order: "asc"`. **Sorting**: `sort_by` is `created_at` (default), `stage_date` or `custom_stage_date`; `sort_order` is `desc` (default) or `asc`. **Pagination**: `offset` and `limit` (max 100). A very broad search on a large workspace can return `504 SEARCH_TIMEOUT`; add filters and retry. There is no name or keyword filter. To find a person by name, use `POST /v1/persons/search`; for one person's Stage Date, call `GET /v1/candidates/{id}` with the `candidate_id` it returns. For person-level filters (tags, custom fields, location, keywords), use `POST /v1/persons/search` with `include: ["candidates"]`. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/candidates/search 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. - name: Campaigns description: >- Create and edit email campaigns, enroll people through enrollment batches, and manage who is enrolled. paths: /v1/candidates/search: post: tags: - Candidates summary: Search candidates across jobs description: >- List candidates (people on a job pipeline) across every job in the workspace, one row per candidate and job, with their current stage, stage dates, person and job. **Filters**: `job_ids_included`, current stage (`pipeline_stage_ids_included` / `_excluded`), stage category (`stage_categories_included` / `_excluded`: interviewing, offer, placement, rejection), `owner_ids`, `sourced_by_ids`, `exclude_archived_jobs`, and date ranges on when the candidate was added (`created_at_*`), when they entered their current stage (`stage_date_*`) and the current stage's Stage Date (`custom_stage_date_*`). **Stage Date** is the date and time set on a stage by a person or the calendar; on interview stages it is usually the interview time. For upcoming interviews, pass `stage_categories_included: ["interviewing"]`, `custom_stage_date_gte` set to the start of today with its timezone offset, `sort_by: "custom_stage_date"` and `sort_order: "asc"`. **Sorting**: `sort_by` is `created_at` (default), `stage_date` or `custom_stage_date`; `sort_order` is `desc` (default) or `asc`. **Pagination**: `offset` and `limit` (max 100). A very broad search on a large workspace can return `504 SEARCH_TIMEOUT`; add filters and retry. There is no name or keyword filter. To find a person by name, use `POST /v1/persons/search`; for one person's Stage Date, call `GET /v1/candidates/{id}` with the `candidate_id` it returns. For person-level filters (tags, custom fields, location, keywords), use `POST /v1/persons/search` with `include: ["candidates"]`. operationId: searchCandidates requestBody: content: application/json: schema: $ref: '#/components/schemas/CandidatesSearchBody' responses: '200': description: Candidates found content: application/json: schema: $ref: '#/components/schemas/CandidatesSearchResponse' 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_id: 456e7890-e12b-34d5-a678-901234567890 current_company_name: Tech Corp job_title: Senior Backend Engineer job_company_id: 789e0123-a45b-67c8-d901-234567890123 job_company_name: Acme Inc current_pipeline_stage_id: 567e8901-e23c-45d6-e789-012345678901 current_pipeline_stage_name: Technical Interview current_pipeline_stage_date: '2024-01-15T10:00:00Z' current_custom_stage_date: '2024-01-18T15:00:00Z' created_at: '2024-01-12T14:30:00Z' sourced_by: 678e9012-e34d-56f7-a890-123456789012 owner_id: 678e9012-e34d-56f7-a890-123456789012 meta: total: 1 offset: 0 limit: 100 '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. details: type: object additionalProperties: {} description: >- Extra facts about the error when they help you fix it, such as a limit and when it resets. 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. details: type: object additionalProperties: {} description: >- Extra facts about the error when they help you fix it, such as a limit and when it resets. 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. details: type: object additionalProperties: {} description: >- Extra facts about the error when they help you fix it, such as a limit and when it resets. required: - code - message required: - success - error components: schemas: CandidatesSearchBody: type: object properties: offset: type: - integer - 'null' minimum: 0 default: 0 description: Records to skip for pagination. Defaults to 0. limit: type: integer minimum: 1 maximum: 100 default: 100 description: Max records per page (1–100). Defaults to 100. job_ids_included: type: array items: type: string format: uuid maxItems: 100 description: >- Only candidates on these jobs (up to 100). Get IDs from POST /v1/jobs/search. pipeline_stage_ids_included: type: array items: type: string format: uuid maxItems: 100 description: >- Only candidates whose current stage is one of these pipeline stages (up to 100). Get IDs from GET /v1/jobs/pipeline-stages. pipeline_stage_ids_excluded: type: array items: type: string format: uuid maxItems: 100 description: >- Leave out candidates whose current stage is one of these pipeline stages (up to 100). stage_categories_included: type: array items: type: string enum: - interviewing - offer - placement - rejection description: >- Only candidates whose current stage is in any of these categories: interviewing, offer, placement, rejection. Categories are set per stage in pipeline settings. stage_categories_excluded: type: array items: type: string enum: - interviewing - offer - placement - rejection description: >- Leave out candidates whose current stage is in any of these categories. owner_ids: type: array items: type: string format: uuid maxItems: 100 description: >- Only candidates owned by these team members (up to 100). Get IDs from GET /v1/team-members. sourced_by_ids: type: array items: type: string format: uuid maxItems: 100 description: >- Only candidates sourced by these team members (up to 100). Get IDs from GET /v1/team-members. exclude_archived_jobs: type: boolean default: false description: Leave out candidates on archived jobs. Defaults to false. created_at_gte: anyOf: - type: string format: date-time - type: string format: date description: >- Only candidates added to their job at or after this ISO 8601 date or timestamp. A date without a time means midnight UTC at the start of that day, so a date-only upper bound leaves that day out. For a day in a local timezone pass full timestamps with the offset, such as 2026-11-05T00:00:00-05:00 to 2026-11-05T23:59:59-05:00. created_at_lte: anyOf: - type: string format: date-time - type: string format: date description: >- Only candidates added to their job at or before this ISO 8601 date or timestamp. A date without a time means midnight UTC at the start of that day, so a date-only upper bound leaves that day out. For a day in a local timezone pass full timestamps with the offset, such as 2026-11-05T00:00:00-05:00 to 2026-11-05T23:59:59-05:00. stage_date_gte: anyOf: - type: string format: date-time - type: string format: date description: >- Only candidates who entered their current stage at or after this ISO 8601 date or timestamp. Only candidates whose current stage has this date are returned. A date without a time means midnight UTC at the start of that day, so a date-only upper bound leaves that day out. For a day in a local timezone pass full timestamps with the offset, such as 2026-11-05T00:00:00-05:00 to 2026-11-05T23:59:59-05:00. stage_date_lte: anyOf: - type: string format: date-time - type: string format: date description: >- Only candidates who entered their current stage at or before this ISO 8601 date or timestamp. Only candidates whose current stage has this date are returned. A date without a time means midnight UTC at the start of that day, so a date-only upper bound leaves that day out. For a day in a local timezone pass full timestamps with the offset, such as 2026-11-05T00:00:00-05:00 to 2026-11-05T23:59:59-05:00. custom_stage_date_gte: anyOf: - type: string format: date-time - type: string format: date description: >- Only candidates whose current stage has a Stage Date (on interview stages, usually the interview time) at or after this ISO 8601 date or timestamp. Only candidates whose current stage has this date are returned. A date without a time means midnight UTC at the start of that day, so a date-only upper bound leaves that day out. For a day in a local timezone pass full timestamps with the offset, such as 2026-11-05T00:00:00-05:00 to 2026-11-05T23:59:59-05:00. custom_stage_date_lte: anyOf: - type: string format: date-time - type: string format: date description: >- Only candidates whose current stage has a Stage Date at or before this ISO 8601 date or timestamp. Only candidates whose current stage has this date are returned. A date without a time means midnight UTC at the start of that day, so a date-only upper bound leaves that day out. For a day in a local timezone pass full timestamps with the offset, such as 2026-11-05T00:00:00-05:00 to 2026-11-05T23:59:59-05:00. sort_by: type: string enum: - created_at - stage_date - custom_stage_date default: created_at description: >- created_at (default): when the candidate was added to the job. stage_date: when they entered their current stage. custom_stage_date: the Stage Date of their current stage, leaving out candidates without one. Sorting by stage_date leaves out the few candidates with no recorded stage history; with no stage date filter, meta.total still counts them. sort_order: type: string enum: - asc - desc default: desc description: Sort direction. Defaults to desc. CandidatesSearchResponse: type: object properties: success: type: boolean enum: - true data: type: array items: $ref: '#/components/schemas/CandidateSearchResult' 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 CandidateSearchResult: type: object properties: id: type: string format: uuid description: Candidate UUID. person_id: type: string format: uuid description: Person UUID. Use in GET /v1/persons/{id} for the full profile. job_id: type: string format: uuid description: Job UUID. Use in GET /v1/jobs/{id} for job details. name: type: - string - 'null' description: Candidate full name. current_job_title: type: - string - 'null' description: Current job title from their person profile. current_company_id: type: - string - 'null' format: uuid description: Current employer company UUID. current_company_name: type: - string - 'null' description: Current employer name. job_title: type: - string - 'null' description: Job title. job_company_id: type: - string - 'null' format: uuid description: UUID of the company the job is for. job_company_name: type: - string - 'null' description: Name of the company the job is for. current_pipeline_stage_id: type: - string - 'null' format: uuid description: >- UUID of the current pipeline stage. Matches IDs from GET /v1/jobs/pipeline-stages. current_pipeline_stage_name: type: - string - 'null' description: Name of the current pipeline stage. current_pipeline_stage_date: type: - string - 'null' description: >- ISO 8601 timestamp when the candidate entered the current stage. Null when no stage history is recorded. current_custom_stage_date: type: - string - 'null' description: >- Stage Date of the current stage: the date and time set by a person or the calendar, shown as Stage Date in the app. On interview stages this is usually the interview time. Null when none was set. created_at: type: string description: ISO 8601 timestamp when the person was added to the job. sourced_by: type: - string - 'null' format: uuid description: >- UUID of the team member who sourced this candidate. Matches IDs from GET /v1/team-members. owner_id: type: - string - 'null' format: uuid description: >- UUID of the team member who owns this candidate. Matches IDs from GET /v1/team-members. required: - id - person_id - job_id - name - current_job_title - current_company_id - current_company_name - job_title - job_company_id - job_company_name - current_pipeline_stage_id - current_pipeline_stage_name - current_pipeline_stage_date - current_custom_stage_date - created_at - sourced_by - owner_id securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.