Candidate Profiles

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.

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.

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}

string

required

UUID of the candidate profile

boolean

Request sensitive fields. Requires the sensitive_pii scope; otherwise returns 403.

{
  "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" }
}

{
  "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" }
}

{
  "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" }
}

List Saved Jobs

List the jobs a candidate has saved (page paginated, newest first). Endpoint: GET /qsi/gather/candidate-profiles/{candidateProfileId}/saved-jobs

string

required

UUID of the candidate profile

number

Page number (default: 1)

number

Items per page (default: 50)

{
  "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" }
}

Conversations

Read chatbot conversations and messages

Chatbots

Manage chatbots and configuration

Get Started

API Reference

Guides

Code Examples

Resources

Overview

Field Visibility

Gating truth table

Get Candidate Profile

List Saved Jobs

Conversations

Chatbots

​Overview

​Field Visibility

​Gating truth table

​Get Candidate Profile

​List Saved Jobs

​Related Resources

Conversations

Chatbots

Overview

Field Visibility

Gating truth table

Get Candidate Profile

List Saved Jobs

Related Resources