curl --request POST \
  --url https://partner-api.taptalent.io/v1/partner/candidates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "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"
}
EOF

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

Candidates

Add a candidate

Create a new candidate in your company.

Duplicate email handling: if a candidate with the same email already exists, the existing candidate is returned with isExisting: true instead of creating a duplicate.
Job association: if jobId is provided, the candidate is associated with that job and jobCandidateId is returned; resume scoring is automatically enabled (consumes credits). If the candidate is already in the job, isAlreadyInJob is true in the response.
Resume parsing: by default (shouldParseResume: true), a provided resume URL is downloaded, stored, and parsed asynchronously (consumes credits). The webhook events resume.single_parse.completed and resume.single_parse.failed are sent when parsing completes or fails.
Scoring without parsing: if shouldParseResume is false and jobId is provided, you must include city, country, educations, and workExperiences for scoring to work; otherwise the request fails with MISSING_SCORING_FIELDS (the missing field names are listed in details.missingFields).
Response structure: all miscellaneous fields (educations, workExperiences, etc.) are flattened to the top level of the returned candidate object.
Validation: all fields are validated against a schema; invalid requests return detailed field-specific error messages.

POST

candidates

curl --request POST \
  --url https://partner-api.taptalent.io/v1/partner/candidates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "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"
}
EOF

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

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.

Body

application/json

Request body for creating a candidate. Note that the nested request objects (educations, workExperiences, projectExperiences, certifications) use different field names than the corresponding response objects — see each Input schema's description.

firstName

string

required

Candidate's first name (min 1, max 200 characters).

Required string length: 1 - 200

lastName

string

required

Candidate's last name (min 1, max 200 characters).

Required string length: 1 - 200

string<email>

required

Candidate's email address (must be valid email format, max 500 characters).

Maximum string length: 500

phone

string

Candidate's phone number.

resume

string<uri>

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

Candidate's current job title.

currentCompany

string

Candidate's current company name.

city

string

City location. Required (together with country, educations, and workExperiences) when jobId is provided and shouldParseResume is false.

country

string

Country. Required (together with city, educations, and workExperiences) when jobId is provided and shouldParseResume is false.

skills

Array of skills (max 200 characters each) or a comma-separated string. Arrays will be converted to comma-separated strings.

Maximum string length: 200

string

LinkedIn profile URL.

coverLetter

string

Cover letter text.

gender

enum<string>

Gender. Must be one of: "male", "female", "other", "Male", "Female", "Other".

Available options:

male,

female,

other,

Male,

Female,

Other

dateOfBirth

string<date>

Date of birth (ISO 8601 format).

nationality

string

Nationality.

industry

string

Industry.

Response

Candidate created (or existing candidate returned when the email already exists).

Success envelope for the create-candidate 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

Candidate Self-Scheduling

Webhooks

Add a candidate

Authorizations

Body

Response