Candidates - Taptalent Partner API

The Candidates API allows you to add candidates, bulk upload resumes, retrieve parsed candidate information, list candidates with filters, and fetch individual candidate details.

Add Candidate

Create a new candidate in your company. If a candidate with the same email already exists, the existing candidate will be returned along with a flag indicating it’s an existing candidate.

`POST /candidates`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Request Body

Field	Type	Required	Description
`firstName`	string	Yes	Candidate’s first name (min 1, max 200 characters)
`lastName`	string	Yes	Candidate’s last name (min 1, max 200 characters)
`email`	string	Yes	Candidate’s email address (must be valid email format, max 500 characters)
`phone`	string	No	Candidate’s phone number
`resume`	string	No	URL to candidate’s resume file (must start with http:// or https://). If provided and `shouldParseResume` is true, the resume will be downloaded, stored, and parsed.
`currentJobTitle`	string	No	Candidate’s current job title
`currentCompany`	string	No	Candidate’s current company name
`city`	string	No	City location
`country`	string	No	Country
`skills`	array or string	No	Array of skills (max 200 characters each) or comma-separated string. Arrays will be converted to comma-separated strings.
`linkedin`	string	No	LinkedIn profile URL
`coverLetter`	string	No	Cover letter text
`gender`	string	No	Gender. Must be one of: “male”, “female”, “other”, “Male”, “Female”, “Other”
`dateOfBirth`	string	No	Date of birth (ISO 8601 format)
`nationality`	string	No	Nationality
`industry`	string	No	Industry
`category`	string	No	Category
`jobId`	integer	No	Job ID to associate the candidate with. If provided, resume scoring will be automatically enabled.
`shouldParseResume`	boolean	No	Whether to parse the resume. Default: `true`. Set to `false` if you’re providing parsed data directly (educations, workExperiences, etc.).
`majors`	string	No	Majors/fields of study (comma-separated string or single value)
`summary`	string	No	Professional summary (max 5000 characters)
`languages`	array	No	Array of language strings (max 100 characters each)
`educations`	array	No	Array of education objects (see Education Object below)
`githubUrl`	string	No	GitHub profile URL (must be valid URL)
`certifications`	array	No	Array of certification objects (see Certification Object below)
`workExperiences`	array	No	Array of work experience objects (see Work Experience Object below)
`projectExperiences`	array	No	Array of project experience objects (see Project Experience Object below)

Request Body Example

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "resume": "https://example.com/resumes/john-doe.pdf",
  "currentJobTitle": "Software Engineer",
  "currentCompany": "Tech Corp",
  "city": "San Francisco",
  "country": "United States",
  "skills": ["JavaScript", "React", "Node.js"],
  "linkedin": "https://linkedin.com/in/johndoe",
  "coverLetter": "I am interested in joining your team...",
  "gender": "Male",
  "dateOfBirth": "1995-05-15",
  "nationality": "American",
  "industry": "Technology",
  "category": "Engineering",
  "jobId": 12345,
  "shouldParseResume": true,
  "majors": "Computer Science",
  "summary": "Experienced software engineer with 5+ years...",
  "languages": ["English", "Spanish"],
  "educations": [
    {
      "degree": "Bachelor's",
      "university": "University of California",
      "graduation_year": "2019"
    }
  ],
  "workExperiences": [
    {
      "title": "Senior Software Engineer",
      "company": "Tech Corp",
      "start_date": "2020-01-01",
      "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"
      ]
    }
  ],
  "certifications": [
    {
      "name": "AWS Certified Solutions Architect",
      "provider": "Amazon Web Services"
    }
  ],
  "githubUrl": "https://github.com/johndoe"
}

Example Request

curl -X POST "https://partner-api.taptalent.io/v1/partner/candidates" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "currentJobTitle": "Software Engineer",
    "currentCompany": "Tech Corp",
    "city": "San Francisco",
    "country": "United States",
    "skills": ["JavaScript", "React", "Node.js"],
    "resume": "https://example.com/resumes/john-doe.pdf",
    "jobId": 12345,
    "shouldParseResume": true
  }'

Example Response

{
  "status": "success",
  "data": {
    "candidate": {
      "id": 12345,
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "currentJobTitle": "Software Engineer",
      "currentCompany": "Tech Corp",
      "city": "San Francisco",
      "country": "United States",
      "skills": ["JavaScript", "React", "Node.js"],
      "resume": "https://storage.example.com/resumes/john-doe.pdf",
      "coverLetter": "I am interested in joining your team...",
      "majors": ["Computer Science"],
      "summary": "Experienced software engineer with 5+ years...",
      "languages": ["English", "Spanish"],
      "educations": [
        {
          "degree": "Bachelor's",
          "field": "Computer Science",
          "institution": "University of California",
          "startDate": "2015-09-01",
          "endDate": "2019-06-01"
        }
      ],
      "workExperiences": [
        {
          "title": "Senior Software Engineer",
          "company": "Tech Corp",
          "location": "San Francisco, CA",
          "startDate": "2020-01-01",
          "endDate": null,
          "description": "Led development of..."
        }
      ],
      "projectExperiences": [
        {
          "name": "E-commerce Platform",
          "description": "Built a full-stack e-commerce platform...",
          "technologies": ["React", "Node.js", "PostgreSQL"]
        }
      ],
      "certifications": [
        {
          "name": "AWS Certified Solutions Architect",
          "issuer": "Amazon Web Services",
          "issueDate": "2022-03-15",
          "expiryDate": "2025-03-15"
        }
      ],
      "githubUrl": "https://github.com/johndoe",
      "linkedin": "https://linkedin.com/in/johndoe",
      "gender": "Male",
      "dateOfBirth": "1995-05-15",
      "nationality": "American",
      "industry": "Technology",
      "category": "Engineering"
    },
    "jobCandidateId": 67890,
    "isExisting": false,
    "isAlreadyInJob": false
  }
}

Response Fields

Field	Type	Description
`status`	string	Response status (“success”)
`data.candidate`	object	The created or existing candidate object with all fields flattened
`data.jobCandidateId`	integer	The job candidate ID if `jobId` was provided and candidate was added to the job, otherwise `null`
`data.isExisting`	boolean	Indicates if the candidate already existed (true) or was newly created (false)
`data.isAlreadyInJob`	boolean	Indicates if the candidate was already associated with the specified job (only present when `jobId` is provided)

Candidate Object Fields

The candidate object includes all standard candidate fields with flattened structure (miscellaneous fields are extracted to the top level):

Basic info: id, firstName, lastName, email, phone
Professional info: currentJobTitle, currentCompany, city, country, skills
Resume: resume (URL)
Extended info: majors, summary, languages, educations, workExperiences, projectExperiences, certifications
Social: githubUrl, linkedin
Additional: coverLetter, gender, dateOfBirth, nationality, industry, category

Notes

Duplicate Email Handling: If a candidate with the same email already exists, the existing candidate will be returned with isExisting: true
Job Association: If jobId is provided:
- The candidate will be associated with that job and jobCandidateId will be returned
- Resume scoring will be automatically enabled
- If the candidate is already in the job, in response, isAlreadyInJob will be true
Resume Parsing:
- By default (shouldParseResume: true), if a resume URL is provided, it will be downloaded, stored, and parsed asynchronously
- Webhook events will be sent when parsing completes or fails
Resume Scoring:
- Automatically enabled when jobId is provided
- If shouldParseResume is false and jobId is provided, you must include city, country, educations, and workExperiences for scoring to work.
Skills Format: Skills can be provided as an array or comma-separated string.
Response Structure: All miscellaneous fields (educations, workExperiences, etc.) are flattened to the top level in the response
Validation: All fields are validated using schema. Invalid requests will return detailed error messages with field-specific errors

Webhook Events

When you add a candidate with a resume URL, webhook events are triggered for resume parsing:

resume.single_parse.completed: Sent when the resume parsing completes successfully

{
  "event": "resume.single_parse.completed",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": "companyId_1",
  "data": {
    "candidateId": 12345,
    "status": "SUCCESS"
  }
}

resume.single_parse.failed: Sent when the resume parsing fails

{
  "event": "resume.single_parse.failed",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": "companyId_1",
  "data": {
    "candidateId": 12345,
    "status": "FAILED",
    "error": "Resume parsing failed"
  }
}

When you add a candidate without resume but with a jobId, webhook events are triggered for scoring:

job.candidate.score.completed: Sent when AI scoring is completed for a candidate’s application to a job

{
  "event": "job.candidate.score.completed",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": 12345,
  "data": {
    "jobId": 12345,
    "jobCandidateId": 101,
    "candidateId": "candidateId_1"
  }
}

job.candidate.score.failed: Sent when AI scoring fails for a candidate’s application to a job

{
  "event": "job.candidate.score.failed",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": 12345,
  "data": {
    "jobId": 12345,
    "jobCandidateId": 101,
    "candidateId": "candidateId_1",
    "error": "Scoring failed: insufficient candidate data"
  }
}

Error Responses

Missing firstName:

{
  "error": {
    "code": "MISSING_FIRST_NAME",
    "type": "validation_error",
    "message": "firstName is required"
  }
}

Missing lastName:

{
  "error": {
    "code": "MISSING_LAST_NAME",
    "type": "validation_error",
    "message": "lastName is required"
  }
}

Missing email:

{
  "error": {
    "code": "MISSING_EMAIL",
    "type": "validation_error",
    "message": "email is required"
  }
}

Invalid request (validation errors):

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "One or more fields are invalid.",
    "details": {
      "email": "email must be a valid email address",
      "resume": "resume must be a valid URL starting with http:// or https://",
      "firstName": "firstName is required"
    }
  }
}

Insufficient credits for resume parsing:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "type": "payment_error",
    "message": "Insufficient credits for resume parsing"
  }
}

Insufficient credits for resume scoring:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "type": "payment_error",
    "message": "Insufficient credits for resume scoring"
  }
}

Missing scoring fields (when scoring without parsing):

{
  "error": {
    "code": "MISSING_SCORING_FIELDS",
    "type": "validation_error",
    "message": "When scoring is required (jobId provided) without parsing, these fields are required: educations, workExperiences, city, country",
    "details": {
      "missingFields": ["city", "country"]
    }
  }
}

Object Schemas

Education Object

Field	Type	Required	Description
`degree`	string	No	Degree name (max 500 characters)
`university`	string	No	University/institution name (max 500 characters)
`graduation_year`	string	No	Graduation year (max 50 characters)

Work Experience Object

Field	Type	Required	Description
`title`	string	No	Job title (max 500 characters)
`company`	string	No	Company name (max 500 characters)
`start_date`	string	No	Start date (max 50 characters)
`end_date`	string	No	End date (max 50 characters). Omit this field for current positions
`responsibilities`	array	No	Array of responsibility strings (max 2000 characters each)

Project Experience Object

Field	Type	Required	Description
`title`	string	No	Project title (max 500 characters)
`technology_used`	string	No	Technologies used (max 1000 characters)
`summary`	array	No	Array of summary strings (max 2000 characters each)

Certification Object

Field	Type	Required	Description
`name`	string	Yes	Certification name (max 500 characters)
`provider`	string	Yes	Certification provider/issuer (max 500 characters)

List Candidates

Retrieve a paginated list of candidates in your company with advanced filtering options.

`GET /candidates/list`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Query Parameters

Parameter	Type	Required	Description
`jobIds`	string	No	Comma-separated list of job IDs (integers) to filter candidates by
`stageIds`	string	No	Comma-separated list of stage IDs to filter candidates by
`searchTerm`	string	No	Search term to filter candidates by name, email, or other fields
`currentJobTitle`	string	No	Filter by candidate’s current job title
`currentCompany`	string	No	Filter by candidate’s current company
`candidatePhone`	string	No	Filter by candidate’s phone number
`candidateEmail`	string	No	Filter by candidate’s email address
`skills`	string	No	Comma-separated list of skills to filter by (case-insensitive)
`groupIds`	string	No	Comma-separated list of group IDs to filter by
`includeOnlyRejecetedCandidates`	string	No	Set to “true” to include only rejected candidates (default: “false”)
`source`	string	No	Filter by candidate source
`createdAtMin`	string (ISO 8601)	No	Return candidates created in the system on or after this datetime
`createdAtMax`	string (ISO 8601)	No	Return candidates created in the system on or before this datetime
`appliedAtMin`	string (ISO 8601)	No	Return candidates who applied / were added to a job on or after this datetime
`appliedAtMax`	string (ISO 8601)	No	Return candidates who applied / were added to a job on or before this datetime
`includeJobApplicationDetails`	string	No	Set to `"true"` to include each candidate’s current job applications in `jobCandidateDetails` (default: `"false"`)
`perPage`	integer	No	Items per page. Must be one of: 10, 20, 40, 80, 100 (default: 10)
`pageNumber`	integer	No	Page number (0-indexed, default: 0)

createdAtMin / createdAtMax filter on when the candidate record was created in TapTalent.appliedAtMin / appliedAtMax filter on when the candidate applied or was added to a job. Candidates match if they have at least one application in that range. When includeJobApplicationDetails=true, the response returns their current job applications (not only the in-range application).

Example Request

Basic list with skills and title filters:

curl -X GET "https://partner-api.taptalent.io/v1/partner/candidates/list?pageNumber=0&perPage=20&skills=javascript,react&currentJobTitle=Software%20Engineer" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"

Filter by candidate created date range:

curl -X GET "https://partner-api.taptalent.io/v1/partner/candidates/list?pageNumber=0&perPage=20&createdAtMin=2026-01-01T00:00:00.000Z&createdAtMax=2026-03-31T23:59:59.999Z" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"

Filter by job application date range and include job application details:

curl -X GET "https://partner-api.taptalent.io/v1/partner/candidates/list?pageNumber=0&perPage=20&appliedAtMin=2026-07-01T00:00:00.000Z&appliedAtMax=2026-07-31T23:59:59.999Z&includeJobApplicationDetails=true" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"

Combine job filter, applied date range, and job application details:

curl -X GET "https://partner-api.taptalent.io/v1/partner/candidates/list?pageNumber=0&perPage=20&jobIds=12345&appliedAtMin=2026-07-01T00:00:00.000Z&appliedAtMax=2026-07-31T23:59:59.999Z&includeJobApplicationDetails=true" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"

Example Response

{
  "status": "success",
  "data": {
    "candidates": [
      {
        "id": 12345,
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "+1234567890",
        "currentJobTitle": "Software Engineer",
        "currentCompany": "Tech Corp",
        "city": "San Francisco",
        "country": "United States",
        "skills": ["JavaScript", "React", "Node.js"],
        "resume": "https://storage.example.com/resumes/john-doe.pdf",
        "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",
        "createdAt": "2026-01-15T10:00:00.000Z",
        "updatedAt": "2026-07-15T12:00:00.000Z",
        "jobCandidateDetails": [
          {
            "jobCandidateId": 98765,
            "jobId": 12345,
            "stageId": 101,
            "status": "ACTIVE",
            "source": "FACEBOOK",
            "evaluationStatus": null,
            "matchedScoreByAI": 82,
            "hiredAt": null,
            "appliedAt": "2026-07-15T10:00:00.000Z",
            "updatedAt": "2026-07-20T09:00:00.000Z",
            "job": {
              "jobId": 12345,
              "title": "Software Engineer",
              "city": "Manila",
              "country": "PH",
              "status": "ACTIVE"
            }
          }
        ]
      }
    ],
    "pagination": {
      "page": 0,
      "perPage": 20,
      "totalCandidates": 150,
      "totalPages": 8,
      "hasNextPage": true
    }
  }
}

jobCandidateDetails is only present when includeJobApplicationDetails=true.

Response Fields

Field	Type	Description
`status`	string	Response status (“success”)
`data.candidates`	array	Array of candidate objects
`data.pagination.page`	number	Current page number (0-indexed)
`data.pagination.perPage`	number	Number of items per page
`data.pagination.totalCandidates`	number	Total number of candidates matching the filters
`data.pagination.totalPages`	number	Total number of pages
`data.pagination.hasNextPage`	boolean	Indicates if there are more pages

Candidate Object Fields

The candidate objects include all standard candidate fields:

Basic info: id, firstName, lastName, email, phone
Professional info: currentJobTitle, currentCompany, city, country, skills
Resume: resume (URL)
Extended info: majors, summary, languages, educations, workExperiences, projectExperiences, certifications
Social: githubUrl, linkedin
Timestamps: createdAt, updatedAt
Optional (when includeJobApplicationDetails=true): jobCandidateDetails

`jobCandidateDetails` Object Fields

Returned only when includeJobApplicationDetails=true.

Field	Type	Description
`jobCandidateId`	integer	Job-candidate association ID
`jobId`	integer	Job ID
`stageId`	integer	Current pipeline stage ID
`status`	string	Application status (e.g. `ACTIVE`, `REJECTED`)
`source`	string \| null	Application source
`evaluationStatus`	string \| null	Evaluation status
`matchedScoreByAI`	number \| null	AI resume match score
`hiredAt`	string (ISO 8601) \| null	Hire timestamp, if hired
`appliedAt`	string (ISO 8601) \| null	When the candidate was applied/added to this job
`updatedAt`	string (ISO 8601) \| null	Last update timestamp for the application
`job`	object \| null	Job summary (`jobId`, `title`, `city`, `country`, `status`)

Error Responses

Invalid perPage value:

{
  "error": {
    "code": "INVALID_PER_PAGE",
    "type": "validation_error",
    "message": "perPage must be one of: 10, 20, 40, 80, 100"
  }
}

Invalid date:

{
  "error": {
    "code": "INVALID_DATE",
    "type": "validation_error",
    "message": "createdAtMin must be a valid ISO 8601 date/datetime"
  }
}

Invalid date range (min after max):

{
  "error": {
    "code": "INVALID_DATE_RANGE",
    "type": "validation_error",
    "message": "createdAtMin must be less than or equal to createdAtMax"
  }
}

Get Candidate Details

Retrieve detailed information about a specific candidate, including their associated jobs.

`GET /candidates/:candidateId`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Path Parameters

Parameter	Type	Description
`candidateId`	integer	The unique identifier of the candidate

Example Request

curl -X GET "https://partner-api.taptalent.io/v1/partner/candidates/12345" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"

Example Response

{
  "status": "success",
  "data": {
    "id": 12345,
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "currentJobTitle": "Software Engineer",
    "currentCompany": "Tech Corp",
    "city": "San Francisco",
    "state": "California",
    "country": "United States",
    "skills": ["JavaScript", "React", "Node.js"],
    "resume": "https://storage.example.com/resumes/john-doe.pdf",
    "coverLetter": "I am interested in...",
    "majors": ["Computer Science"],
    "summary": "Experienced software engineer with 5+ years...",
    "languages": ["English", "Spanish"],
    "educations": [
      {
        "degree": "Bachelor's",
        "field": "Computer Science",
        "institution": "University of California",
        "startDate": "2015-09-01",
        "endDate": "2019-06-01"
      }
    ],
    "workExperiences": [
      {
        "title": "Senior Software Engineer",
        "company": "Tech Corp",
        "location": "San Francisco, CA",
        "startDate": "2020-01-01",
        "endDate": null,
        "description": "Led development of..."
      }
    ],
    "projectExperiences": [
      {
        "name": "E-commerce Platform",
        "description": "Built a full-stack e-commerce platform...",
        "technologies": ["React", "Node.js", "PostgreSQL"]
      }
    ],
    "certifications": [
      {
        "name": "AWS Certified Solutions Architect",
        "issuer": "Amazon Web Services",
        "issueDate": "2022-03-15",
        "expiryDate": "2025-03-15"
      }
    ],
    "githubUrl": "https://github.com/johndoe",
    "linkedin": "https://linkedin.com/in/johndoe",
    "gender": "Male",
    "dateOfBirth": "1995-05-15",
    "nationality": "American",
    "industry": "Technology",
    "category": "Engineering"
  }
}

Response Fields

The response includes all candidate fields with flattened structure (miscellaneous fields are extracted to the top level):

Field	Type	Description
`id`	integer	Unique candidate identifier
`firstName`	string	Candidate’s first name
`lastName`	string	Candidate’s last name
`email`	string	Candidate’s email address
`phone`	string	Candidate’s phone number
`currentJobTitle`	string	Current job title
`currentCompany`	string	Current company name
`city`	string	City location
`state`	string	State/province
`country`	string	Country
`skills`	array	Array of skills
`resume`	string	URL to resume file
`coverLetter`	string	Cover letter text
`majors`	array	Array of majors/fields of study
`summary`	string	Professional summary
`languages`	array	Array of languages
`educations`	array	Array of education objects
`workExperiences`	array	Array of work experience objects
`projectExperiences`	array	Array of project experience objects
`certifications`	array	Array of certification objects
`githubUrl`	string	GitHub profile URL
`linkedin`	string	LinkedIn profile URL
`gender`	string	Gender
`dateOfBirth`	string	Date of birth
`nationality`	string	Nationality
`industry`	string	Industry
`category`	string	Category

Error Responses

Missing candidateId:

{
  "error": {
    "code": "MISSING_CANDIDATE_ID",
    "type": "validation_error",
    "message": "candidateId is required"
  }
}

Candidate not found:

{
  "error": {
    "code": "CANDIDATE_NOT_FOUND",
    "type": "resource_error",
    "message": "Candidate not found"
  }
}

Update Candidate

Update a candidate’s profile. This is a partial update: send only the fields you want to change. All request body fields are optional, but at least one must be provided.

`PATCH /candidates/:candidateId`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Path Parameters

Parameter	Type	Required	Description
`candidateId`	integer	Yes	The unique identifier of the candidate

Request Body (all optional; at least one required)

Same fields as Add Candidate are supported, except jobId and shouldParseResume. Include only the fields you want to update.

Field	Type	Description
`firstName`	string	First name (min 1, max 200 characters)
`lastName`	string	Last name (min 1, max 200 characters)
`email`	string	Email address (valid format). Must be unique within your company.
`phone`	string	Phone number
`currentJobTitle`	string	Current job title
`currentCompany`	string	Current company
`city`	string	City
`country`	string	Country
`skills`	array or string	Skills (array or comma-separated)
`linkedin`	string	LinkedIn profile URL
`coverLetter`	string	Cover letter text
`gender`	string	One of: “male”, “female”, “other”, “Male”, “Female”, “Other”
`dateOfBirth`	string	Date of birth (ISO 8601)
`nationality`	string	Nationality
`industry`	string	Industry
`category`	string	Category
`majors`	string	Majors/fields of study
`summary`	string	Professional summary (max 5000 characters)
`languages`	array	Array of language strings
`educations`	array	Array of education objects (see Add Candidate schema)
`githubUrl`	string	GitHub profile URL
`certifications`	array	Array of certification objects
`workExperiences`	array	Array of work experience objects
`projectExperiences`	array	Array of project experience objects

Example Request

curl -X PATCH "https://partner-api.taptalent.io/v1/partner/candidates/12345" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "currentJobTitle": "Senior Software Engineer",
    "currentCompany": "New Tech Corp",
    "phone": "+1234567890"
  }'

Example Response

{
  "status": "success",
  "message": "Candidate updated successfully",
  "data": {
    "id": 12345,
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "currentJobTitle": "Senior Software Engineer",
    "currentCompany": "New Tech Corp",
    "city": "San Francisco",
    "country": "United States",
    "skills": ["JavaScript", "React", "Node.js"],
    "resume": "https://storage.example.com/resumes/john-doe.pdf",
    "majors": ["Computer Science"],
    "summary": "Experienced software engineer...",
    "languages": ["English", "Spanish"],
    "educations": [],
    "workExperiences": [],
    "projectExperiences": [],
    "certifications": [],
    "githubUrl": "https://github.com/johndoe",
    "linkedin": "https://linkedin.com/in/johndoe"
  }
}

Notes

Partial update: Only included fields are updated; others are left unchanged.
Email uniqueness: If you change email, it must not already exist for another candidate in your company.
Resume: Updating resume URL is not supported via this endpoint.

Error Responses

Invalid candidateId:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Invalid candidateId"
  }
}

Candidate not found:

{
  "error": {
    "code": "CANDIDATE_NOT_FOUND",
    "type": "resource_error",
    "message": "Candidate not found"
  }
}

Duplicate email:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Another candidate with this email already exists in your company"
  }
}

Validation errors:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "One or more fields are invalid.",
    "details": {
      "email": "email must be a valid email address"
    }
  }
}

Bulk Upload Resumes

Upload multiple resumes for parsing and candidate creation.

`POST /candidates/bulk/resume`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Request Body

Field	Type	Required	Description
`resumeURLs`	array of strings	Yes	Array of publicly accessible URLs pointing to resume files (PDF, DOC, DOCX). Maximum 5,000 resumes per request.

Request Body Example

{
  "resumeURLs": [
    "https://example.com/resumes/john-doe.pdf",
    "https://example.com/resumes/jane-smith.docx",
    "https://example.com/resumes/bob-johnson.pdf"
  ]
}

Example Request

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

Example Response

{
  "success": true,
  "data": {
    "batchId": 12345,
    "fileCount": 2
  }
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`data.batchId`	integer	Unique identifier for this batch. Use this to retrieve candidates later.
`data.fileCount`	number	Number of resumes in the batch

Validation Rules

resumeURLs must be provided and cannot be empty
resumeURLs must be an array
Each URL must be a non-empty string (whitespace-only strings are invalid)
URLs must be publicly accessible
Maximum 5,000 resume URLs per request

Webhook Events

When you upload resumes, webhook events are triggered:

resume.bulk_upload_parse.started: Sent when batch processing starts

{
  "event": "resume.bulk_upload_parse.started",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": "companyId_1",
  "data": {
    "batchId": 12345,
    "fileCount": 2,
    "jobId": 67890
  }
}

resume.bulk_upload_parse.completed: Sent when batch processing completes

{
  "event": "resume.bulk_upload_parse.completed",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": "companyId_1",
  "data": {
    "batchId": 12345,
    "status": "COMPLETED",
    "fileCount": 25,
    "successCount": 23,
    "failedCount": 2,
    "jobId": 67890,
    "error": null,
    "errorCode": null
  }
}

Note: If there are insufficient credits, the error and errorCode fields will be populated:

{
  "event": "resume.bulk_upload_parse.completed",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": "companyId_1",
  "data": {
    "batchId": 12345,
    "status": "COMPLETED",
    "fileCount": 25,
    "successCount": 0,
    "failedCount": 25,
    "jobId": 67890,
    "error": "You have insufficient credits to parse the resume.",
    "errorCode": "INSUFFICIENT_CREDITS"
  }
}

resume.bulk_upload_parse.failed: Sent if batch processing fails

{
  "event": "resume.bulk_upload_parse.failed",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": "companyId_1",
  "data": {
    "error": "Error message"
  }
}

Error Responses

Missing resumeURLs:

{
  "error": {
    "code": "MISSING_RESUME_URLS",
    "type": "validation_error",
    "message": "resumeURLs is required in the request body"
  }
}

Invalid resumeURLs format:

{
  "error": {
    "code": "INVALID_RESUME_URLS",
    "type": "validation_error",
    "message": "resumeURLs must be an array of URLs",
    "details": {
      "invalidCount": 1
    }
  }
}

Exceeded maximum resume URLs:

{
  "error": {
    "code": "EXCEEDED_MAX_RESUME_URLS",
    "type": "validation_error",
    "message": "Maximum 5000 resume URLs allowed per request",
    "details": {
      "provided": 6000,
      "maximum": 5000
    }
  }
}

Invalid URL format (non-empty string validation):

{
  "error": {
    "code": "INVALID_RESUME_URLS",
    "type": "validation_error",
    "message": "All resumeURLs must be non-empty strings",
    "details": {
      "invalidCount": 2
    }
  }
}

Empty resumeURLs array:

{
  "error": {
    "code": "MISSING_RESUME_URLS",
    "type": "validation_error",
    "message": "resumeURLs array cannot be empty"
  }
}

Company not found:

{
  "error": {
    "code": "COMPANY_NOT_FOUND",
    "type": "resource_error",
    "message": "Company not found for this API key"
  }
}

Subscription not active:

{
  "error": {
    "code": "SUBSCRIPTION_NOT_ACTIVE",
    "type": "subscription_error",
    "message": "Your subscription is not active. Please renew to continue."
  }
}

Get Batch Candidates

Retrieve parsed candidates from a batch with pagination.

`GET /candidates/batch/:batchId`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Path Parameters

Parameter	Type	Description
`batchId`	integer	The batch ID returned from the bulk upload endpoint

Query Parameters

Parameter	Type	Required	Description
`pageNumber`	integer	No	Page number (default: 1)
`perPage`	integer	No	Items per page. Must be one of: 10, 20, 40, 80, 100 (default: 10)

Example Request

curl -X GET "https://partner-api.taptalent.io/v1/partner/candidates/batch/12345?pageNumber=1&perPage=20" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": {
    "batchId": 12345,
    "batchStatus": "COMPLETED",
    "total": 45,
    "pageNumber": 1,
    "perPage": 20,
    "hasNextPage": true,
    "candidates": [
      {
        "id": 12345,
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+1234567890",
        "resumeUrl": "https://storage.example.com/resumes/john-doe.pdf",
        "createdAt": "2024-01-20T14:45:00Z"
      },
      {
        "id": 12346,
        "name": "Jane Smith",
        "email": "jane.smith@example.com",
        "phone": "+0987654321",
        "resumeUrl": "https://storage.example.com/resumes/john-doe.pdf",
        "createdAt": "2024-01-20T14:46:00Z"
      }
    ]
  }
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`data.batchId`	integer	The batch ID
`data.batchStatus`	string	Batch processing status (e.g., “PROCESSING”, “COMPLETED”, “FAILED”)
`data.total`	number	Total number of candidates in the batch
`data.pageNumber`	number	Current page number
`data.perPage`	number	Number of items per page
`data.hasNextPage`	boolean	Indicates if there are more pages
`data.candidates`	array	Array of candidate objects

Candidate Object Fields

Field	Type	Description
`id`	integer	Unique candidate identifier
`name`	string	Candidate’s full name
`email`	string	Candidate’s email address
`phone`	string	Candidate’s phone number
`resumeUrl`	string	URL to the stored resume file
`createdAt`	string (ISO 8601)	Timestamp when candidate was created

Error Responses

Invalid batchId:

{
  "error": {
    "code": "INVALID_BATCH_ID",
    "type": "validation_error",
    "message": "batchId is required"
  }
}

Batch not found:

{
  "error": {
    "code": "BATCH_NOT_FOUND",
    "type": "resource_error",
    "message": "Batch not found"
  }
}

Unauthorized access:

{
  "error": {
    "code": "UNAUTHORIZED_ACCESS",
    "type": "authorization_error",
    "message": "You do not have access to this batch"
  }
}

Invalid perPage value:

{
  "error": {
    "code": "INVALID_PER_PAGE",
    "type": "validation_error",
    "message": "perPage must be one of: 10, 20, 40, 80, 100"
  }
}

Use Cases

Candidate Search and Filtering

Use the list endpoint to search and filter candidates:

Search by Skills: Filter candidates by specific skills (e.g., skills=javascript,react,node.js)
Filter by Job: Find candidates associated with specific jobs (jobIds=12345,12346)
Filter by Stage: Get candidates in specific pipeline stages (stageIds=789,790)
Search by Contact Info: Find candidates by email or phone (candidateEmail=john@example.com)
Filter by Current Role: Find candidates with specific job titles or companies (currentJobTitle=Software Engineer)
Filter by Created Date: Find candidates created in the system in a date range (createdAtMin / createdAtMax)
Filter by Application Date: Find candidates who applied to a job in a date range (appliedAtMin / appliedAtMax)
Include Job Applications: Return current job application details with includeJobApplicationDetails=true

Candidate Detail Retrieval

Get comprehensive candidate information:

Retrieve full candidate profile including work experience, education, and certifications
Access candidate’s resume and cover letter
View candidate’s social profiles (LinkedIn, GitHub)
Get complete candidate history and details

Bulk Candidate Ingestion

Upload multiple resumes at once to quickly build your candidate database:

Collect resume URLs from your ATS or other sources
Upload them in batches (up to 5,000 per batch)
Receive webhook notifications when processing starts/completes
Retrieve parsed candidates using the batch ID

Resume Parsing Pipeline

Integrate TapTalent’s resume parsing into your workflow:

Upload resumes as they come in
Receive real-time webhook notifications
Retrieve parsed candidate data programmatically
Sync with your internal systems

Best Practices

Filtering and Search

Use Specific Filters: Combine multiple filters for precise results (e.g., skills + currentJobTitle)
Pagination: Use appropriate perPage values (10, 20, 40, 80, or 100) based on your needs
Search Terms: Use searchTerm for broad text searches across multiple fields
Comma-Separated Lists: For array filters (jobIds, stageIds, skills, groupIds), use comma-separated values
Case Sensitivity: Skill searches are case-insensitive, but other text filters may be case-sensitive
Date Ranges: Use ISO 8601 datetimes for createdAtMin/createdAtMax and appliedAtMin/appliedAtMax; ensure min ≤ max
Job Application Details: Only request includeJobApplicationDetails=true when you need application/job context — responses are larger

Candidate Details

Cache Results: Cache candidate details to reduce API calls for frequently accessed candidates
Error Handling: Always handle 404 errors for candidates that may have been deleted
Field Access: All miscellaneous fields (educations, workExperiences, etc.) are flattened to the top level

Batch Size

You can upload up to 5,000 resume URLs in a single request
For very large uploads (1,000+ resumes), consider splitting into multiple requests to better track progress
Use batches of 50-500 resumes for optimal balance between speed and tracking

Error Handling

Handle webhook events for batch status updates
Implement retry logic for failed uploads
Monitor batch status and handle failures gracefully

Pagination

Use appropriate perPage values (10, 20, 40, 80, or 100)
Check hasNextPage to determine if more data is available
Implement pagination loops to retrieve all candidates
Note that list endpoint uses 0-indexed pages (pageNumber=0 for first page)

Webhook Integration

Set up webhook URL to receive batch status updates
Handle both success and failure webhook events
Use webhooks to trigger downstream processing

Bulk Fetch Candidates

Fetch multiple candidates by their IDs in a single request.

`POST /candidates/bulk-fetch`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Request Body

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

Request Body Example

{
  "candidateIds": [
    12345,
    12346,
    12347
  ]
}

Example Request

curl -X POST "https://partner-api.taptalent.io/v1/partner/candidates/bulk-fetch" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "candidateIds": [
      12345,
      12346
    ]
  }'

Example Response

{
  "status": "success",
  "data": [
    {
      "id": 12345,
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "currentJobTitle": "Software Engineer",
      "currentCompany": "Tech Corp",
      "city": "San Francisco",
      "country": "United States",
      "skills": ["JavaScript", "React", "Node.js"],
      "resume": "https://storage.example.com/resumes/john-doe.pdf",
      "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"
    }
  ],
  "invalidCandidateIds": [12347]
}

Response Fields

Field	Type	Description
`status`	string	Response status (“success”)
`data`	array	Array of candidate objects
`invalidCandidateIds`	array (optional)	Array of candidate IDs that were not found (only included if any IDs are invalid)

Validation Rules

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

Error Responses

Missing candidateIds:

{
  "error": {
    "code": "MISSING_CANDIDATE_IDS",
    "type": "validation_error",
    "message": "candidateIds is required in the request body"
  }
}

Invalid candidateIds format:

{
  "error": {
    "code": "INVALID_CANDIDATE_IDS",
    "type": "validation_error",
    "message": "candidateIds must be an array",
    "details": {
      "invalidCount": 1
    }
  }
}

Exceeded maximum:

{
  "error": {
    "code": "EXCEEDED_MAX_CANDIDATES",
    "type": "validation_error",
    "message": "Maximum 100 candidateIds allowed per request",
    "details": {
      "provided": 150,
      "maximum": 100
    }
  }
}

Next Steps

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

​Add Candidate

​POST /candidates

​Authentication

​Request Body

​Request Body Example

​Example Request

​Example Response

​Response Fields

​Candidate Object Fields

​Notes

​Webhook Events

​Error Responses

​Object Schemas

​Education Object

​Work Experience Object

​Project Experience Object

​Certification Object

​List Candidates

​GET /candidates/list

​Authentication

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Candidate Object Fields

​jobCandidateDetails Object Fields

​Error Responses

​Get Candidate Details

​GET /candidates/:candidateId

​Authentication

​Path Parameters

​Example Request

​Example Response

​Response Fields

​Error Responses

​Update Candidate

​PATCH /candidates/:candidateId

​Authentication

​Path Parameters

​Request Body (all optional; at least one required)

​Example Request

​Example Response

​Notes

​Error Responses

​Bulk Upload Resumes

​POST /candidates/bulk/resume

​Authentication

​Request Body

​Request Body Example

​Example Request

​Example Response

​Response Fields

​Validation Rules

​Webhook Events

​Error Responses

​Get Batch Candidates

​GET /candidates/batch/:batchId

​Authentication

​Path Parameters

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Candidate Object Fields

​Error Responses

​Use Cases

​Candidate Search and Filtering

​Candidate Detail Retrieval

​Bulk Candidate Ingestion

​Resume Parsing Pipeline

​Best Practices

​Filtering and Search

​Candidate Details

​Batch Size

​Error Handling

​Pagination

​Webhook Integration

​Bulk Fetch Candidates

​POST /candidates/bulk-fetch

​Authentication

Add Candidate

`POST /candidates`

Authentication

Request Body

Request Body Example

Example Request

Example Response

Response Fields

Candidate Object Fields

Notes

Webhook Events

Error Responses

Object Schemas

Education Object

Work Experience Object

Project Experience Object

Certification Object

List Candidates

`GET /candidates/list`

Authentication

Query Parameters

Example Request

Example Response

Response Fields

Candidate Object Fields

`jobCandidateDetails` Object Fields

Error Responses

Get Candidate Details

`GET /candidates/:candidateId`

Authentication

Path Parameters

Example Request

Example Response

Response Fields

Error Responses

Update Candidate

`PATCH /candidates/:candidateId`

Authentication

Path Parameters

Request Body (all optional; at least one required)

Example Request

Example Response

Notes

Error Responses

Bulk Upload Resumes

`POST /candidates/bulk/resume`

Authentication

Request Body

Request Body Example

Example Request

Example Response

Response Fields

Validation Rules

Webhook Events

Error Responses

Get Batch Candidates

`GET /candidates/batch/:batchId`

Authentication

Path Parameters

Query Parameters

Example Request

Example Response

Response Fields

Candidate Object Fields

Error Responses

Use Cases

Candidate Search and Filtering

Candidate Detail Retrieval

Bulk Candidate Ingestion

Resume Parsing Pipeline

Best Practices

Filtering and Search

Candidate Details

Batch Size

Error Handling

Pagination

Webhook Integration

Bulk Fetch Candidates

`POST /candidates/bulk-fetch`

Authentication