> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linkupapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Candidates

> Retrieve applicants for a LinkedIn job posting

Retrieve detailed information about candidates who have applied to your LinkedIn job posting, including their profiles, work experience, education, contact information, and application responses.

<Note>
  This endpoint costs **1 credit** per result.
</Note>

### Header Parameters

<ParamField header="x-api-key" type="string" required>
  Your API key
</ParamField>

### Body Parameters

<ParamField body="job_id" type="string" required>
  LinkedIn job posting ID (e.g., "4178681649", you can get it with the /recruiter/posts endpoint)
</ParamField>

<ParamField body="total_results" type="integer" default="10">
  Number of profiles to retrieve
</ParamField>

<ParamField body="start_page" type="integer">
  First page to fetch when using pagination mode (default: 1)
</ParamField>

<ParamField body="end_page" type="integer">
  Last page to fetch when using pagination mode (default: same as start\_page)
</ParamField>

<ParamField body="start" type="string" default="0">
  Starting position for pagination
</ParamField>

<ParamField body="sortType" type="string" default="RELEVANCE">
  Sorting method. Options: RELEVANCE, APPLIED\_DATE
</ParamField>

<ParamField body="sortOrder" type="string" default="DESCENDING">
  Sorting order. Options: ASCENDING, DESCENDING
</ParamField>

<ParamField body="ratings" type="string" default="GOOD_FIT,MAYBE,UNRATED">
  Candidate ratings to include, comma-separated (e.g, "GOOD\_FIT,MAYBE,UNRATED,NOT\_A\_FIT")
</ParamField>

<ParamField body="location" type="string">
  Filter candidates by location (e.g., "Paris")
</ParamField>

<ParamField body="yearsOfExperience" type="string">
  Filter by years of experience, comma-separated (e.g., "THREE\_TO\_FIVE\_YEARS,SIX\_TO\_TEN\_YEARS")
</ParamField>

<ParamField body="country" type="string" default="FR">
  Country code for proxy selection. Available: (US, UK, FR, DE, NL, IT, IL, CA, BR, ES, IN)
</ParamField>

<ParamField body="login_token" type="string" required>
  LinkedIn authentication cookie () obtained from the login/verify process
</ParamField>

### Response

<ResponseField name="status" type="string">
  Request status (success/error)
</ResponseField>

<ResponseField name="data" type="object">
  Response data container
</ResponseField>

<ResponseField name="data.total_results" type="integer">
  Total number of candidates retrieved
</ResponseField>

<ResponseField name="data.candidates" type="array">
  List of candidate profiles
</ResponseField>

<ResponseField name="data.candidates[].application_id" type="string">
  Unique ID of the application
</ResponseField>

<ResponseField name="data.candidates[].rating" type="string">
  Recruiter's rating of the candidate (GOOD\_FIT, MAYBE, UNRATED, NOT\_A\_FIT)
</ResponseField>

<ResponseField name="data.candidates[].is_top_choice" type="boolean">
  Whether the candidate is marked as a top choice
</ResponseField>

<ResponseField name="data.candidates[].top_choice_message" type="string">
  Message from candidate if marked as top choice
</ResponseField>

<ResponseField name="data.candidates[].first_name" type="string">
  Candidate's first name
</ResponseField>

<ResponseField name="data.candidates[].last_name" type="string">
  Candidate's last name
</ResponseField>

<ResponseField name="data.candidates[].full_name" type="string">
  Candidate's full name
</ResponseField>

<ResponseField name="data.candidates[].headline" type="string">
  Candidate's LinkedIn headline
</ResponseField>

<ResponseField name="data.candidates[].public_identifier" type="string">
  Candidate's LinkedIn URL identifier
</ResponseField>

<ResponseField name="data.candidates[].profile_url" type="string">
  Complete LinkedIn profile URL
</ResponseField>

<ResponseField name="data.candidates[].linkedin_id" type="string">
  Candidate's LinkedIn internal ID
</ResponseField>

<ResponseField name="data.candidates[].location" type="string">
  Candidate's location
</ResponseField>

<ResponseField name="data.candidates[].experiences" type="array">
  List of candidate's work experiences
</ResponseField>

<ResponseField name="data.candidates[].experiences[].title" type="string">
  Job title
</ResponseField>

<ResponseField name="data.candidates[].experiences[].company" type="string">
  Company name
</ResponseField>

<ResponseField name="data.candidates[].experiences[].company_url" type="string">
  LinkedIn URL of the company
</ResponseField>

<ResponseField name="data.candidates[].experiences[].date_range" type="string">
  Employment period
</ResponseField>

<ResponseField name="data.candidates[].experiences[].description" type="string">
  Job description
</ResponseField>

<ResponseField name="data.candidates[].education" type="array">
  List of candidate's education history
</ResponseField>

<ResponseField name="data.candidates[].education[].school" type="string">
  School name
</ResponseField>

<ResponseField name="data.candidates[].education[].school_url" type="string">
  LinkedIn URL of the school/university
</ResponseField>

<ResponseField name="data.candidates[].education[].degree" type="string">
  Degree obtained
</ResponseField>

<ResponseField name="data.candidates[].education[].field" type="string">
  Field of study
</ResponseField>

<ResponseField name="data.candidates[].education[].years" type="string">
  Period of study
</ResponseField>

<ResponseField name="data.candidates[].responses" type="object">
  Candidate's answers to job application questions
</ResponseField>

<ResponseField name="data.candidates[].application_date" type="string">
  Date and time when the application was submitted
</ResponseField>

<ResponseField name="data.candidates[].contact_email" type="string">
  Candidate's email address
</ResponseField>

<ResponseField name="data.candidates[].contact_phone" type="string">
  Candidate's phone number
</ResponseField>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "status": "success",
    "data": {
      "total_results": 1,
      "candidates": [
        {
          "application_id": "22985735624",
          "rating": "GOOD_FIT",
          "is_top_choice": true,
          "top_choice_message": "Hello,\nI'm very excited about this opportunity and believe my background in digital marketing would be a perfect fit. Please find my resume attached.\nBest regards,\nSarah",
          "first_name": "Sarah",
          "last_name": "Johnson",
          "full_name": "Sarah Johnson",
          "headline": "Digital Marketing Director | SEO | Content Strategy | E-commerce",
          "public_identifier": "sarahjohnsondigital",
          "profile_url": "https://www.linkedin.com/in/sarahjohnsondigital",
          "location": "London, United Kingdom",
          "experiences": [
            {
              "title": "Digital Marketing Director",
              "company": "TechGrowth Solutions",
              "company_url": "https://www.linkedin.com/company/techgrowth-solutions/",
              "date_range": "5/2022 - Present",
              "description": "Leading a team of 12 marketing specialists across SEO, content, and paid acquisition channels. Developed and executed comprehensive marketing strategies that increased organic traffic by 78% and improved conversion rates by 34% within 18 months."
            },
            {
              "title": "Senior Marketing Manager",
              "company": "E-Commerce Innovators",
              "company_url": "https://www.linkedin.com/company/ecommerce-innovators/",
              "date_range": "3/2019 - 5/2022",
              "description": "Managed digital marketing initiatives for B2B SaaS platform. Implemented data-driven marketing strategies that generated 12M in pipeline and contributed to 25% YoY revenue growth."
            }
          ],
          "education": [
            {
              "school": "University of Manchester",
              "school_url": "https://www.linkedin.com/school/university-of-manchester/",
              "degree": "Master's degree, Digital Marketing",
              "field": "Marketing",
              "years": "2016 - 2018"
            },
            {
              "school": "King's College London",
              "school_url": "https://www.linkedin.com/school/kings-college-london/",
              "degree": "Bachelor's degree, Business Administration",
              "field": "Marketing and Communications",
              "years": "2012 - 2016"
            }
          ],
          "responses": {
            "Do you have experience with SEO and SEM strategies?": "Yes, I have 8+ years of experience developing and implementing SEO/SEM strategies for e-commerce and SaaS companies. My recent campaign increased organic traffic by 78% year-over-year.",
            "Are you willing to relocate?": "Yes, I'm open to relocation opportunities."
          },
          "application_date": "2025-04-15 10:27:39",
          "contact_email": "sarah.johnson@example.com",
          "contact_phone": "+44 7700 900123"
        }
      ]
    }
    "pagination": {
        "start_page": 1,
        "end_page": 1,
        "results_per_page": 10,
        "pages_fetched": 1
      }
  }
  ```
</ResponseExample>