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 -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": "[email protected]",
"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: '[email protected]',
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': '[email protected]',
'phone': '+1234567890'
}
)
candidate = response.json()
{
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"phone": "+1234567890",
"externalId": "candidate-123",
"timezone": "America/New_York",
"smsOptIn": true
}
Get Candidate
Retrieve candidate details.
Endpoint: GET /qsi/gather/candidates/{candidateId}
{
"data": {
"id": "uuid",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"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
Items per page (default: 10, max: 100)
Include archived candidates (default: false)
{
"data": {
"candidates": [
{
"id": "uuid",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"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}
UUID of the candidate to update
Delete Candidate
Archive a candidate.
Endpoint: DELETE /qsi/gather/candidates/{candidateId}
UUID of the candidate to archive
{
"data": {
"id": "uuid",
"archivedAt": "2024-01-01T00:00:00Z"
},
"meta": {
"requestId": "uuid",
"timestamp": "2024-01-01T00:00:00Z"
}
}
- ✅
+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
