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

# Candidate Profiles

> Read candidate profiles and their saved jobs, with gated sensitive PII

## Overview

Candidate profiles are organization-scoped, read-only records of a candidate's preferences and (optionally) sensitive personal information. By default, only a non-sensitive **safe subset** is returned. Sensitive fields require **both** the `sensitive_pii` scope on your API key **and** the `?includeSensitive=true` query parameter.

<Warning>
  Sensitive fields are returned only when **both** conditions are met:
  the API key has the `sensitive_pii` scope **and** the request includes
  `?includeSensitive=true`. Requesting `?includeSensitive=true` with a key that
  lacks the scope returns **403**. Profiles are organization-scoped — a profile
  not associated with your key's organization returns **404**.
</Warning>

## Field Visibility

| Visibility                                                   | Fields                                                                                                                                                                                                     |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Safe subset** (any `gather` key)                           | `id`, `firstName`, `lastName`, `preferences`, `jobObjectives`, `jobPreferenceSummary`, `jobPreferenceSummaryStatus`, `jobPreferenceSummaryUpdatedAt`, `createdAt`, `updatedAt`, `archivedAt`               |
| **Gated** (`sensitive_pii` scope + `?includeSensitive=true`) | `email`, `phone`, `linkedinUrl`, `portfolioUrl`, `locationAddress`, `locationCoordinates`, `resumeText`, `resumeUrl`, `resumeTitle`, `workAuthorization`, `hourlyWageExpectation`, `knowYourWorthEstimate` |

### Gating truth table

| `?includeSensitive=true` | key has `sensitive_pii` | Result                |
| ------------------------ | ----------------------- | --------------------- |
| yes                      | yes                     | gated fields included |
| yes                      | no                      | **403 Forbidden**     |
| no                       | yes                     | safe subset           |
| no                       | no                      | safe subset           |

## Get Candidate Profile

Retrieve a candidate profile. Returns the safe subset unless sensitive access is granted.

**Endpoint:** `GET /qsi/gather/candidate-profiles/{candidateProfileId}`

<ParamField path="candidateProfileId" type="string" required>
  UUID of the candidate profile
</ParamField>

<ParamField query="includeSensitive" type="boolean">
  Request sensitive fields. Requires the `sensitive_pii` scope; otherwise returns 403.
</ParamField>

<CodeGroup>
  ```json Response (safe subset) theme={null}
  {
    "data": {
      "candidateProfile": {
        "id": "cp-uuid",
        "firstName": "Jane",
        "lastName": "Doe",
        "preferences": { "remote": true },
        "jobObjectives": ["Senior Engineer"],
        "jobPreferenceSummary": "Looking for remote backend roles",
        "jobPreferenceSummaryStatus": "ready",
        "jobPreferenceSummaryUpdatedAt": "2026-01-02T00:00:00Z",
        "createdAt": "2026-01-01T00:00:00Z",
        "updatedAt": "2026-01-02T00:00:00Z"
      }
    },
    "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
  }
  ```

  ```json Response (?includeSensitive=true, scoped key) theme={null}
  {
    "data": {
      "candidateProfile": {
        "id": "cp-uuid",
        "firstName": "Jane",
        "lastName": "Doe",
        "preferences": { "remote": true },
        "jobObjectives": ["Senior Engineer"],
        "jobPreferenceSummary": "Looking for remote backend roles",
        "jobPreferenceSummaryStatus": "ready",
        "jobPreferenceSummaryUpdatedAt": "2026-01-02T00:00:00Z",
        "email": "jane@example.com",
        "phone": "+15555550123",
        "linkedinUrl": "https://linkedin.com/in/jane",
        "portfolioUrl": "https://jane.dev",
        "locationAddress": "1 Main St, Anytown",
        "locationCoordinates": { "lat": 40.7, "lng": -74.0 },
        "resumeText": "…full resume text…",
        "resumeUrl": "https://files.example.com/resume.pdf",
        "resumeTitle": "jane_doe_resume.pdf",
        "workAuthorization": "US Citizen",
        "hourlyWageExpectation": 55,
        "knowYourWorthEstimate": "$110k–$130k",
        "createdAt": "2026-01-01T00:00:00Z",
        "updatedAt": "2026-01-02T00:00:00Z"
      }
    },
    "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
  }
  ```

  ```json Response (?includeSensitive=true, non-scoped key) theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "message": "API credential is missing required permission: sensitive_pii",
      "details": { "required": "sensitive_pii" }
    },
    "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
  }
  ```
</CodeGroup>

## List Saved Jobs

List the jobs a candidate has saved (page paginated, newest first).

**Endpoint:** `GET /qsi/gather/candidate-profiles/{candidateProfileId}/saved-jobs`

<ParamField path="candidateProfileId" type="string" required>
  UUID of the candidate profile
</ParamField>

<ParamField query="page" type="number">
  Page number (default: 1)
</ParamField>

<ParamField query="pageSize" type="number">
  Items per page (default: 50)
</ParamField>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "savedJobs": [
        {
          "id": "sj-uuid",
          "jobId": "job-uuid",
          "candidateProfileId": "cp-uuid",
          "savedAt": "2026-01-01T00:00:00Z",
          "notes": "Great fit",
          "organizationId": "org-uuid",
          "teamId": "team-uuid",
          "createdAt": "2026-01-01T00:00:00Z",
          "updatedAt": "2026-01-01T00:00:00Z"
        }
      ],
      "pagination": { "total": 4, "page": 1, "totalPages": 1, "pageSize": 50 }
    },
    "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
  }
  ```
</CodeGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Conversations" icon="comments" href="/api-reference/conversations">
    Read chatbot conversations and messages
  </Card>

  <Card title="Chatbots" icon="robot" href="/api-reference/chatbots">
    Manage chatbots and configuration
  </Card>
</CardGroup>