List candidates in a pipeline stage

curl --request GET \
  --url https://partner-api.taptalent.io/v1/partner/job-candidates/stage/{stageId}/candidates \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://partner-api.taptalent.io/v1/partner/job-candidates/stage/{stageId}/candidates"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://partner-api.taptalent.io/v1/partner/job-candidates/stage/{stageId}/candidates', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://partner-api.taptalent.io/v1/partner/job-candidates/stage/{stageId}/candidates",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://partner-api.taptalent.io/v1/partner/job-candidates/stage/{stageId}/candidates"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://partner-api.taptalent.io/v1/partner/job-candidates/stage/{stageId}/candidates")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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
    }
  }
}

Job Candidates

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.

GET

job-candidates

stage

{stageId}

candidates

List candidates in a pipeline stage

curl --request GET \
  --url https://partner-api.taptalent.io/v1/partner/job-candidates/stage/{stageId}/candidates \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://partner-api.taptalent.io/v1/partner/job-candidates/stage/{stageId}/candidates"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://partner-api.taptalent.io/v1/partner/job-candidates/stage/{stageId}/candidates', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://partner-api.taptalent.io/v1/partner/job-candidates/stage/{stageId}/candidates",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://partner-api.taptalent.io/v1/partner/job-candidates/stage/{stageId}/candidates"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://partner-api.taptalent.io/v1/partner/job-candidates/stage/{stageId}/candidates")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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
    }
  }
}

Authorizations

Authorization

string

header

required

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.

Path Parameters

stageId

integer

required

The unique identifier of the pipeline stage.

Query Parameters

jobId

integer

Filter candidates by job ID.

startDate

string<date-time>

Filter by date range start (ISO 8601 format, e.g. "2024-01-01T00:00:00Z"). Filters by candidate creation date.

endDate

string<date-time>

Filter by date range end (ISO 8601 format, e.g. "2024-12-31T23:59:59Z"). Filters by candidate creation date.

page

integer

default:1

Page number (default: 1).

Required range: x >= 1

perPage

integer

default:20

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.

Required range: 1 <= x <= 100

orderColumn

enum<string>

default:createdAt

Column to sort by. Default: createdAt.

Available options:

createdAt,

firstName

orderBy

enum<string>

default:DESC

Sort order. Default: DESC.

Available options:

ASC,

DESC

Response

Candidates in the stage.

Success envelope for the per-stage candidates list endpoint.

status

enum<string>

required

Response status ("success").

Available options:

success

data

object

required

Show child attributes

Jobs

Candidates

Job Candidates

Pipelines

Custom Fields

Custom Field Values

Webhooks

List candidates in a pipeline stage

Authorizations

Path Parameters

Query Parameters

Response