> ## Documentation Index > Fetch the complete documentation index at: https://docs.taptalent.io/llms.txt > Use this file to discover all available pages before exploring further. # List candidates in a pipeline stage > Retrieve all candidates in a specific pipeline stage with pagination, filtering by job ID, and date-range filtering. This endpoint returns complete candidate details from both the `candidate_details` and `job_candidate_details` tables. Notes: - The maximum number of candidates returned per request is 100. Unlike the per-job list endpoint, `perPage` here accepts any value from 1 to 100 (not a fixed set of page sizes). - The `startDate` and `endDate` filters apply to the candidate's creation date (the `createdAt` field in `job_candidate_details`). - You can only access candidates in stages that belong to pipelines in your company. - When `jobId` is provided, only candidates associated with that specific job are returned. - Custom fields are fetched from the normalized `customFieldValues` table and include field labels and parent sections. ## OpenAPI ````yaml /api-reference/openapi.yaml get /job-candidates/stage/{stageId}/candidates openapi: 3.1.0 info: title: TapTalent Partner API version: 1.0.0 summary: Partner API for jobs, candidates, pipelines, custom fields, and webhooks. description: > The TapTalent Partner API lets partner systems manage jobs, candidates, job-candidate relationships, hiring pipelines, and custom fields, and receive real-time event notifications via webhooks. All communication is JSON over HTTPS. ## Authentication Every request requires an API key sent as an HTTP bearer token: ``` Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv ``` Keys are prefixed `sk_live_` (production) or `sk_test_` (sandbox) followed by 22 base62 characters, are scoped to a company, and are generated from the TapTalent dashboard (Account Settings → Developers → API Key Management). Key management is dashboard-only and not available via this API. ## Response envelopes The API uses three envelope styles, by resource family: | Family | Success envelope | |---|---| | Jobs | Bare object (e.g. `{ "jobs": [...], "totalJobs": 45 }` or the job object itself) | | Candidates, Job Candidates, Pipelines, Custom Fields | `{ "status": "success", "data": ... }` | | Bulk resume upload and batch retrieval | `{ "success": true, "data": ... }` | Each operation in this specification models its family's actual envelope; no unified envelope is imposed. ## Pagination Pagination conventions vary by endpoint and are modeled as documented: | Endpoint | Page parameter | First page | Default page size | Page size rule | |---|---|---|---|---| | `GET /jobs` | `pageNumber` | 1 | 10 | one of 10, 20, 40, 80, 100 | | `GET /candidates/list` | `pageNumber` | **0** | 10 | one of 10, 20, 40, 80, 100 | | `GET /candidates/batch/{batchId}` | `pageNumber` | 1 | 10 | one of 10, 20, 40, 80, 100 | | `GET /job-candidates/job/{jobId}/candidates` | `page` | 1 | 20 | one of 10, 20, 40, 80, 100 | | `GET /job-candidates/stage/{stageId}/candidates` | `page` | 1 | 20 | any value from 1 to 100 | ## Errors Most errors use the canonical envelope: ```json { "error": { "code": "ERROR_CODE", "type": "error_type", "message": "Human-readable error message", "details": { "field": "Specific validation error message" } } } ``` Authentication failures use flat shapes instead (`{"message": ...}`, `{"code": ..., "message": ...}` or `{"message": ..., "isApiKeyExists": false}`); see the shared 401 response. Rate limits are applied at the company level; numeric limits and the 429 response body are not yet published. ## Webhooks Event notifications are delivered as HTTP POST requests to a single company-level HTTPS endpoint configured in the dashboard. Deliveries carry the headers `X-Webhook-Event`, `X-Webhook-Timestamp`, and `X-Webhook-Key` (verify by plain equality against the key generated in the dashboard; HMAC signatures are not yet available). Endpoints must respond with a 2xx status within 5 seconds; failed deliveries are retried at 200 ms, 400 ms, and 800 ms before being marked failed. See the `webhooks` section of this document for every event payload. ## Conventions used in this specification - `x-inferred: true` marks schemas or responses whose shape is inferred from related endpoints because the source documentation does not include an example; verify against the sandbox before relying on exact field names. - `x-known-quirk` marks fields whose wire format deviates from the API's prevailing conventions (for example an epoch timestamp where other endpoints return ISO 8601 strings). - Where the published documentation shows placeholder string identifiers (for example `"pipelineId_1"` or `"companyId_1"`), this specification models the underlying integer identifier types used by the API and notes the resolution on the affected field. contact: name: TapTalent Support email: support@taptalent.ai url: https://docs.taptalent.io license: name: Proprietary url: https://taptalent.ai servers: - url: https://partner-api.taptalent.io/v1/partner description: Production (use `sk_live_` keys) - url: https://sandbox.partner-api.taptalent.io/v1/partner description: Sandbox / staging (use `sk_test_` keys) security: - bearerAuth: [] tags: - name: Jobs description: Create, read, update, and list jobs. - name: Candidates description: >- Create and retrieve candidates, upload resumes in bulk, and fetch candidates by batch or id list. - name: Job Candidates description: >- Manage the relationship between candidates and jobs, including stage placement and per-job resume ingestion. - name: Pipelines description: Manage hiring pipelines and their stages. - name: Custom Fields description: Define custom field templates for candidates and jobs. - name: Custom Field Values description: Read and write custom field values attached to candidates and jobs. - name: Webhooks description: >- Event notifications delivered to your configured webhook endpoint. See the top-level `webhooks` section for payloads. paths: /job-candidates/stage/{stageId}/candidates: get: tags: - Job Candidates summary: List candidates in a pipeline stage description: | Retrieve all candidates in a specific pipeline stage with pagination, filtering by job ID, and date-range filtering. This endpoint returns complete candidate details from both the `candidate_details` and `job_candidate_details` tables. Notes: - The maximum number of candidates returned per request is 100. Unlike the per-job list endpoint, `perPage` here accepts any value from 1 to 100 (not a fixed set of page sizes). - The `startDate` and `endDate` filters apply to the candidate's creation date (the `createdAt` field in `job_candidate_details`). - You can only access candidates in stages that belong to pipelines in your company. - When `jobId` is provided, only candidates associated with that specific job are returned. - Custom fields are fetched from the normalized `customFieldValues` table and include field labels and parent sections. operationId: listCandidatesForStage parameters: - name: stageId in: path required: true description: The unique identifier of the pipeline stage. schema: type: integer example: 790 - name: jobId in: query required: false description: Filter candidates by job ID. schema: type: integer example: 12345 - name: startDate in: query required: false description: | Filter by date range start (ISO 8601 format, e.g. "2024-01-01T00:00:00Z"). Filters by candidate creation date. schema: type: string format: date-time example: '2024-01-01T00:00:00Z' - name: endDate in: query required: false description: | Filter by date range end (ISO 8601 format, e.g. "2024-12-31T23:59:59Z"). Filters by candidate creation date. schema: type: string format: date-time example: '2024-01-31T23:59:59Z' - name: page in: query required: false description: 'Page number (default: 1).' schema: type: integer default: 1 minimum: 1 - name: perPage in: query required: false description: | Items per page (1-100, default: 20). Maximum 100 allowed. Note this is a range, not the fixed 10/20/40/80/100 set used by the per-job candidates list. schema: type: integer minimum: 1 maximum: 100 default: 20 - name: orderColumn in: query required: false description: 'Column to sort by. Default: `createdAt`.' schema: type: string enum: - createdAt - firstName default: createdAt - name: orderBy in: query required: false description: 'Sort order. Default: `DESC`.' schema: type: string enum: - ASC - DESC default: DESC responses: '200': description: Candidates in the stage. content: application/json: schema: $ref: '#/components/schemas/ListCandidatesForStageResponse' examples: candidatesForStage: summary: One page of stage candidates value: status: success data: candidates: - jobCandidateId: 12345 jobId: 12345 stageId: 789 status: IN_PROGRESS profileMatchScore: 85 criteriaMatches: skills: 90 experience: 80 education: 75 recommendToRecruitingFirm: true aiSummary: Strong candidate with relevant experience... evaluationStatus: PENDING addedAt: '2024-01-15T10:00:00.000Z' updatedAt: '2024-01-15T10:00:00.000Z' candidate_details: id: 12345 firstName: John lastName: Doe email: john.doe@example.com phone: '+1234567890' resume: https://storage.example.com/resumes/john-doe.pdf currentJobTitle: Software Engineer currentCompany: Tech Corp city: San Francisco country: United States skills: - JavaScript - React - Node.js coverLetter: I am interested in... linkedin: https://linkedin.com/in/johndoe gender: Male dateOfBirth: '1995-05-15' nationality: American industry: Technology category: Engineering majors: - Computer Science summary: Experienced software engineer... languages: - English - Spanish educations: - degree: Bachelor's university: University of California graduation_year: '2019' githubUrl: https://github.com/johndoe certifications: - name: AWS Certified Solutions Architect provider: Amazon Web Services workExperiences: - title: Senior Software Engineer company: Tech Corp start_date: '2020-01-01' end_date: null responsibilities: - Led development of... - Managed team of 5 engineers projectExperiences: - title: E-commerce Platform technology_used: React, Node.js, PostgreSQL summary: - Built a full-stack e-commerce platform - Implemented payment gateway integration customFields: '13': label: Preferred Communication Channel value: Email parentSection: Personal Details '14': label: Availability Start Date value: '2024-02-01' parentSection: Personal Details pagination: page: 1 perPage: 20 totalCandidates: 150 totalPages: 8 '400': description: | Validation error. (The HTTP status code is not stated explicitly in the source documentation; it is inferred from the documented `validation_error` type.) content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: missingStageId: summary: Missing stage ID value: error: code: INVALID_REQUEST type: validation_error message: Stage ID is required invalidPerPage: summary: Invalid perPage value: error: code: INVALID_REQUEST type: validation_error message: perPage must be between 1 and 100 '401': $ref: '#/components/responses/Unauthorized' '403': description: | Not authorized to access this stage. (The HTTP status code is not stated explicitly in the source documentation; it is inferred from the documented `authorization_error` type.) content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: permissionDenied: summary: Unauthorized access value: error: code: PERMISSION_DENIED type: authorization_error message: You are not authorized to access this stage '404': description: | Stage not found, or job not found when the `jobId` filter is provided. (The HTTP status code is not stated explicitly in the source documentation; it is inferred from the documented `resource_error` type.) content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: stageNotFound: summary: Stage not found value: error: code: STAGE_NOT_FOUND type: resource_error message: Stage not found jobNotFound: summary: Job not found (jobId filter provided) value: error: code: JOB_NOT_FOUND type: resource_error message: Job not found '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' components: schemas: ListCandidatesForStageResponse: type: object description: Success envelope for the per-stage candidates list endpoint. required: - status - data properties: status: type: string description: Response status ("success"). enum: - success data: type: object required: - candidates - pagination properties: candidates: type: array description: Array of candidate objects with complete details. items: $ref: '#/components/schemas/JobCandidateForStage' pagination: $ref: '#/components/schemas/JobCandidatePagination' ApiError: type: object description: Canonical error envelope used by most non-authentication errors. required: - error properties: error: $ref: '#/components/schemas/ApiErrorBody' JobCandidateForStage: type: object description: | Job candidate item as returned by the per-stage list endpoint (`GET /job-candidates/stage/{stageId}/candidates`), combining data from the `candidate_details` and `job_candidate_details` tables. Naming caution: this shape uses `jobCandidateId` with `addedAt`/`updatedAt` timestamps and carries BOTH `status` and `evaluationStatus`. The bulk-fetch shape (`JobCandidate`) names the identifier `id` and has only `evaluationStatus`; the per-job list shape (`JobCandidateForJob`) uses `createdAt` instead of `addedAt` and has only `status`. properties: jobCandidateId: type: integer description: | Job candidate relationship ID. (The bulk-fetch endpoint and the move-to-stage response name this same identifier `id`.) jobId: type: integer description: Job ID. stageId: type: integer description: Pipeline stage ID. status: type: string description: | Candidate status in the job. Documented example values conflict across this page: "IN_PROGRESS", "REJECTED" (per-stage list field table) versus "PENDING", "APPROVED", "REJECTED" (per-job list field table). The closed value set is unconfirmed, so no enum is imposed. profileMatchScore: type: number minimum: 0 maximum: 100 description: AI-generated profile match score (0-100). criteriaMatches: $ref: '#/components/schemas/JobCandidateCriteriaMatches' recommendToRecruitingFirm: type: boolean description: Whether the candidate is recommended for recruiting firm. aiSummary: type: string description: AI-generated summary of candidate match. evaluationStatus: type: string description: | Evaluation status. Documented example values conflict across this page: "PENDING", "COMPLETED" (per-stage list field table) versus "PENDING", "APPROVED", "REJECTED" (bulk-fetch field table). The closed value set is unconfirmed, so no enum is imposed. addedAt: type: string format: date-time description: | When the candidate was added to the job (ISO 8601). (The per-job list shape names this same timestamp `createdAt`; the underlying column is `createdAt` in `job_candidate_details`.) updatedAt: type: string format: date-time description: Last update timestamp (ISO 8601). candidate_details: $ref: '#/components/schemas/JobCandidateCandidateDetails' customFields: $ref: '#/components/schemas/JobCandidateEnrichedCustomFieldValues' JobCandidatePagination: type: object description: | Pagination block returned by the job-candidate list endpoints. Note it reports `totalCandidates`/`totalPages` and does NOT include a `hasNextPage` flag (unlike some list endpoints in other families). required: - page - perPage - totalCandidates - totalPages properties: page: type: integer description: Current page number. perPage: type: integer description: Items per page. totalCandidates: type: integer description: Total number of candidates matching the filters. totalPages: type: integer description: Total number of pages. ApiErrorBody: type: object description: Canonical error object carried under the `error` key. required: - code - type - message properties: code: type: string description: Machine-readable error code, e.g. `INVALID_REQUEST`. examples: - INVALID_REQUEST type: type: string description: Error category. enum: - validation_error - internal_error - not_found - authorization_error - resource_error - payment_error - subscription_error message: type: string description: Human-readable error message. details: type: object description: Optional per-field validation messages or structured error context. additionalProperties: true AuthMessageError: type: object description: >- Flat authentication error shape (does not use the canonical `error` envelope). required: - message properties: message: type: string examples: - Invalid API key AuthCodeMessageError: type: object description: >- Flat authentication error shape returned when the account subscription is inactive. required: - code - message properties: code: type: string examples: - ACCOUNT_INACTIVE message: type: string examples: - >- Your subscription is inactive. Please renew your plan to continue using this feature. AuthApiKeyError: type: object description: >- Flat authentication error shape returned when the API key does not exist. required: - message - isApiKeyExists properties: message: type: string examples: - API key not found isApiKeyExists: type: boolean JobCandidateCriteriaMatches: type: object description: | Breakdown of how well the candidate matches each job criterion, showing match percentages for different aspects. Only an ad-hoc example is documented — an object with numeric scores keyed by criterion category, e.g. `{"skills": 90, "experience": 80, "education": 75}` — so the key set is not modeled as a fixed contract. additionalProperties: true JobCandidateCandidateDetails: type: object description: | Complete candidate profile as embedded in job-candidate responses under the snake_case key `candidate_details` (all fields from the `candidate_details` table, per the per-stage endpoint's field table). Nested objects here use snake_case keys (e.g. `graduation_year`, `start_date`, `technology_used`), matching the request-side shapes of the Candidates API rather than the camelCase nested shapes that other candidate response endpoints document. The bulk-fetch and per-job list examples on the same page show a subset of these fields and slightly different nested education/work-experience keys (see `JobCandidateEducation` and `JobCandidateWorkExperience`). properties: id: type: integer description: Candidate ID. firstName: type: string description: First name. lastName: type: string description: Last name. email: type: string description: Email address. phone: type: string description: Phone number. resume: type: string description: Resume URL. currentJobTitle: type: string description: Current job title. currentCompany: type: string description: Current company. city: type: string description: City. country: type: string description: Country. skills: description: Skills (comma-separated string or array of strings). oneOf: - type: string - type: array items: type: string coverLetter: type: string description: Cover letter text. linkedin: type: string description: LinkedIn profile URL. gender: type: string description: Gender. dateOfBirth: type: string format: date description: Date of birth. nationality: type: string description: Nationality. industry: type: string description: Industry. category: type: string description: Category. majors: description: | Majors/fields of study. Documented as a string in the field table, but every example on the page shows an array of strings; both forms are accepted here. oneOf: - type: string - type: array items: type: string summary: type: string description: Professional summary. languages: type: array description: Array of languages. items: type: string educations: type: array description: Array of education objects. items: $ref: '#/components/schemas/JobCandidateEducation' githubUrl: type: string description: GitHub profile URL. certifications: type: array description: Array of certification objects. items: $ref: '#/components/schemas/JobCandidateCertification' workExperiences: type: array description: Array of work experience objects. items: $ref: '#/components/schemas/JobCandidateWorkExperience' projectExperiences: type: array description: Array of project experience objects. items: $ref: '#/components/schemas/JobCandidateProjectExperience' JobCandidateEnrichedCustomFieldValues: type: object description: | Enriched custom field values for the candidate, formatted as `{ customFieldId: { label, value, parentSection } }` where each key is a `customFieldId` rendered as a string (e.g. "13"). Fetched from the normalized `customFieldValues` table. Only included in responses when custom field values exist for the candidate. additionalProperties: type: object description: Enriched value of one custom field, keyed by its `customFieldId`. properties: label: type: string description: The display name of the custom field. value: description: | The actual value. Its type depends on the custom field type: string, number, date, boolean, or array. parentSection: type: string description: The section where the field appears in the UI. JobCandidateEducation: type: object description: | Education entry as shown in job-candidate responses. The per-stage example uses the snake_case shape `degree`/`university`/ `graduation_year`, while the bulk-fetch and per-job list examples on the same page show `degree`/`field`/`institution` instead; all documented keys are modeled as optional and the object is left open. Other API families document differing education shapes for their own endpoints. properties: degree: type: string description: Degree obtained (e.g. "Bachelor's"). university: type: string description: University name (per-stage example shape). graduation_year: type: string description: Graduation year, as a string (e.g. "2019"). Per-stage example shape. field: type: string description: Field of study (bulk-fetch and per-job list example shape). institution: type: string description: Institution name (bulk-fetch and per-job list example shape). JobCandidateCertification: type: object description: Certification entry as shown in job-candidate responses. properties: name: type: string description: Certification name. provider: type: string description: Certification provider. JobCandidateWorkExperience: type: object description: | Work experience entry as shown in job-candidate responses. The per-stage example uses the snake_case shape with `start_date`/`end_date`/ `responsibilities`, while the bulk-fetch and per-job list examples on the same page show a `duration` string instead; all documented keys are modeled as optional and the object is left open. properties: title: type: string description: Job title. company: type: string description: Company name. start_date: type: string format: date description: Start date (per-stage example shape). end_date: type: - string - 'null' format: date description: End date; null for a current position (per-stage example shape). responsibilities: type: array description: List of responsibilities (per-stage example shape). items: type: string duration: type: string description: >- Duration string, e.g. "2 years" (bulk-fetch and per-job list example shape). JobCandidateProjectExperience: type: object description: >- Project experience entry as shown in job-candidate responses (snake_case keys). properties: title: type: string description: Project title. technology_used: type: string description: >- Technologies used, as a single string (e.g. "React, Node.js, PostgreSQL"). summary: type: array description: Bullet-point summary lines. items: type: string responses: Unauthorized: description: | Authentication failed. Note that authentication errors use flat body shapes rather than the canonical `error` envelope. content: application/json: schema: anyOf: - $ref: '#/components/schemas/AuthMessageError' - $ref: '#/components/schemas/AuthCodeMessageError' - $ref: '#/components/schemas/AuthApiKeyError' examples: invalidApiKey: summary: Invalid API key value: message: Invalid API key accountInactive: summary: Subscription inactive value: code: ACCOUNT_INACTIVE message: >- Your subscription is inactive. Please renew your plan to continue using this feature. apiKeyNotFound: summary: API key not found value: message: API key not found isApiKeyExists: false TooManyRequests: x-inferred: true description: | Rate limit exceeded. Rate limits are applied at the company level; the response body below is inferred because the current documentation mentions handling 429 responses but does not publish a body. Retry with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: rateLimited: summary: Rate limit exceeded (inferred example) value: error: code: RATE_LIMIT_EXCEEDED type: validation_error message: Too many requests. Please retry with exponential backoff. InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: internalError: summary: Internal error value: error: code: INTERNAL_ERROR type: internal_error message: Something went wrong. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: | Company-scoped API key. Production keys are prefixed `sk_live_`, sandbox keys `sk_test_`, each followed by 22 base62 characters (pattern `^sk_(live|test)_[0-9A-Za-z]{22}$`). Generate keys in the TapTalent dashboard under Account Settings → Developers → API Key Management; a key is shown once at generation and old keys are invalidated immediately on regeneration. ````