Skip to main content
POST
/
api
/
screening
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
  }'

{
  "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
}
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

​
candidateId
integer
required
ID of the candidate to screen (required if jobSubmissionId not provided)
​
jobId
integer
required
ID of the job to screen against (required if jobSubmissionId not provided)
​
criteria
array
Additional screening criteria
​
replaceCriteria
boolean
default:"false"
If true, provided criteria replace job criteria. If false, they are added to job criteria.
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
  }'

​
Response Fields

​
id
integer
Unique identifier for the screening
​
jobSubmissionId
integer
ID of the job submission being screened (if exists)
​
candidateId
integer
ID of the candidate being screened
​
jobId
integer
ID of the job being screened against
​
currentScore
number
Current match percentage based on verified criteria (0-100)
​
potentialScore
number
Maximum possible match percentage if all unverified criteria are met (0-100)
​
disqualify
boolean
Whether the candidate should be disqualified from the job
​
criteria
array
Detailed analysis of each criterion
​
qualificationLevel
string
Overall qualification assessment (e.g., “Appropriate”, “Overqualified”, “Underqualified”)
​
isRelevant
boolean
Indicates if the candidate’s background is relevant to the position
{
  "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
}

{
  "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"
  ]
}