# Candidates

> The people you're considering, one per person across all your jobs, with their resumes. Part of the HireHappy API reference (https://hirehappy.io/docs/api).

Base URL: `https://api.hirehappy.io/v1`. Authenticate with `Authorization: Bearer <API key>`.

### List candidates

`GET https://api.hirehappy.io/v1/candidates`

Scope: `candidates:read`

Newest first. `q` matches part of the name or email.

**Query parameters**

| Name | Type | Description |
| --- | --- | --- |
| `q` | string | Matches part of the name or email. |
| `limit` | integer | How many to return. min 1, max 100, default `50` |
| `offset` | integer | How many to skip. See [Pagination](https://hirehappy.io/docs/pagination). default `0` |

**Example request**

```bash
curl "https://api.hirehappy.io/v1/candidates?q=ribeiro" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"
```

**Response** `200` (a page: `items`, `total`, `limit`, `offset`)

| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `created_at` | datetime |  |
| `updated_at` | datetime | nullable |
| `first_name` | string |  |
| `last_name` | string |  |
| `email` | string | Unique within the organization. nullable |
| `phone` | string | nullable |
| `location` | string | nullable |
| `linkedin_url` | string | nullable |
| `source` | string | Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...). nullable |
| `resume_url` | string | Their resume (PDF); null when there's none. nullable |

```json
{
  "items": [
    {
      "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
      "created_at": "2026-10-26T09:30:00Z",
      "updated_at": "2026-10-27T14:05:00Z",
      "first_name": "Ana",
      "last_name": "Ribeiro",
      "email": "ana.ribeiro@example.com",
      "phone": "+49 30 901820",
      "location": "Lisbon, Portugal",
      "linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
      "source": "referral",
      "resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

**Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed candidates:read; `422` a parameter or field doesn't validate.

### Create a candidate

`POST https://api.hirehappy.io/v1/candidates`

Scope: `candidates:write`

Add a candidate, to put forward for a job with POST /applications. 409 when another candidate has the email.

**Request body** (application/json)

| Name | Type | Description |
| --- | --- | --- |
| `first_name` | string | required, min 1 chars, max 100 chars |
| `last_name` | string | required, min 1 chars, max 100 chars |
| `email` | email | 409 when another candidate has it. nullable |
| `phone` | string | nullable, max 50 chars |
| `location` | string | nullable, max 200 chars |
| `linkedin_url` | string | nullable, max 500 chars |
| `source` | string | Where they came from, in your own words: referral, linkedin, agency, ... nullable, max 100 chars |

**Example request**

```bash
curl -X POST "https://api.hirehappy.io/v1/candidates" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ana",
    "last_name": "Ribeiro",
    "email": "ana.ribeiro@example.com",
    "linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
    "source": "referral"
  }'
```

**Response** `201`

| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `created_at` | datetime |  |
| `updated_at` | datetime | nullable |
| `first_name` | string |  |
| `last_name` | string |  |
| `email` | string | Unique within the organization. nullable |
| `phone` | string | nullable |
| `location` | string | nullable |
| `linkedin_url` | string | nullable |
| `source` | string | Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...). nullable |
| `resume_url` | string | Their resume (PDF); null when there's none. nullable |

```json
{
  "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
  "created_at": "2026-10-26T09:30:00Z",
  "updated_at": "2026-10-27T14:05:00Z",
  "first_name": "Ana",
  "last_name": "Ribeiro",
  "email": "ana.ribeiro@example.com",
  "phone": "+49 30 901820",
  "location": "Lisbon, Portugal",
  "linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
  "source": "referral",
  "resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}
```

**Errors**: `400` a value is out of place; `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed candidates:write; `409` when another candidate has the email; `422` a parameter or field doesn't validate.

### Retrieve a candidate

`GET https://api.hirehappy.io/v1/candidates/{candidate_id}`

Scope: `candidates:read`



**Path parameters**

| Name | Type | Description |
| --- | --- | --- |
| `candidate_id` | uuid | required |

**Example request**

```bash
curl "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"
```

**Response** `200`

| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `created_at` | datetime |  |
| `updated_at` | datetime | nullable |
| `first_name` | string |  |
| `last_name` | string |  |
| `email` | string | Unique within the organization. nullable |
| `phone` | string | nullable |
| `location` | string | nullable |
| `linkedin_url` | string | nullable |
| `source` | string | Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...). nullable |
| `resume_url` | string | Their resume (PDF); null when there's none. nullable |

```json
{
  "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
  "created_at": "2026-10-26T09:30:00Z",
  "updated_at": "2026-10-27T14:05:00Z",
  "first_name": "Ana",
  "last_name": "Ribeiro",
  "email": "ana.ribeiro@example.com",
  "phone": "+49 30 901820",
  "location": "Lisbon, Portugal",
  "linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
  "source": "referral",
  "resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}
```

**Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed candidates:read; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.

### Update a candidate

`PATCH https://api.hirehappy.io/v1/candidates/{candidate_id}`

Scope: `candidates:write`



**Path parameters**

| Name | Type | Description |
| --- | --- | --- |
| `candidate_id` | uuid | required |

**Request body** (application/json)

| Name | Type | Description |
| --- | --- | --- |
| `first_name` | string | nullable, min 1 chars, max 100 chars |
| `last_name` | string | nullable, min 1 chars, max 100 chars |
| `email` | email | nullable |
| `phone` | string | nullable, max 50 chars |
| `location` | string | nullable, max 200 chars |
| `linkedin_url` | string | nullable, max 500 chars |
| `source` | string | nullable, max 100 chars |

**Example request**

```bash
curl -X PATCH "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+49 30 901820",
    "location": "Lisbon, Portugal"
  }'
```

**Response** `200`

| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `created_at` | datetime |  |
| `updated_at` | datetime | nullable |
| `first_name` | string |  |
| `last_name` | string |  |
| `email` | string | Unique within the organization. nullable |
| `phone` | string | nullable |
| `location` | string | nullable |
| `linkedin_url` | string | nullable |
| `source` | string | Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...). nullable |
| `resume_url` | string | Their resume (PDF); null when there's none. nullable |

```json
{
  "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
  "created_at": "2026-10-26T09:30:00Z",
  "updated_at": "2026-10-27T14:05:00Z",
  "first_name": "Ana",
  "last_name": "Ribeiro",
  "email": "ana.ribeiro@example.com",
  "phone": "+49 30 901820",
  "location": "Lisbon, Portugal",
  "linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
  "source": "referral",
  "resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}
```

**Errors**: `400` a value is out of place; `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed candidates:write; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.

### Delete a candidate

`DELETE https://api.hirehappy.io/v1/candidates/{candidate_id}`

Scope: `candidates:write`

Delete a candidate for good, with their applications and notes (a request to erase their data, say).

**Path parameters**

| Name | Type | Description |
| --- | --- | --- |
| `candidate_id` | uuid | required |

**Example request**

```bash
curl -X DELETE "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"
```

**Response** `204` with no body.

**Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed candidates:write; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.

### Upload a candidate's resume

`PUT https://api.hirehappy.io/v1/candidates/{candidate_id}/resume`

Scope: `candidates:write`

Set the candidate's resume, a PDF sent as multipart/form-data (`resume`), replacing any they had. It's searchable at once; scorecards use it from the next scoring on.

**Path parameters**

| Name | Type | Description |
| --- | --- | --- |
| `candidate_id` | uuid | required |

**Request body** (multipart/form-data)

| Name | Type | Description |
| --- | --- | --- |
| `resume` | string | required |

**Example request**

```bash
curl -X PUT "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f/resume" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY" \
  -F "resume=@resume.pdf;type=application/pdf"
```

**Response** `200`

| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `created_at` | datetime |  |
| `updated_at` | datetime | nullable |
| `first_name` | string |  |
| `last_name` | string |  |
| `email` | string | Unique within the organization. nullable |
| `phone` | string | nullable |
| `location` | string | nullable |
| `linkedin_url` | string | nullable |
| `source` | string | Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...). nullable |
| `resume_url` | string | Their resume (PDF); null when there's none. nullable |

```json
{
  "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
  "created_at": "2026-10-26T09:30:00Z",
  "updated_at": "2026-10-27T14:05:00Z",
  "first_name": "Ana",
  "last_name": "Ribeiro",
  "email": "ana.ribeiro@example.com",
  "phone": "+49 30 901820",
  "location": "Lisbon, Portugal",
  "linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
  "source": "referral",
  "resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}
```

**Errors**: `400` a value is out of place; `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed candidates:write; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.
