> ## Documentation Index
> Fetch the complete documentation index at: https://docs.harmonyforstaffing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Find Recommended Candidates

> Find candidates that match a job's requirements and preferences

Find and screen candidates that match a job's requirements. Results are automatically screened and ranked by match percentage.

### Query Parameters

<ParamField query="jobId" type="integer" required>
  ID of the job to find candidates for
</ParamField>

### Body Parameters

<ParamField body="location" type="object">
  Location requirements for candidates

  <Expandable title="Location Object">
    <ParamField body="zipCode" type="string">
      ZIP/Postal code of the job
    </ParamField>

    <ParamField body="radius" type="integer" default="25">
      Maximum distance for candidates in miles
    </ParamField>

    <ParamField body="states" type="array">
      List of acceptable state codes for licensure (e.g., \["CA", "OR", "WA"])
    </ParamField>

    <ParamField body="requireLocalCandidates" type="boolean">
      Only show candidates within specified radius
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="specialties" type="array">
  Required specialties (e.g., \["icu", "er", "pediatrics"])
</ParamField>

<ParamField body="replaceCriteria" type="boolean" default="false">
  If true, provided criteria replace job criteria. If false, they are added to job criteria.
</ParamField>

<ParamField body="criteria" type="array">
  Additional screening criteria

  <Expandable title="Criteria Object">
    <ParamField body="description" type="string" required>
      Full description of the requirement (e.g., "Must have 2 years of ICU nursing experience")
    </ParamField>

    <ParamField body="importance" type="string" required>
      One of: "required", "preferred", "optional"
    </ParamField>

    <ParamField body="type" type="string" required>
      Type of criterion (e.g., "specialty", "certification", "experience")
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="minScore" type="number" default="60">
  Minimum match score (0-100)
</ParamField>

<ParamField body="limit" type="integer" default="20">
  Maximum number of candidates to return
</ParamField>

<ParamField body="offset" type="integer" default="0">
  Number of candidates to skip for pagination
</ParamField>

<RequestExample>
  ```bash theme={null}
  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
    }'
  ```
</RequestExample>

### Response Fields

<ResponseField name="candidates" type="array">
  Array of matching candidates with screening results

  <Expandable title="Candidate Object">
    <ResponseField name="id" type="integer">
      Unique identifier for the candidate
    </ResponseField>

    <ResponseField name="location" type="object">
      Candidate's location information

      <Expandable title="Location Object">
        <ResponseField name="city" type="string">
          City name
        </ResponseField>

        <ResponseField name="state" type="string">
          State code (e.g., "CA")
        </ResponseField>

        <ResponseField name="zipCode" type="string">
          ZIP/Postal code
        </ResponseField>

        <ResponseField name="distance" type="number">
          Distance from job location in miles
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="screening" type="object">
      Screening results for this candidate

      <Expandable title="Screening Object">
        <ResponseField name="currentScore" type="number">
          Current match percentage based on verified criteria (0-100)
        </ResponseField>

        <ResponseField name="potentialScore" type="number">
          Maximum possible match percentage if all unverified criteria are met (0-100)
        </ResponseField>

        <ResponseField name="disqualify" type="boolean">
          Whether the candidate should be disqualified from the job
        </ResponseField>

        <ResponseField name="summary" type="object">
          <Expandable title="Summary Object">
            <ResponseField name="screeningSummary" type="string">
              Overall assessment of the candidate's fit for the position
            </ResponseField>

            <ResponseField name="followUpQuestions" type="array">
              Questions to ask the candidate about unverified or unclear criteria
            </ResponseField>

            <ResponseField name="missingInformation" type="array">
              List of criteria that couldn't be verified from available information
            </ResponseField>

            <ResponseField name="strengths" type="array">
              List of criteria where the candidate shows strong matches
            </ResponseField>

            <ResponseField name="gaps" type="array">
              List of areas where the candidate doesn't meet requirements
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="questions" type="array">
          <Expandable title="Question Object">
            <ResponseField name="id" type="integer">
              Unique identifier for the criterion
            </ResponseField>

            <ResponseField name="source" type="string">
              Origin of the criterion (e.g., "job\_criteria")
            </ResponseField>

            <ResponseField name="question" type="string">
              The criterion formatted as a question
            </ResponseField>

            <ResponseField name="criteria" type="string">
              Original criterion text
            </ResponseField>

            <ResponseField name="type" type="string">
              Type of criterion (e.g., "YearsOfExperience", "Required", "Preferred")
            </ResponseField>

            <ResponseField name="status" type="string">
              Match status: "FullyMet", "PartiallyMet", or "NotMet"
            </ResponseField>

            <ResponseField name="reasoning" type="string">
              Explanation of how the criterion was evaluated
            </ResponseField>

            <ResponseField name="textEvidence" type="string">
              Supporting text from resume/application, if found
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="qualificationLevel" type="string">
      Overall qualification assessment (e.g., "Appropriate", "Overqualified", "Underqualified")
    </ResponseField>

    <ResponseField name="isRelevant" type="boolean">
      Indicates if the candidate's background is relevant to the position
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of matching candidates found
</ResponseField>

<ResponseField name="limit" type="integer">
  Maximum number of candidates returned
</ResponseField>

<ResponseField name="offset" type="integer">
  Number of candidates skipped
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "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
  }
  ```
</ResponseExample>