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

# Screen Many Candidates

> Screen multiple candidates against a job

Screen multiple candidates against a job, including a summary of the screening results. You can optionally provide additional or replacement criteria specific to this screening.

### Body Parameters

<ParamField body="candidateId" type="integer">
  Single candidate ID to screen against multiple jobs (required if jobIds provided)
</ParamField>

<ParamField body="jobId" type="integer">
  Single job ID to screen multiple candidates against (required if candidateIds provided)
</ParamField>

<ParamField body="criteria" type="array">
  Additional screening criteria (optional)

  <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="replaceCriteria" type="boolean" default="false">
  If true, provided criteria replace job criteria. If false, they are added to job criteria.
</ParamField>

### Request Examples

<RequestExample>
  ```bash Screen Multiple Candidates Against One Job theme={null}
  curl --request POST \
    --url https://api.harmonyforstaffing.com/api/screening/batch \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "jobId": 123,
      "candidateIds": [456, 457, 458],
      "criteria": [
        {
          "description": "Must be experienced in Pediatric Intensive Care",
          "importance": "required",
          "type": "specialty"
        }
      ],
      "replaceCriteria": true
    }'
  ```
</RequestExample>

### Response Fields

<ResponseField name="id" type="integer">
  Unique identifier for the screening
</ResponseField>

<ResponseField name="jobSubmissionId" type="integer">
  ID of the job submission being screened (if exists)
</ResponseField>

<ResponseField name="candidateId" type="integer">
  ID of the candidate being screened
</ResponseField>

<ResponseField name="jobId" type="integer">
  ID of the job being screened against
</ResponseField>

<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="criteria" type="array">
  Detailed analysis of each criterion

  <Expandable title="Criterion fields">
    <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>

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

<ResponseExample>
  ```json theme={null}
  {
    "screenings": [
      {
        "id": 789,
        "candidateId": 456,
        "jobId": 123,
        "currentScore": 66.67,
        "potentialScore": 100,
        "disqualify": false,
        "criteria": [
          {
            "id": 1,
            "source": "job_criteria",
            "question": "How many years of ICU nursing experience do you have?",
            "criteria": "Minimum of 3 years ICU nursing experience required",
            "type": "YearsOfExperience",
            "status": "PartiallyMet",
            "reasoning": "The candidate has 2 years of ICU experience...",
            "textEvidence": "2 years of experience in Medical ICU"
          }
        ],
        "qualificationLevel": "Appropriate",
        "isRelevant": true
      }
      // ... Additional screening results
    ]
  }
  ```
</ResponseExample>