Candidates

Overview

Candidates represent individuals who will be invited to take interviews. You must create candidates before you can send interview invites.

Create Candidate

Create a new candidate. Endpoint: POST /qsi/gather/candidates

cURL
JavaScript
Python

curl -X POST https://api.prod.qualifi.hr/qsi/gather/candidates \
  -H "x-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890"
  }'

const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/candidates', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: 'John',
    lastName: 'Doe',
    email: 'john.doe@example.com',
    phone: '+1234567890'
  })
});
const candidate = await response.json();

response = requests.post(
    'https://api.prod.qualifi.hr/qsi/gather/candidates',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    },
    json={
        'firstName': 'John',
        'lastName': 'Doe',
        'email': 'john.doe@example.com',
        'phone': '+1234567890'
    }
)
candidate = response.json()

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "externalId": "candidate-123",
  "timezone": "America/New_York",
  "smsOptIn": true
}

{
  "data": {
    "id": "uuid",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "createdAt": "2024-01-01T00:00:00Z"
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Get Candidate

Retrieve candidate details. Endpoint: GET /qsi/gather/candidates/{candidateId}

string

required

UUID of the candidate

{
  "data": {
    "id": "uuid",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "resumeUrl": "https://...",
    "externalId": "candidate-123",
    "linkedInURL": "https://linkedin.com/in/johndoe",
    "source": "api",
    "timezone": "America/New_York",
    "smsOptIn": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

List Candidates

List all candidates with pagination and filtering. Endpoint: GET /qsi/gather/candidates

number

Page number (default: 1)

number

Items per page (default: 10, max: 100)

boolean

Include archived candidates (default: false)

string

Search by name or email

string

Filter by external ID

{
  "data": {
    "candidates": [
      {
        "id": "uuid",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "+1234567890",
        "resumeUrl": "https://example.com/resume.pdf",
        "externalId": "ext-123",
        "timezone": "America/New_York",
        "smsOptIn": true,
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "createdById": "user-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "total": 42,
      "page": 1,
      "pages": 5,
      "pageSize": 10
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Update Candidate

Update candidate information. Endpoint: PATCH /qsi/gather/candidates/{candidateId}

string

required

UUID of the candidate to update

{
  "firstName": "Jane",
  "email": "jane.doe@example.com"
}

{
  "data": {
    "id": "uuid",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "updatedAt": "2024-01-01T00:00:00Z"
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Delete Candidate

Archive a candidate. Endpoint: DELETE /qsi/gather/candidates/{candidateId}

string

required

UUID of the candidate to archive

{
  "data": {
    "id": "uuid",
    "archivedAt": "2024-01-01T00:00:00Z"
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Phone Number Format

Phone numbers must be in E.164 format:

✅ +1234567890
❌ 123-456-7890
❌ (123) 456-7890

Ensure phone numbers include country code and are in E.164 format for proper delivery of SMS and phone call invites.

External IDs

Use externalId to maintain references to candidates in your own system:

Helps track candidates across systems
Useful for syncing data between Qualifi and your ATS
Can be used for filtering and searching

Candidate Interviews

Send interview invites to candidates

Sending Invites

Learn how to send interview invites

Get Started

API Reference

Guides

Code Examples

Resources

Overview

Create Candidate

Get Candidate

List Candidates

Update Candidate

Delete Candidate

Phone Number Format

External IDs

Candidate Interviews

Sending Invites

​Overview

​Create Candidate

​Get Candidate

​List Candidates

​Update Candidate

​Delete Candidate

​Phone Number Format

​External IDs

​Related Resources

Candidate Interviews

Sending Invites

Overview

Create Candidate

Get Candidate

List Candidates

Update Candidate

Delete Candidate

Phone Number Format

External IDs

Related Resources