> ## 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 Jobs

> Find jobs that match a candidate's qualifications and preferences

Find and screen jobs that match a candidate's qualifications and preferences. Results are automatically screened and ranked by match percentage.

### Query Parameters

<ParamField query="candidateId" type="integer" required>
  ID of the candidate to find jobs for
</ParamField>

### Body Parameters

<ParamField query="location" type="object">
  Location preferences for job search

  <Expandable title="Location Object">
    <ParamField query="zipCode" type="string">
      ZIP/Postal code to search from
    </ParamField>

    <ParamField query="radius" type="integer" default="25">
      Search radius in miles
    </ParamField>

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

    <ParamField query="remote" type="boolean">
      Include remote positions
    </ParamField>
  </Expandable>
</ParamField>

<ParamField query="compensation" type="object">
  Compensation requirements

  <Expandable title="Compensation Object">
    <ParamField query="minimum" type="number">
      Minimum annual salary or hourly rate
    </ParamField>

    <ParamField query="type" type="string">
      Pay type: "hourly" or "salary"
    </ParamField>
  </Expandable>
</ParamField>

<ParamField query="schedule" type="object">
  Schedule preferences

  <Expandable title="Schedule Object">
    <ParamField query="availableDate" type="string">
      Date available to start (ISO 8601)
    </ParamField>

    <ParamField query="shifts" type="array">
      Preferred shifts (e.g., \["day", "night", "evening"])
    </ParamField>

    <ParamField query="hoursPerWeek" type="object">
      <ParamField query="minimum" type="integer">
        Minimum hours per week
      </ParamField>

      <ParamField query="maximum" type="integer">
        Maximum hours per week
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField query="jobTypes" type="array">
  Types of positions (e.g., \["full-time", "part-time", "contract", "per-diem"])
</ParamField>

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

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

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

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

<RequestExample>
  ```bash theme={null}
  curl --request GET \
    --url 'https://api.harmonyforstaffing.com/api/matching/jobs?candidateId=456' \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "location": {
        "zipCode": "94143",
        "radius": 25,
        "states": ["CA"],
        "remote": true
      },
      "compensation": {
        "minimum": 65.00,
        "type": "hourly"
      },
      "schedule": {
        "availableDate": "2024-06-01",
        "shifts": ["day", "evening"],
        "hoursPerWeek": {
          "minimum": 32,
          "maximum": 40
        }
      },
      "jobTypes": ["full-time", "part-time"],
      "specialties": ["icu", "er"],
      "minScore": 70
    }'
  ```
</RequestExample>

### Response Fields

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

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

    <ResponseField name="title" type="string">
      Job title
    </ResponseField>

    <ResponseField name="employer" type="object">
      Employer information

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

        <ResponseField name="name" type="string">
          Employer name
        </ResponseField>

        <ResponseField name="location" type="object">
          <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>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="jobType" type="string">
      Type of position (e.g., "full-time", "part-time")
    </ResponseField>

    <ResponseField name="schedule" type="object">
      Schedule details

      <Expandable title="Schedule Object">
        <ResponseField name="shifts" type="array">
          Available shifts (e.g., \["day", "night"])
        </ResponseField>

        <ResponseField name="hoursPerWeek" type="object">
          <ResponseField name="minimum" type="integer">
            Minimum hours per week
          </ResponseField>

          <ResponseField name="maximum" type="integer">
            Maximum hours per week
          </ResponseField>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="compensation" type="object">
      Compensation details

      <Expandable title="Compensation Object">
        <ResponseField name="type" type="string">
          Pay type ("hourly" or "salary")
        </ResponseField>

        <ResponseField name="minimum" type="number">
          Minimum pay rate
        </ResponseField>

        <ResponseField name="maximum" type="number">
          Maximum pay rate
        </ResponseField>
      </Expandable>
    </ResponseField>

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

      <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="requirements" type="object">
      Job requirements

      <Expandable title="Requirements Object">
        <ResponseField name="experience" type="string">
          Experience requirements
        </ResponseField>

        <ResponseField name="certifications" type="array">
          Required certifications
        </ResponseField>

        <ResponseField name="license" type="object">
          <ResponseField name="type" type="string">
            License type (e.g., "RN")
          </ResponseField>

          <ResponseField name="state" type="string">
            State code where license is required
          </ResponseField>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="postedDate" type="string">
      When the job was posted (ISO 8601)
    </ResponseField>

    <ResponseField name="startDate" type="string">
      When the job starts (ISO 8601)
    </ResponseField>
  </Expandable>
</ResponseField>

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

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

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

<ResponseExample>
  ```json theme={null}
  {
    "jobs": [
      {
        "id": 123,
        "title": "ICU Nurse",
        "employer": {
          "id": 456,
          "name": "Saint Francis Hospital",
          "location": {
            "city": "San Francisco",
            "state": "CA",
            "zipCode": "94143"
          }
        },
        "jobType": "full-time",
        "schedule": {
          "shifts": ["day", "night"],
          "hoursPerWeek": {
            "minimum": 36,
            "maximum": 40
          }
        },
        "compensation": {
          "type": "hourly",
          "minimum": 65.00,
          "maximum": 85.00,
        },
        "screening": {
          "currentScore": 85.5,
          "potentialScore": 100,
          "disqualify": false,
          "summary": {
            "screeningSummary": "Strong match for your ICU experience and certifications...",
            "followUpQuestions": [
              "Are you able to start on June 1st?",
              "Are you comfortable with rotating shifts?"
            ],
            "strengths": [
              "Experience level exceeds requirements",
              "All required certifications current"
            ],
            "gaps": [
              "Location is 30 miles from your preferred radius"
            ]
          }
        },
        "requirements": {
          "experience": "2+ years ICU",
          "certifications": ["BLS", "ACLS", "PALS"],
          "license": {
            "type": "RN",
            "state": "CA"
          }
        },
        "postedDate": "2024-03-01T08:00:00Z",
        "startDate": "2024-06-01"
      }
    ],
    "total": 45,
    "limit": 20,
    "offset": 0
  }
  ```
</ResponseExample>