> ## 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.

# Search Candidates by Skills, Experience, and Location

> Use the Cutshort API to search 4M+ Indian tech professionals by skills, experience, location, salary expectations, and AI quality score.

The candidate search endpoint is your primary way to discover engineers in Cutshort's talent pool. You can filter by any combination of skills, years of experience, location, salary expectation, availability, and AI quality score. Results are paginated and sorted by match relevance.

## Basic search

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

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

  response = requests.get(
      "https://api.cutshort.io/v1/candidates/search",
      params={
          "skills": "react,nodejs",
          "experience_min": 3,
          "location": "Bengaluru"
      },
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  data = response.json()
  print(f"{data['total']} candidates found")
  ```
</CodeGroup>

## Available search filters

| Parameter           | Type                     | Description                                       |
| ------------------- | ------------------------ | ------------------------------------------------- |
| `skills`            | string (comma-separated) | Required skills (e.g., `python,django,aws`)       |
| `experience_min`    | integer                  | Minimum years of experience                       |
| `experience_max`    | integer                  | Maximum years of experience                       |
| `location`          | string                   | City name (e.g., `Bengaluru`, `Mumbai`, `Remote`) |
| `remote_only`       | boolean                  | Set `true` to show only remote-open candidates    |
| `salary_max`        | integer                  | Maximum salary expectation in INR (annual)        |
| `quality_score_min` | integer (0–100)          | Minimum AI quality score                          |
| `availability`      | string                   | One of `active`, `open`, or `active,open`         |
| `page`              | integer                  | Page number (default: 1)                          |
| `per_page`          | integer                  | Results per page (max: 50, default: 20)           |

## Response example

```json theme={null}
{
  "total": 412,
  "page": 1,
  "per_page": 20,
  "data": [
    {
      "id": "cand_8f3kL9mN",
      "name": "Priya Menon",
      "headline": "Senior React Developer",
      "location": "Bengaluru",
      "experience_years": 5,
      "skills": ["React", "Node.js", "TypeScript"],
      "quality_score": 84,
      "availability": "active",
      "salary_expectation_min": 1800000,
      "salary_expectation_max": 2400000,
      "profile_url": "https://cutshort.io/candidate/priya-menon"
    }
  ]
}
```

## Filtering by quality score

The `quality_score_min` parameter filters candidates by Cutshort's AI-computed quality score, which evaluates profile completeness, skill depth, career trajectory, and engagement signals. Scores range from 0 to 100.

<Tip>
  Use `quality_score_min=70` for a strong signal-to-noise ratio. Use `quality_score_min=85` for senior or leadership roles.
</Tip>

## Pagination

Use the `page` and `per_page` parameters to navigate through large result sets. The `total` field in the response tells you the full count of matching candidates. Each page returns up to 50 results.

To iterate through all pages, increment `page` until you have collected `total` records:

```python theme={null}
import requests

all_candidates = []
page = 1

while True:
    response = requests.get(
        "https://api.cutshort.io/v1/candidates/search",
        params={
            "skills": "python,django",
            "experience_min": 3,
            "page": page,
            "per_page": 50
        },
        headers={"Authorization": "Bearer YOUR_API_KEY"}
    )
    data = response.json()
    all_candidates.extend(data["data"])

    if len(all_candidates) >= data["total"]:
        break

    page += 1

print(f"Fetched {len(all_candidates)} candidates in total")
```

## Best practices

<Note>
  Prefer specific skill names (e.g., `react` not `frontend`). Combine `availability=active,open` with `quality_score_min=65` for best response rates.
</Note>