Skip to main content

​
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

VisibilityFields
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=truekey has sensitive_piiResult
yesyesgated fields included
yesno403 Forbidden
noyessafe subset
nonosafe subset

​
Get Candidate Profile

Retrieve a candidate profile. Returns the safe subset unless sensitive access is granted. Endpoint: GET /qsi/gather/candidate-profiles/{candidateProfileId}
​
candidateProfileId
string
required
UUID of the candidate profile
​
includeSensitive
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
​
candidateProfileId
string
required
UUID of the candidate profile
​
page
number
Page number (default: 1)
​
pageSize
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