> ## 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 Job Submission

> Screen a candidate for a specific job submission

Screen a candidate for a specific job submission, including a summary of the screening results and recommendations for next steps. You can optionally provide additional or replacement criteria specific to this screening.

### Body Parameters

<ParamField body="jobSubmissionId" type="integer">
  ID of the job submission to screen (required if candidateId and jobId 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>
  ```bash Using Job Submission ID theme={null}
  curl --request POST \
    --url https://api.harmonyforstaffing.com/api/screening \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "jobSubmissionId": 789,
      "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
    }'
  ```
</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="submissionSummary" type="object">
  Detailed screening analysis and recommendations

  <Expandable title="Summary fields">
    <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="applicationReadiness" type="object">
  Analysis of application completeness and readiness to submit

  <Expandable title="Readiness fields">
    <ResponseField name="readinessScore" type="number">
      Overall readiness score (0-100) based on completeness and qualification
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status: "Ready", "NeedsInformation", "NeedsQualification", "NotQualified"
    </ResponseField>

    <ResponseField name="requiredDocuments" type="object">
      <ResponseField name="missing" type="array">
        Required documents that need to be provided
      </ResponseField>

      <ResponseField name="expiringSoon" type="array">
        Documents that will expire within 90 days
      </ResponseField>

      <ResponseField name="verified" type="array">
        Documents that have been verified
      </ResponseField>
    </ResponseField>

    <ResponseField name="qualificationGaps" type="object">
      <ResponseField name="critical" type="array">
        Required qualifications that are missing
      </ResponseField>

      <ResponseField name="recommended" type="array">
        Preferred qualifications that would strengthen the application
      </ResponseField>
    </ResponseField>

    <ResponseField name="workHistoryGaps" type="object">
      <ResponseField name="gaps" type="array">
        Time periods with no employment history

        <Expandable title="Gap Object">
          <ResponseField name="startDate" type="string">
            When the gap started (ISO 8601)
          </ResponseField>

          <ResponseField name="endDate" type="string">
            When the gap ended (ISO 8601)
          </ResponseField>

          <ResponseField name="duration" type="string">
            Human readable duration (e.g., "3 months")
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="totalGapDuration" type="string">
        Total duration of all gaps (e.g., "8 months")
      </ResponseField>
    </ResponseField>

    <ResponseField name="verificationStatus" type="object">
      <ResponseField name="pendingVerification" type="array">
        Items needing verification (e.g., references, credentials)
      </ResponseField>

      <ResponseField name="verified" type="array">
        Items that have been verified
      </ResponseField>
    </ResponseField>

    <ResponseField name="nextSteps" type="array">
      Prioritized list of actions to improve application readiness
    </ResponseField>
  </Expandable>
</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,
    "submissionSummary": {
      "screeningSummary": "The candidate meets most critical requirements including ICU experience and certifications. While they have slightly less experience than required, their strong qualifications in pediatric care make them a promising candidate.",
      "followUpQuestions": [
        "Are you willing and able to work night shifts?",
        "Would you be comfortable working with pediatric patients given your adult ICU background?",
        "Is your PALS certification current or would you be willing to obtain it?"
      ],
      "missingInformation": [
        "Night shift availability",
        "Pediatric care experience details",
        "PALS certification status"
      ],
      "strengths": [
        "Current ACLS and BLS certifications",
        "Recent ICU experience",
        "Proficient with EPIC EMR"
      ],
      "gaps": [
        "Experience level slightly below requirement (2 years vs 3 years)",
        "No confirmed night shift experience",
        "No explicit pediatric care experience"
      ]
    },
    "applicationReadiness": {
      "readinessScore": 75,
      "status": "NeedsInformation",
      "requiredDocuments": {
        "missing": [
          "PALS certification",
          "Professional references"
        ],
        "expiringSoon": [
          "RN License (expires in 60 days)"
        ]
      },
      "qualificationGaps": {
        "critical": [
          "Night shift availability confirmation",
          "PALS certification"
        ],
        "recommended": [
          "Additional year of ICU experience",
          "Pediatric care experience"
        ]
      },
      "workHistoryGaps": {
        "gaps": [
          {
            "startDate": "2022-06-01",
            "endDate": "2022-08-15",
            "duration": "2.5 months"
          },
          {
            "startDate": "2023-01-01",
            "endDate": "2023-03-01",
            "duration": "2 months"
          }
        ],
        "totalGapDuration": "4.5 months",
      },
      "nextSteps": [
        "Submit PALS certification",
        "Provide professional references",
        "Confirm night shift availability",
        "Renew RN license"
      ]
    },
    "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>