Ai Candidate Screener

An Apify Actor that evaluates English/ESL teacher candidates using AI by analyzing employer criteria against candidate responses. Features comprehensive evaluation including audio quality assessment for pronunciation, accent, and fluency.

Features

• Comprehensive Candidate Evaluation: Analyzes experience, motivation, teaching approach, problem-solving, and logistics
• Audio Quality Assessment: Evaluates pronunciation, accent, fluency, intonation, and clarity from audio recordings (optional)
• Structured Scoring: Provides scores (1-10) for experience, communication, fit, motivation, problem-solving, and spoken English
• Hiring Recommendations: Generates recommendations (hire/interview/reject) with detailed reasoning
• Detailed Assessments: Returns strengths, concerns, key highlights, and spoken English assessment
• Dual Output: Stores results in both Apify dataset and key-value store for easy retrieval

Use Cases

• ESL/English Teacher Recruitment: Screen candidates for teaching positions
• Language School Hiring: Evaluate pronunciation and teaching ability
• Remote Hiring: Automated initial screening before interviews
• High-Volume Recruitment: Process multiple candidates efficiently

Setup

1. Install Dependencies

$npm install

2. Configure OpenAI API Key

Option 1 (Recommended): Set as environment variable in Apify Console

• Go to your Actor settings → Secrets
• Add OPENAI_API_KEY with your OpenAI API key

Option 2: Provide in input JSON (not recommended for production)

• Include openai_api_key in the input JSON

Note: Audio evaluation requires GPT-4o access. Ensure your OpenAI API key has access to GPT-4o models.

Local Testing

$apify run

This will prompt you for input JSON. Use the example below or provide your own.

Deployment

1. Log in to Apify:

$apify login

2. Push the Actor:

$apify push

3. Set Environment Variables in Apify Console:
   • Add OPENAI_API_KEY as a secret environment variable

Input Schema

The Actor expects JSON input with the following structure:

Required Fields

• employer_criteria (object): Job requirements and criteria

  • role (string): Job title/position
  • location (string, optional): Job location
  • max_salary_krw (number, optional): Maximum salary in KRW
  • must_haves (array, optional): Required qualifications/skills

• candidate_answers (object): Candidate responses

  • name (string): Candidate name
  • current_location (string): Current location
  • visa_status (string): Visa/work authorization status
  • years_experience (number): Years of teaching experience
  • age_groups_taught (string): Age groups taught (e.g., "elementary, middle school")
  • why_teaching (string): Motivation for teaching
  • enjoy_about_teaching (string): What they enjoy about teaching
  • teaching_challenges (string): Challenges faced and how overcome
  • education_background (string): Educational background and certifications
  • previous_locations (string): Previous teaching locations
  • availability (string): Availability to start
  • salary_expectation_krw (number): Expected salary in KRW
  • sample_intro (string): Written introduction about teaching style
  • spoken_intro_transcript (string): Transcript of spoken English sample
  • spoken_intro_audio_base64 (string, optional): Base64-encoded audio file (WebM format) for pronunciation evaluation

• openai_api_key (string, optional): OpenAI API key (if not using environment variable)

Output Structure

Results are stored in both:

1. Dataset (via Actor.pushData())
2. Key-Value Store (as RESULT key)

Output Schema

{
  "overall_fit": "strong" | "average" | "weak",
  "recommendation": "hire" | "interview" | "reject",
  "summary": "Detailed 2-3 paragraph evaluation summary",
  "scores": {
    "experience": 1-10,
    "communication": 1-10,
    "fit": 1-10,
    "motivation": 1-10,
    "problem_solving": 1-10,
    "spoken_english": 1-10
  },
  "strengths": ["Array of key strengths"],
  "concerns": ["Array of concerns or areas for improvement"],
  "key_highlights": ["Array of standout qualities"],
  "spoken_english_assessment": "Detailed assessment of spoken English quality"
}

Evaluation Criteria

The Actor evaluates candidates across 6 categories:

1. Experience & Qualifications (25%)

   • Years of teaching experience
   • Age groups taught
   • Educational background
   • Previous teaching locations

2. Motivation & Fit (20%)

   • Why they want to teach
   • Passion and interest
   • Cultural fit
   • Alignment with school values

3. Teaching Approach (15%)

   • Teaching style and methods
   • Adaptability
   • Communication skills
   • Examples of effective teaching

4. Spoken English Quality (25%) ⭐

   • If audio provided: Pronunciation, accent, fluency, intonation, clarity (via GPT-4o audio analysis)
   • If transcript only: Grammar, vocabulary, naturalness, clarity
   • Critical for ESL teaching positions

5. Problem-Solving & Resilience (10%)

   • Handling challenges
   • Adaptability
   • Examples of overcoming difficulties

6. Logistics & Practicality (5%)

   • Visa status
   • Availability
   • Salary expectations
   • Location considerations

Evaluation Rules

The Actor applies specific business rules:

• Salary: If salary_expectation_krw > max_salary_krw, adds to concerns
• Visa: If visa_status is missing or unacceptable, recommendation = "reject"
• Experience: If no experience with target age group AND no training, max recommendation = "interview"
• Audio Quality: If spoken_intro_audio_base64 is provided, uses GPT-4o for pronunciation/accent evaluation
• Missing Data: Missing transcript or poor quality is a major concern for ESL teaching

Example Input

Basic Example (Transcript Only)

{
  "employer_criteria": {
    "role": "ESL Teacher (Elementary)",
    "location": "Seoul",
    "max_salary_krw": 3000000,
    "must_haves": ["native or near-native English", "in Korea or 30 days"]
  },
  "candidate_answers": {
    "name": "John Doe",
    "current_location": "Seoul",
    "visa_status": "E-2",
    "years_experience": 3,
    "age_groups_taught": "elementary, middle school",
    "why_teaching": "I love helping children learn and grow",
    "enjoy_about_teaching": "Seeing students progress and gain confidence",
    "teaching_challenges": "Managing different learning styles - I adapt my approach",
    "education_background": "Bachelor's in Education, TESOL certified",
    "previous_locations": "Korea, China",
    "availability": "Immediate",
    "salary_expectation_krw": 2800000,
    "sample_intro": "I use interactive games and activities to make learning fun",
    "spoken_intro_transcript": "Hello, my name is John and I have three years of experience teaching English to elementary students."
  }
}

Advanced Example (With Audio Evaluation)

{
  "employer_criteria": {
    "role": "ESL Teacher (Elementary)",
    "location": "Seoul",
    "max_salary_krw": 3000000,
    "must_haves": ["native or near-native English"]
  },
  "candidate_answers": {
    "name": "Jane Smith",
    "current_location": "Seoul",
    "visa_status": "E-2",
    "years_experience": 5,
    "age_groups_taught": "elementary",
    "why_teaching": "Passionate about education",
    "enjoy_about_teaching": "Student engagement and progress",
    "teaching_challenges": "Adapting to different learning styles",
    "education_background": "Master's in TESOL",
    "previous_locations": "Korea",
    "availability": "2 weeks notice",
    "salary_expectation_krw": 2900000,
    "sample_intro": "I create engaging, interactive lessons",
    "spoken_intro_transcript": "Hello, my name is Jane and I have five years of experience teaching English.",
    "spoken_intro_audio_base64": "BASE64_ENCODED_AUDIO_FILE_HERE"
  }
}

Note: For audio evaluation, provide spoken_intro_audio_base64 as a base64-encoded WebM audio file. The Actor will use GPT-4o to analyze pronunciation, accent, fluency, intonation, and clarity.

Audio Evaluation

When spoken_intro_audio_base64 is provided, the Actor:

1. Converts base64 to audio buffer
2. Sends to GPT-4o for audio analysis
3. Evaluates:
   • Pronunciation (clarity, accuracy of sounds)
   • Accent (native-like vs. foreign, intelligibility)
   • Fluency (smoothness, pace, natural flow)
   • Intonation (stress patterns, rhythm, naturalness)
   • Clarity (overall understandability)
4. Provides detailed scores (1-10) for each aspect
5. Includes audio evaluation in the final assessment

Requirements: GPT-4o API access (check your OpenAI account)

API Integration

Starting an Actor Run

const response = await fetch(
  `https://api.apify.com/v2/acts/YOUR_USERNAME~ai-candidate-screener/runs?token=YOUR_TOKEN`,
  {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({
      employer_criteria: { /* ... */ },
      candidate_answers: { /* ... */ },
      webhooks: [
        {
          eventTypes: ['ACTOR.RUN.SUCCEEDED'],
          requestUrl: 'https://your-app.com/webhook'
        }
      ]
    })
  }
);

const { data } = await response.json();
const runId = data.id;

Retrieving Results

From Key-Value Store (recommended):

const result = await fetch(
  `https://api.apify.com/v2/key-value-stores/STORE_ID/records/RESULT?token=YOUR_TOKEN`
).then(r => r.json());

From Dataset:

const items = await fetch(
  `https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_TOKEN`
).then(r => r.json());

Limitations

• Audio evaluation requires GPT-4o API access
• Audio files should be WebM format (browser MediaRecorder default)
• Maximum audio length: Follow OpenAI API limits
• Base64 encoding increases payload size (consider compression for large files)

Support

For issues, questions, or contributions, please open an issue on the Actor's GitHub repository or contact the maintainer.

License

ISC

Version History

• 0.0: Initial release
  • Comprehensive candidate evaluation
  • Audio quality assessment (pronunciation, accent, fluency)
  • Structured scoring system
  • Webhook support