curl --request GET \
--url 'https://api.harmonyforstaffing.com/api/matching/candidates?jobId=123' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"location": {
"zipCode": "94143",
"radius": 25,
"states": ["CA"],
"requireLocalCandidates": true
},
"specialties": ["icu", "er"],
"criteria": [
{
"description": "Must have 2 years of ICU nursing experience",
"importance": "required",
"type": "experience"
},
{
"description": "Current ACLS certification required",
"importance": "required",
"type": "certification"
}
],
"replaceCriteria": false,
"minScore": 70
}'
{
"candidates": [
{
"id": 456,
"location": {
"city": "San Francisco",
"state": "CA",
"zipCode": "94143",
"distance": 5.2
},
"screening": {
"currentScore": 85.5,
"potentialScore": 100,
"disqualify": false,
"summary": {
"screeningSummary": "Strong candidate with extensive ICU experience...",
"followUpQuestions": [
"Are you comfortable with rotating shifts?",
"Can you start by June 1st?"
],
"strengths": [
"Exceeds experience requirements",
"All required certifications current",
"Local candidate within 10 miles"
],
"gaps": [
"No recent pediatric experience"
]
},
"questions": [
{
"id": 1,
"source": "job_criteria",
"question": "How many years of ICU nursing experience do you have?",
"criteria": "Minimum of 2 years ICU nursing experience required",
"type": "YearsOfExperience",
"status": "FullyMet",
"reasoning": "The candidate has 5 years of ICU experience...",
"textEvidence": "5 years of experience in Medical ICU at Saint Francis Hospital"
}
]
},
"qualificationLevel": "Appropriate",
"isRelevant": true
}
],
"total": 12,
"limit": 20,
"offset": 0
}
Matching
Find Recommended Candidates
Find candidates that match a job’s requirements and preferences
GET
/
api
/
matching
/
candidates
curl --request GET \
--url 'https://api.harmonyforstaffing.com/api/matching/candidates?jobId=123' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"location": {
"zipCode": "94143",
"radius": 25,
"states": ["CA"],
"requireLocalCandidates": true
},
"specialties": ["icu", "er"],
"criteria": [
{
"description": "Must have 2 years of ICU nursing experience",
"importance": "required",
"type": "experience"
},
{
"description": "Current ACLS certification required",
"importance": "required",
"type": "certification"
}
],
"replaceCriteria": false,
"minScore": 70
}'
{
"candidates": [
{
"id": 456,
"location": {
"city": "San Francisco",
"state": "CA",
"zipCode": "94143",
"distance": 5.2
},
"screening": {
"currentScore": 85.5,
"potentialScore": 100,
"disqualify": false,
"summary": {
"screeningSummary": "Strong candidate with extensive ICU experience...",
"followUpQuestions": [
"Are you comfortable with rotating shifts?",
"Can you start by June 1st?"
],
"strengths": [
"Exceeds experience requirements",
"All required certifications current",
"Local candidate within 10 miles"
],
"gaps": [
"No recent pediatric experience"
]
},
"questions": [
{
"id": 1,
"source": "job_criteria",
"question": "How many years of ICU nursing experience do you have?",
"criteria": "Minimum of 2 years ICU nursing experience required",
"type": "YearsOfExperience",
"status": "FullyMet",
"reasoning": "The candidate has 5 years of ICU experience...",
"textEvidence": "5 years of experience in Medical ICU at Saint Francis Hospital"
}
]
},
"qualificationLevel": "Appropriate",
"isRelevant": true
}
],
"total": 12,
"limit": 20,
"offset": 0
}
Find and screen candidates that match a job’s requirements. Results are automatically screened and ranked by match percentage.
Query Parameters
integer
required
ID of the job to find candidates for
Body Parameters
object
array
Required specialties (e.g., [“icu”, “er”, “pediatrics”])
boolean
default:"false"
If true, provided criteria replace job criteria. If false, they are added to job criteria.
array
number
default:"60"
Minimum match score (0-100)
integer
default:"20"
Maximum number of candidates to return
integer
default:"0"
Number of candidates to skip for pagination
curl --request GET \
--url 'https://api.harmonyforstaffing.com/api/matching/candidates?jobId=123' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"location": {
"zipCode": "94143",
"radius": 25,
"states": ["CA"],
"requireLocalCandidates": true
},
"specialties": ["icu", "er"],
"criteria": [
{
"description": "Must have 2 years of ICU nursing experience",
"importance": "required",
"type": "experience"
},
{
"description": "Current ACLS certification required",
"importance": "required",
"type": "certification"
}
],
"replaceCriteria": false,
"minScore": 70
}'
Response Fields
array
Array of matching candidates with screening results
Show Candidate Object
Show Candidate Object
integer
Unique identifier for the candidate
object
object
Screening results for this candidate
Show Screening Object
Show Screening Object
number
Current match percentage based on verified criteria (0-100)
number
Maximum possible match percentage if all unverified criteria are met (0-100)
boolean
Whether the candidate should be disqualified from the job
object
Show Summary Object
Show Summary Object
string
Overall assessment of the candidate’s fit for the position
array
Questions to ask the candidate about unverified or unclear criteria
array
List of criteria that couldn’t be verified from available information
array
List of criteria where the candidate shows strong matches
array
List of areas where the candidate doesn’t meet requirements
array
Show Question Object
Show Question Object
integer
Unique identifier for the criterion
string
Origin of the criterion (e.g., “job_criteria”)
string
The criterion formatted as a question
string
Original criterion text
string
Type of criterion (e.g., “YearsOfExperience”, “Required”, “Preferred”)
string
Match status: “FullyMet”, “PartiallyMet”, or “NotMet”
string
Explanation of how the criterion was evaluated
string
Supporting text from resume/application, if found
string
Overall qualification assessment (e.g., “Appropriate”, “Overqualified”, “Underqualified”)
boolean
Indicates if the candidate’s background is relevant to the position
integer
Total number of matching candidates found
integer
Maximum number of candidates returned
integer
Number of candidates skipped
{
"candidates": [
{
"id": 456,
"location": {
"city": "San Francisco",
"state": "CA",
"zipCode": "94143",
"distance": 5.2
},
"screening": {
"currentScore": 85.5,
"potentialScore": 100,
"disqualify": false,
"summary": {
"screeningSummary": "Strong candidate with extensive ICU experience...",
"followUpQuestions": [
"Are you comfortable with rotating shifts?",
"Can you start by June 1st?"
],
"strengths": [
"Exceeds experience requirements",
"All required certifications current",
"Local candidate within 10 miles"
],
"gaps": [
"No recent pediatric experience"
]
},
"questions": [
{
"id": 1,
"source": "job_criteria",
"question": "How many years of ICU nursing experience do you have?",
"criteria": "Minimum of 2 years ICU nursing experience required",
"type": "YearsOfExperience",
"status": "FullyMet",
"reasoning": "The candidate has 5 years of ICU experience...",
"textEvidence": "5 years of experience in Medical ICU at Saint Francis Hospital"
}
]
},
"qualificationLevel": "Appropriate",
"isRelevant": true
}
],
"total": 12,
"limit": 20,
"offset": 0
}