---
title: "Search candidates"
method: GET
path: "/api/public/v1/candidates/search"
tags: ["Public API v1 — Candidates", "Public API v1 — Candidates"]
---

# Search candidates

`GET /api/public/v1/candidates/search`

## Request

- Base URL: `https://api.thebetterhire.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.thebetterhire.ai/api/public/v1/candidates/search`
- Auth: HTTP bearer

Search for existing candidates by name or email. Returns matching candidates with interview history and scores. Use this before scheduling to check if a candidate already exists.

## Query parameters

- `name` string, nullable: Search by candidate name (partial, case-insensitive).
- `email` string, nullable: Search by email (partial, case-insensitive).
- `limit` integer: Max results.

## Response `200`

Successful Response

- CandidateSearchResponse
  - `candidates` CandidateSearchResult[], required
    - `candidate_id` string, required
    - `name` string, required
    - `email` string, nullable
    - `phone` string, nullable
    - `source` string, nullable
    - `interviews` InterviewSummary[]
      - `interview_id` string, required
      - `role` string, required
      - `score` integer, nullable
      - `recommendation` string, nullable
      - `status` string, required
      - `created_at` string, required
    - `interview_count` integer
    - `latest_score` integer, nullable
    - `latest_recommendation` string, nullable
  - `total` integer, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api.md) · [All operations](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api/revisions/c8ad03e900ea?raw)