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

> Create a new screening for a candidate and job

Create a new screening to evaluate a candidate against job criteria. You can optionally provide additional or replacement criteria specific to this screening.

### Body Parameters

<ParamField body="candidateId" type="integer" required>
  ID of the candidate to screen (required if jobSubmissionId not provided)
</ParamField>

<ParamField body="jobId" type="integer" required>
  ID of the job to screen against (required if jobSubmissionId not provided)
</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="replaceCriteria" type="boolean" default="false">
  If true, provided criteria replace job criteria. If false, they are added to job criteria.
</ParamField>

<RequestExample>
  ```Request theme={null}
  curl --request POST \
    --url https://api.harmonyforstaffing.com/api/screening \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "candidateId": 456,
      "jobId": 123,
      "criteria": [
        {
          "description": "Must be experienced in Pediatric Intensive Care",
          "importance": "required",
          "type": "specialty"
        },
        {
          "description": "BLS certification required, PALS certification preferred",
          "importance": "required",
          "type": "certification"
        },
        {
          "description": "Experience with EPIC EMR system preferred",
          "importance": "preferred",
          "type": "experience"
        }
      ],
      "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}
  {
    "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, which is slightly below the required 3 years. However, their experience is recent and includes relevant critical care skills.",
        "textEvidence": "2 years of experience in Medical ICU at Saint Francis Hospital"
      },
      {
        "id": 2,
        "source": "job_criteria",
        "question": "Do you have current ACLS and BLS certifications?",
        "criteria": "Current ACLS and BLS certifications required",
        "type": "Required",
        "status": "FullyMet",
        "reasoning": "The candidate holds current ACLS and BLS certifications that are valid through 2025.",
        "textEvidence": "ACLS Certification (exp. 06/2025), BLS Certification (exp. 08/2025)"
      },
      {
        "id": 3,
        "source": "job_criteria",
        "question": "Do you have experience with EPIC EMR system?",
        "criteria": "Experience with EPIC EMR system preferred",
        "type": "Preferred",
        "status": "FullyMet",
        "reasoning": "The candidate has extensive experience using EPIC EMR in their current role.",
        "textEvidence": "Proficient in EPIC EMR system, including documentation, order entry, and care planning modules"
      },
      {
        "id": 4,
        "source": "job_criteria",
        "question": "Are you able to work night shifts?",
        "criteria": "Must be willing to work night shifts",
        "type": "Required",
        "status": "NotMet",
        "reasoning": "The resume does not indicate any night shift experience or willingness to work nights.",
        "textEvidence": null
      }
    ],
    "qualificationLevel": "Appropriate",
    "isRelevant": true
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      "Must provide either jobSubmissionId or both candidateId and jobId",
      "Invalid importance value. Must be one of: required, preferred, optional"
    ]
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "not_found",
    "message": "Job submission, candidate, or job not found"
  }
  ```
</ResponseExample>