Job Candidates

Job Candidates API

The Job Candidates API allows you to manage candidates that are associated with specific jobs. This includes bulk fetching job candidates and uploading resumes directly to jobs.

Understanding Job Criteria and Candidate Matching: When you upload resumes to a job or add candidates, TapTalent’s AI automatically evaluates each candidate against the job’s criterionDetails (job requirements). The AI generates a profile match score and detailed matching information based on how well candidates meet your “Must Have”, “Nice to Have”, and “Bonus” criteria. See the Job Criteria section in the Jobs API documentation for details on how to set up effective job criteria.

Bulk Fetch Job Candidates

Fetch multiple job candidates by their IDs in a single request. This returns candidates with their job-specific information including AI matching scores and evaluation status.

`POST /v1/partner/job-candidates/bulk-fetch`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Request Body

Field	Type	Required	Description
`jobCandidateIds`	array of strings/numbers	Yes	Array of job candidate IDs to fetch. Maximum 100 IDs per request.

Request Body Example

{
  "jobCandidateIds": [
    "job-candidate-uuid-1",
    "job-candidate-uuid-2",
    "job-candidate-uuid-3"
  ]
}

Example Request

curl -X POST "https://partner-api.taptalent.io/v1/partner/job-candidates/bulk-fetch" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "jobCandidateIds": [
      "job-candidate-uuid-1",
      "job-candidate-uuid-2"
    ]
  }'

Example Response

{
  "status": "success",
  "data": [
    {
      "id": "job-candidate-uuid-1",
      "jobId": "job-uuid",
      "candidateId": "candidate-uuid",
      "profileMatchScore": 85,
      "evaluationStatus": "PENDING",
      "criteriaMatches": {
        "skills": 90,
        "experience": 80,
        "education": 75
      },
      "recommendToRecruitingFirm": true,
      "aiSummary": "Strong candidate with relevant experience...",
      "candidate_details": {
        "id": "candidate-uuid",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "phone": "+1234567890",
        "currentJobTitle": "Software Engineer",
        "currentCompany": "Tech Corp",
        "city": "San Francisco",
        "country": "United States",
        "skills": ["JavaScript", "React", "Node.js"],
        "resume": "https://s3.amazonaws.com/...",
        "majors": ["Computer Science"],
        "summary": "Experienced software engineer...",
        "languages": ["English"],
        "educations": [
          {
            "degree": "Bachelor's",
            "field": "Computer Science",
            "institution": "University"
          }
        ],
        "workExperiences": [
          {
            "title": "Software Engineer",
            "company": "Tech Corp",
            "duration": "2 years"
          }
        ],
        "projectExperiences": [],
        "certifications": [],
        "githubUrl": "https://github.com/johndoe",
        "linkedin": "https://linkedin.com/in/johndoe"
      }
    }
  ]
}

Response Fields

Field	Type	Description
`status`	string	Response status (“success”)
`data`	array	Array of job candidate objects

Job Candidate Object Fields

Field	Type	Description
`id`	string (UUID)	Job candidate ID
`jobId`	string (UUID)	Associated job ID
`candidateId`	string (UUID)	Candidate ID
`profileMatchScore`	number	AI-generated profile match score (0-100). This score is calculated based on how well the candidate meets the job’s `criterionDetails`. Higher scores indicate better matches.
`evaluationStatus`	string	Evaluation status (e.g., “PENDING”, “APPROVED”, “REJECTED”)
`criteriaMatches`	object	Breakdown of how well the candidate matches each job criterion. Shows match percentages for different aspects like skills, experience, and education.
`recommendToRecruitingFirm`	boolean	Whether candidate is recommended based on AI analysis of job criteria
`aiSummary`	string	AI-generated summary explaining why the candidate is a good (or poor) match for the job based on the criteria
`candidate_details`	object	Full candidate details (see candidate object structure)

How Profile Match Scores Work

The profileMatchScore is calculated by evaluating the candidate’s resume against the job’s criterionDetails:

“Must Have” criteria are weighted most heavily - candidates missing these will have significantly lower scores
“Nice to Have” criteria contribute to the score but won’t disqualify candidates
“Bonus” criteria add points for exceptional candidates but don’t penalize those without them

For example:

A candidate meeting all “Must Have” criteria and most “Nice to Have” criteria might score 85-95
A candidate missing a “Must Have” criterion might score 40-60, even if they meet other criteria
A candidate meeting all criteria including “Bonus” items might score 95-100

Validation Rules

jobCandidateIds must be provided and cannot be empty
jobCandidateIds must be an array
Maximum 100 job candidate IDs per request
Each job candidate ID must be a valid non-empty string or number

Error Responses

Missing jobCandidateIds:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "jobCandidateIds is required and must be a non-empty array."
  }
}

Exceeded maximum:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "jobCandidateIds must not exceed 100 items."
  }
}

Bulk Upload Resumes to Job

Upload multiple resumes for parsing and associate them with a specific job.

`POST /v1/partner/job-candidates/bulk/resume`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Request Body

Field	Type	Required	Description
`jobId`	string (UUID)	Yes	The job ID to associate the resumes with
`resumeURLs`	array of strings	Yes	Array of publicly accessible URLs pointing to resume files (PDF, DOC, DOCX). Maximum 200 resumes per batch.

Request Body Example

{
  "jobId": "job-uuid-here",
  "resumeURLs": [
    "https://example.com/resumes/john-doe.pdf",
    "https://example.com/resumes/jane-smith.docx"
  ]
}

Example Request

curl -X POST "https://partner-api.taptalent.io/v1/partner/job-candidates/bulk/resume" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "job-uuid-here",
    "resumeURLs": [
      "https://example.com/resumes/john-doe.pdf",
      "https://example.com/resumes/jane-smith.docx"
    ]
  }'

Example Response

{
  "success": true,
  "data": {
    "batchId": "batch-uuid-here",
    "fileCount": 2,
    "jobId": "job-uuid-here"
  }
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`data.batchId`	string (UUID)	Unique identifier for this batch. Use this to retrieve candidates later.
`data.fileCount`	number	Number of resumes in the batch
`data.jobId`	string (UUID)	The job ID the resumes are associated with

Validation Rules

jobId must be provided and must be a valid UUID
resumeURLs must be provided and cannot be empty
resumeURLs must be an array
Each URL must be a non-empty string
URLs must be publicly accessible
Maximum 200 resumes per batch
The job must exist and belong to your company

Webhook Events

When you upload resumes to a job, webhook events are triggered:

resume.bulk_upload_parse.started: Sent when batch processing starts
resume.bulk_upload_parse.failed: Sent if batch processing fails

Error Responses

Missing jobId:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Job ID is required"
  }
}

Job not found:

{
  "error": {
    "code": "JOB_NOT_FOUND",
    "type": "validation_error",
    "message": "Job not found"
  }
}

Permission denied:

{
  "error": {
    "code": "PERMISSION_DENIED",
    "type": "validation_error",
    "message": "You are not authorized to access this job"
  }
}

Use Cases

Fetching Job Candidates

Retrieve job candidates with their AI matching scores and evaluation status:

Display candidates for a specific job ranked by match score
Filter candidates by match score (e.g., show only candidates with 70+ match)
Review how well candidates meet your job criteria
Track evaluation status and hiring progress
Access AI-generated summaries explaining candidate fit

Uploading Resumes to Jobs

Upload resumes directly to jobs for parsing and candidate creation:

Associate resumes with specific job postings
Automatically create job candidates with AI evaluation
Receive AI matching scores based on job criteria
See which candidates best match your “Must Have” requirements
Track candidate progress through the hiring pipeline

Important for Recruiters: The quality of your criterionDetails directly impacts the accuracy of candidate matching. Well-defined, specific criteria will result in more accurate match scores and better candidate recommendations. Vague or generic criteria may lead to less reliable matching results.

Next Steps

Set up Webhooks to receive batch status updates
Review Integration Notes for best practices
Explore other API endpoints

Get Started

Authentication

API Reference

Webhooks

Integration Notes

Job Candidates API

Bulk Fetch Job Candidates

`POST /v1/partner/job-candidates/bulk-fetch`

Authentication

Request Body

Request Body Example

Example Request

Example Response

Response Fields

Job Candidate Object Fields

How Profile Match Scores Work

Validation Rules

Error Responses

Bulk Upload Resumes to Job

`POST /v1/partner/job-candidates/bulk/resume`

Authentication

Request Body

Request Body Example

Example Request

Example Response

Response Fields

Validation Rules

Webhook Events

Error Responses

Use Cases

Fetching Job Candidates

Uploading Resumes to Jobs

Next Steps

Get Started

Authentication

API Reference

Webhooks

Integration Notes

​Job Candidates API

​Bulk Fetch Job Candidates

​POST /v1/partner/job-candidates/bulk-fetch

​Authentication

​Request Body

​Request Body Example

​Example Request

​Example Response

​Response Fields

​Job Candidate Object Fields

​How Profile Match Scores Work

​Validation Rules

​Error Responses

​Bulk Upload Resumes to Job

​POST /v1/partner/job-candidates/bulk/resume

​Authentication

​Request Body

​Request Body Example

​Example Request

​Example Response

​Response Fields

​Validation Rules

​Webhook Events

​Error Responses

​Use Cases

​Fetching Job Candidates

​Uploading Resumes to Jobs

​Next Steps

Job Candidates API

Bulk Fetch Job Candidates

`POST /v1/partner/job-candidates/bulk-fetch`

Authentication

Request Body

Request Body Example

Example Request

Example Response

Response Fields

Job Candidate Object Fields

How Profile Match Scores Work

Validation Rules

Error Responses

Bulk Upload Resumes to Job

`POST /v1/partner/job-candidates/bulk/resume`

Authentication

Request Body

Request Body Example

Example Request

Example Response

Response Fields

Validation Rules

Webhook Events

Error Responses

Use Cases

Fetching Job Candidates

Uploading Resumes to Jobs

Next Steps