Find Recommended Candidates - Harmony AI Agents

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
}

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

jobId

integer

required

ID of the job to find candidates for

Body Parameters

location

object

Location requirements for candidates

Show Location Object

zipCode

string

ZIP/Postal code of the job

radius

integer

default:"25"

Maximum distance for candidates in miles

states

array

List of acceptable state codes for licensure (e.g., [“CA”, “OR”, “WA”])

requireLocalCandidates

boolean

Only show candidates within specified radius

specialties

array

Required specialties (e.g., [“icu”, “er”, “pediatrics”])

replaceCriteria

boolean

default:"false"

If true, provided criteria replace job criteria. If false, they are added to job criteria.

criteria

array

Additional screening criteria

Show Criteria Object

description

string

required

Full description of the requirement (e.g., “Must have 2 years of ICU nursing experience”)

importance

string

required

One of: “required”, “preferred”, “optional”

type

string

required

Type of criterion (e.g., “specialty”, “certification”, “experience”)

minScore

number

default:"60"

Minimum match score (0-100)

limit

integer

default:"20"

Maximum number of candidates to return

offset

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

candidates

array

Array of matching candidates with screening results

Show Candidate Object

integer

Unique identifier for the candidate

location

object

Candidate’s location information

Show Location Object

city

string

City name

state

string

State code (e.g., “CA”)

zipCode

string

ZIP/Postal code

distance

number

Distance from job location in miles

screening

object

Screening results for this candidate

Show Screening Object

currentScore

number

Current match percentage based on verified criteria (0-100)

potentialScore

number

Maximum possible match percentage if all unverified criteria are met (0-100)

disqualify

boolean

Whether the candidate should be disqualified from the job

summary

object

Show Summary Object

screeningSummary

string

Overall assessment of the candidate’s fit for the position

followUpQuestions

array

Questions to ask the candidate about unverified or unclear criteria

missingInformation

array

List of criteria that couldn’t be verified from available information

strengths

array

List of criteria where the candidate shows strong matches

gaps

array

List of areas where the candidate doesn’t meet requirements

questions

array

Show Question Object

integer

Unique identifier for the criterion

source

string

Origin of the criterion (e.g., “job_criteria”)

question

string

The criterion formatted as a question

criteria

string

Original criterion text

type

string

Type of criterion (e.g., “YearsOfExperience”, “Required”, “Preferred”)

status

string

Match status: “FullyMet”, “PartiallyMet”, or “NotMet”

reasoning

string

Explanation of how the criterion was evaluated

textEvidence

string

Supporting text from resume/application, if found

qualificationLevel

string

Overall qualification assessment (e.g., “Appropriate”, “Overqualified”, “Underqualified”)

isRelevant

boolean

Indicates if the candidate’s background is relevant to the position

total

integer

Total number of matching candidates found

limit

integer

Maximum number of candidates returned

offset

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
}

Find Recommended Jobs Parse Resume

​Query Parameters

​Body Parameters

​Response Fields

Query Parameters

Body Parameters

Response Fields