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

# GET /candidates/search — Search the Cutshort Talent Pool

> Search 4M+ Indian tech professionals by skills, experience, location, salary expectation, availability, and AI quality score. Returns paginated results.

Use this endpoint to query the Cutshort talent pool with fine-grained filters. You can combine skill requirements, experience range, location preferences, salary caps, and AI quality scores to surface the most relevant candidates.

## Endpoint

```http theme={null}
GET https://api.cutshort.io/v1/candidates/search
```

## Query Parameters

<ParamField query="skills" type="string" required>
  Comma-separated list of skill names. Case-insensitive. Example: `python,django,postgresql`
</ParamField>

<ParamField query="experience_min" type="integer">
  Minimum years of professional experience.
</ParamField>

<ParamField query="experience_max" type="integer">
  Maximum years of experience.
</ParamField>

<ParamField query="location" type="string">
  City name (e.g., `Bengaluru`, `Mumbai`, `Pune`) or `Remote`.
</ParamField>

<ParamField query="remote_only" type="boolean">
  When `true`, only returns candidates open to remote roles.
</ParamField>

<ParamField query="salary_max" type="integer">
  Maximum salary expectation in INR (annual). Filters out candidates expecting more.
</ParamField>

<ParamField query="quality_score_min" type="integer">
  Minimum AI quality score, on a scale of 0–100. Recommended: 65–70 for a good signal.
</ParamField>

<ParamField query="availability" type="string">
  Comma-separated availability statuses: `active`, `open`, `not_looking`. Returns all statuses if omitted.
</ParamField>

<ParamField query="page" type="integer">
  Page number for paginated results. Default: `1`.
</ParamField>

<ParamField query="per_page" type="integer">
  Number of results per page. Maximum: `50`. Default: `20`.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.cutshort.io/v1/candidates/search?skills=python,fastapi&experience_min=4&location=Bengaluru&quality_score_min=70' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.cutshort.io/v1/candidates/search",
      params={
          "skills": "python,fastapi",
          "experience_min": 4,
          "location": "Bengaluru",
          "quality_score_min": 70
      },
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  data = response.json()
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    skills: 'python,fastapi',
    experience_min: '4',
    location: 'Bengaluru',
    quality_score_min: '70'
  });

  const response = await fetch(
    `https://api.cutshort.io/v1/candidates/search?${params}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
  const data = await response.json();
  ```
</CodeGroup>

## Response

Returns `200 OK` with a paginated list of matching candidate summary objects.

```json theme={null}
{
  "total": 284,
  "page": 1,
  "per_page": 20,
  "data": [
    {
      "id": "cand_8f3kL9mN",
      "name": "Priya Menon",
      "headline": "Senior Python Engineer",
      "location": "Bengaluru",
      "experience_years": 5,
      "skills": ["Python", "FastAPI", "PostgreSQL", "Docker"],
      "quality_score": 82,
      "availability": "active",
      "salary_expectation_min": 2000000,
      "salary_expectation_max": 2800000,
      "profile_url": "https://cutshort.io/candidate/priya-menon"
    }
  ]
}
```

### Response Fields

<ResponseField name="total" type="integer">
  Total number of matching candidates across all pages.
</ResponseField>

<ResponseField name="page" type="integer">
  The current page number.
</ResponseField>

<ResponseField name="per_page" type="integer">
  Number of results returned per page.
</ResponseField>

<ResponseField name="data" type="array">
  List of candidate summary objects matching your query.
</ResponseField>

<ResponseField name="data[].id" type="string">
  Unique Cutshort candidate ID (e.g., `cand_8f3kL9mN`).
</ResponseField>

<ResponseField name="data[].name" type="string">
  The candidate's full name.
</ResponseField>

<ResponseField name="data[].headline" type="string">
  The candidate's professional headline or current role title (e.g., `Senior Python Engineer`).
</ResponseField>

<ResponseField name="data[].experience_years" type="integer">
  Total years of professional experience.
</ResponseField>

<ResponseField name="data[].skills" type="array">
  List of skill name strings associated with the candidate's profile.
</ResponseField>

<ResponseField name="data[].salary_expectation_min" type="integer">
  Minimum expected annual salary in INR.
</ResponseField>

<ResponseField name="data[].salary_expectation_max" type="integer">
  Maximum expected annual salary in INR.
</ResponseField>

<ResponseField name="data[].quality_score" type="integer">
  AI-generated quality score from 0 to 100. Higher scores indicate stronger candidate fit.
</ResponseField>

<ResponseField name="data[].availability" type="string">
  The candidate's current job-search availability. One of `active`, `open`, or `not_looking`.
</ResponseField>

<ResponseField name="data[].profile_url" type="string">
  Direct URL to the candidate's full Cutshort profile.
</ResponseField>