Get Candidates
Retrieve all candidates who applied to a specific job.
GET /api/integrations/job/{externalJobId}/candidatesPath Parameters
| Parameter | Description |
|---|---|
externalJobId | The job ID you provided when creating the job |
Headers
| Header | Required | Description |
|---|---|---|
x-api-key | Yes | Your API key |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
since | string | — | ISO 8601 date. Only return applications created after this date. Alias for from. |
from | string | — | ISO 8601 date. Only return applications created on or after this date. If both since and from are provided, since takes priority. |
to | string | — | ISO 8601 date. Only return applications created on or before this date. Combine with since/from for a date range. |
page | integer | 1 | Page number (1-based). |
pageSize | integer | 50 | Number of results per page. Maximum 100. |
Response
Success — 200
{
"candidates": [
{
"id": "456",
"jobBoardId": "1",
"status": "PENDING",
"companyId": "100",
"firstName": "Ahmed",
"lastName": "Bennani",
"email": "ahmed@example.com",
"phone": "+212600000000",
"cv": "https://storage.jobzyn.com/resumes/abc123.pdf",
"linkedinUrl": "https://linkedin.com/in/ahmed-bennani",
"offerId": "REQ-2024-001",
"date": "2024-06-15T10:30:00.000Z",
"message": "I am very interested in this position..."
}
],
"total": 1,
"error": null
}Candidate Fields
| Field | Type | Description |
|---|---|---|
id | string | Application ID in Jobzyn |
firstName | string | Candidate’s first name |
lastName | string | Candidate’s last name |
email | string | Candidate’s email address |
phone | string | Candidate’s phone number |
cv | string | URL to the candidate’s resume (PDF) |
linkedinUrl | string | Candidate’s LinkedIn profile URL |
offerId | string | Your original job ID |
date | string | Application date (ISO 8601) |
message | string | Cover message from the candidate |
status | string | Application status |
jobBoardId | string | Job board reference |
companyId | string | Your company ID in Jobzyn |
total | integer | Total number of matching candidates (use with page/pageSize for pagination) |
Invalid Date — 400
{
"candidates": null,
"error": {
"message": "Invalid date format. Use ISO 8601 (e.g. 2024-06-15T00:00:00Z)"
}
}Job Not Found — 403
{
"candidates": null,
"error": {
"message": "External id REQ-2024-001 is not associated with any job within company 100"
}
}Examples
All candidates:
curl https://www.jobzyn.com/api/integrations/job/REQ-2024-001/candidates \
-H "x-api-key: jz_your_api_key_here"Poll for new candidates since a given date:
curl "https://www.jobzyn.com/api/integrations/job/REQ-2024-001/candidates?since=2024-06-14T00:00:00Z" \
-H "x-api-key: jz_your_api_key_here"Date range with pagination:
curl "https://www.jobzyn.com/api/integrations/job/REQ-2024-001/candidates?from=2024-06-01T00:00:00Z&to=2024-06-30T23:59:59Z&page=1&pageSize=25" \
-H "x-api-key: jz_your_api_key_here"Last updated on