node-behind-api-client 2.0.48

package/docs/behind-api-client/easyjob/applicants/README.md

@@ -0,0 +1,494 @@
+# Applicants API Extension
+
+This document extends the main EasyJob JavaScript API Client Documentation with detailed information about the Applicants API methods.
+
+## Overview
+
+The Applicants API allows you to manage job applicants and their application status throughout the hiring process. This includes retrieving applicant details, managing application stages, and viewing lists of applicants for specific job postings.
+
+---
+
+## Applicants API
+
+### behindAPI.easyjob.V10.applicants.get(applicationId)
+Retrieves detailed information for a specific job applicant, including their complete profile data.
+
+**Parameters:**
+- `applicationId` (string, required) - The job application UUID to get detailed information for
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.applicants.get("dd0e8400-e29b-41d4-a716-446655440008");
+
+// Response:
+{
+    success: true,
+        data: {
+    application_id: "dd0e8400-e29b-41d4-a716-446655440008",
+        job_description_id: "770e8400-e29b-41d4-a716-446655440002",
+        candidate_profile_id: "aa0e8400-e29b-41d4-a716-446655440005",
+        message: "I am very interested in this position...",
+        stage: "initial_review",
+        application_created_at: "2024-01-20T14:30:00Z",
+        profile_id: "aa0e8400-e29b-41d4-a716-446655440005",
+        profile_data: {
+        first_name: "John",
+            last_name: "Doe",
+            email: "john.doe@example.com",
+            phone: "+1-555-123-4567",
+            location: "New York, NY",
+            summary: "Experienced software developer..."
+    },
+    facts: {
+        total_experience_years: 5,
+            education_level: "masters",
+            skills_match_percentage: 85
+    },
+    education: [
+        {
+            institution: "MIT",
+            degree: "Master of Science",
+            field_of_study: "Computer Science",
+            start_year: 2017,
+            end_year: 2019,
+            gpa: 3.8
+        }
+    ],
+        job_experience: [
+        {
+            company: "Tech Corp",
+            position: "Senior Software Engineer",
+            start_date: "2020-01-15",
+            end_date: "2024-01-15",
+            description: "Led development of microservices...",
+            technologies: ["React", "Node.js", "AWS"]
+        }
+    ],
+        hard_skills: [
+        {
+            skill: "JavaScript",
+            level: "Expert",
+            years_experience: 6
+        }
+    ],
+        soft_skills: [
+        {
+            skill: "Leadership",
+            level: "Advanced"
+        }
+    ],
+        certificates: [
+        {
+            name: "AWS Certified Solutions Architect",
+            issuing_organization: "Amazon Web Services",
+            issue_date: "2023-06-15",
+            expiry_date: "2026-06-15"
+        }
+    ],
+        languages: [
+        {
+            language: "English",
+            proficiency: "Native"
+        }
+    ],
+        profile_created_at: "2024-01-15T10:30:00Z",
+        profile_updated_at: "2024-01-20T09:15:00Z"
+}
+}
+```
+
+### behindAPI.easyjob.V10.applicants.stageChange(applicationId, newStage)
+Updates the stage of a job application for kanban-style tracking throughout the hiring process.
+
+**Parameters:**
+- `applicationId` (string, required) - The job application UUID to update
+- `newStage` (string, required) - The new stage value for the application
+
+**Common Stage Values:**
+- `"applied"` - Initial application received
+- `"initial_review"` - Application under initial review
+- `"phone_screening"` - Phone/video screening stage
+- `"technical_interview"` - Technical assessment stage
+- `"final_interview"` - Final interview stage
+- `"offer_extended"` - Job offer has been extended
+- `"hired"` - Candidate has been hired
+- `"rejected"` - Application has been rejected
+- `"withdrawn"` - Candidate has withdrawn application
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.applicants.stageChange(
+    "dd0e8400-e29b-41d4-a716-446655440008",
+    "technical_interview"
+);
+
+// Response:
+{
+    success: true
+}
+```
+
+### behindAPI.easyjob.V10.applicants.getList(jobDescriptionId)
+Retrieves a list of all job applicants for a specific job description.
+
+**Parameters:**
+- `jobDescriptionId` (string, required) - The job description UUID to get applicants for
+
+**Usage:**
+```javascript
+const result = await behindAPI.easyjob.V10.applicants.getList("770e8400-e29b-41d4-a716-446655440002");
+
+// Response:
+{
+    success: true,
+        data: [
+    {
+        application_id: "dd0e8400-e29b-41d4-a716-446655440008",
+        job_description_id: "770e8400-e29b-41d4-a716-446655440002",
+        candidate_profile_id: "aa0e8400-e29b-41d4-a716-446655440005",
+        message: "I am very interested in this position...",
+        stage: "initial_review",
+        application_created_at: "2024-01-20T14:30:00Z",
+        profile_id: "aa0e8400-e29b-41d4-a716-446655440005",
+        profile_data: {
+            first_name: "John",
+            last_name: "Doe",
+            email: "john.doe@example.com",
+            phone: "+1-555-123-4567",
+            location: "New York, NY",
+            summary: "Experienced software developer..."
+        },
+        profile_created_at: "2024-01-15T10:30:00Z"
+    },
+    {
+        application_id: "ee0e8400-e29b-41d4-a716-446655440009",
+        job_description_id: "770e8400-e29b-41d4-a716-446655440002",
+        candidate_profile_id: "bb0e8400-e29b-41d4-a716-446655440006",
+        message: "Looking forward to contributing to your team...",
+        stage: "phone_screening",
+        application_created_at: "2024-01-21T10:15:00Z",
+        profile_id: "bb0e8400-e29b-41d4-a716-446655440006",
+        profile_data: {
+            first_name: "Jane",
+            last_name: "Smith",
+            email: "jane.smith@example.com",
+            phone: "+1-555-987-6543",
+            location: "San Francisco, CA",
+            summary: "Full-stack developer with expertise..."
+        },
+        profile_created_at: "2024-01-18T16:45:00Z"
+    }
+]
+}
+```
+
+---
+
+## Data Structure Reference
+
+### Application Object (get method)
+The complete application object returned by `get()` includes:
+
+**Core Application Data:**
+- `application_id` (UUID) - Unique identifier for the application
+- `job_description_id` (UUID) - The job posting this application is for
+- `candidate_profile_id` (UUID) - The candidate's profile ID
+- `message` (string) - Cover letter or application message
+- `stage` (string) - Current stage in the hiring process
+- `application_created_at` (timestamp) - When the application was submitted
+
+**Profile Information:**
+- `profile_id` (UUID) - Candidate's profile identifier
+- `profile_data` (object) - Basic profile information
+- `facts` (object) - Computed facts about the candidate
+- `education` (array) - Educational background
+- `job_experience` (array) - Work history
+- `hard_skills` (array) - Technical skills
+- `soft_skills` (array) - Interpersonal skills
+- `certificates` (array) - Professional certifications
+- `languages` (array) - Language proficiencies
+- `profile_created_at` (timestamp) - Profile creation date
+- `profile_updated_at` (timestamp) - Last profile update
+
+### Application Object (getList method)
+The simplified application objects returned by `getList()` include:
+
+- `application_id` (UUID) - Unique identifier for the application
+- `job_description_id` (UUID) - The job posting this application is for
+- `candidate_profile_id` (UUID) - The candidate's profile ID
+- `message` (string) - Cover letter or application message
+- `stage` (string) - Current stage in the hiring process
+- `application_created_at` (timestamp) - When the application was submitted
+- `profile_id` (UUID) - Candidate's profile identifier
+- `profile_data` (object) - Basic profile information only
+- `profile_created_at` (timestamp) - Profile creation date
+
+---
+
+## Complete Usage Example
+
+```javascript
+// Complete workflow for managing job applicants
+async function manageJobApplicants(jobDescriptionId) {
+    try {
+        // 1. Get all applicants for a job posting
+        const applicantsList = await behindAPI.easyjob.V10.applicants.getList(jobDescriptionId);
+
+        if (!applicantsList.success) {
+            console.error("Failed to retrieve applicants list");
+            return;
+        }
+
+        console.log(`Found ${applicantsList.data.length} applicants`);
+
+        // 2. Process each applicant
+        for (const applicant of applicantsList.data) {
+            console.log(`\nProcessing applicant: ${applicant.profile_data.first_name} ${applicant.profile_data.last_name}`);
+            console.log(`Current stage: ${applicant.stage}`);
+            console.log(`Applied on: ${applicant.application_created_at}`);
+
+            // 3. Get detailed information for promising candidates
+            if (applicant.stage === "applied") {
+                const detailedInfo = await behindAPI.easyjob.V10.applicants.get(applicant.application_id);
+
+                if (detailedInfo.success) {
+                    const candidate = detailedInfo.data;
+
+                    // Analyze candidate qualifications
+                    const hasRequiredExperience = candidate.facts?.total_experience_years >= 3;
+                    const hasRelevantSkills = candidate.facts?.skills_match_percentage >= 70;
+                    const hasEducation = candidate.education && candidate.education.length > 0;
+
+                    // Determine next stage based on qualifications
+                    let newStage;
+                    if (hasRequiredExperience && hasRelevantSkills && hasEducation) {
+                        newStage = "phone_screening";
+                        console.log(`  ✓ Advancing to phone screening`);
+                    } else {
+                        newStage = "rejected";
+                        console.log(`  ✗ Rejecting due to insufficient qualifications`);
+                    }
+
+                    // Update application stage
+                    const stageUpdate = await behindAPI.easyjob.V10.applicants.stageChange(
+                        applicant.application_id,
+                        newStage
+                    );
+
+                    if (stageUpdate.success) {
+                        console.log(`  → Stage updated to: ${newStage}`);
+                    } else {
+                        console.log(`  ✗ Failed to update stage`);
+                    }
+                }
+            }
+        }
+
+        // 4. Generate summary report
+        const updatedList = await behindAPI.easyjob.V10.applicants.getList(jobDescriptionId);
+        const stageCounts = {};
+
+        updatedList.data.forEach(applicant => {
+            stageCounts[applicant.stage] = (stageCounts[applicant.stage] || 0) + 1;
+        });
+
+        console.log("\n=== Application Summary ===");
+        Object.entries(stageCounts).forEach(([stage, count]) => {
+            console.log(`${stage}: ${count} applicants`);
+        });
+
+    } catch (error) {
+        console.error("Error managing applicants:", error);
+    }
+}
+
+// Example: Moving candidates through the hiring pipeline
+async function progressHiringPipeline(jobDescriptionId) {
+    try {
+        const applicants = await behindAPI.easyjob.V10.applicants.getList(jobDescriptionId);
+
+        for (const applicant of applicants.data) {
+            // Get detailed candidate information
+            const candidate = await behindAPI.easyjob.V10.applicants.get(applicant.application_id);
+
+            if (!candidate.success) continue;
+
+            const candidateData = candidate.data;
+            let nextStage = applicant.stage;
+
+            // Progress candidates based on current stage and qualifications
+            switch (applicant.stage) {
+                case "phone_screening":
+                    // Move to technical interview if they have strong technical skills
+                    const techSkills = candidateData.hard_skills?.filter(skill =>
+                        ["JavaScript", "React", "Node.js", "Python"].includes(skill.skill)
+                    );
+                    if (techSkills && techSkills.length >= 2) {
+                        nextStage = "technical_interview";
+                    }
+                    break;
+
+                case "technical_interview":
+                    // Move to final interview if they have leadership experience
+                    const hasLeadership = candidateData.soft_skills?.some(skill =>
+                        skill.skill.toLowerCase().includes("leadership")
+                    );
+                    const seniorRole = candidateData.job_experience?.some(exp =>
+                        exp.position.toLowerCase().includes("senior") ||
+                        exp.position.toLowerCase().includes("lead")
+                    );
+                    if (hasLeadership || seniorRole) {
+                        nextStage = "final_interview";
+                    }
+                    break;
+
+                case "final_interview":
+                    // Extend offer to top candidates
+                    if (candidateData.facts?.skills_match_percentage >= 90) {
+                        nextStage = "offer_extended";
+                    }
+                    break;
+            }
+
+            // Update stage if it changed
+            if (nextStage !== applicant.stage) {
+                await behindAPI.easyjob.V10.applicants.stageChange(
+                    applicant.application_id,
+                    nextStage
+                );
+                console.log(`Advanced ${candidateData.profile_data.first_name} ${candidateData.profile_data.last_name} to ${nextStage}`);
+            }
+        }
+
+    } catch (error) {
+        console.error("Error progressing hiring pipeline:", error);
+    }
+}
+
+// Example: Filtering and analyzing applicants
+async function analyzeApplicantPool(jobDescriptionId) {
+    try {
+        const applicants = await behindAPI.easyjob.V10.applicants.getList(jobDescriptionId);
+
+        const analysis = {
+            total: applicants.data.length,
+            byStage: {},
+            byLocation: {},
+            averageExperience: 0,
+            topSkills: {}
+        };
+
+        let totalExperience = 0;
+        let experienceCount = 0;
+
+        // Analyze each applicant
+        for (const applicant of applicants.data) {
+            // Count by stage
+            analysis.byStage[applicant.stage] = (analysis.byStage[applicant.stage] || 0) + 1;
+
+            // Count by location
+            const location = applicant.profile_data.location;
+            if (location) {
+                analysis.byLocation[location] = (analysis.byLocation[location] || 0) + 1;
+            }
+
+            // Get detailed data for skills and experience analysis
+            const detailed = await behindAPI.easyjob.V10.applicants.get(applicant.application_id);
+            if (detailed.success) {
+                const candidate = detailed.data;
+
+                // Calculate experience
+                if (candidate.facts?.total_experience_years) {
+                    totalExperience += candidate.facts.total_experience_years;
+                    experienceCount++;
+                }
+
+                // Count skills
+                if (candidate.hard_skills) {
+                    candidate.hard_skills.forEach(skill => {
+                        analysis.topSkills[skill.skill] = (analysis.topSkills[skill.skill] || 0) + 1;
+                    });
+                }
+            }
+        }
+
+        // Calculate averages and sort results
+        analysis.averageExperience = experienceCount > 0 ? totalExperience / experienceCount : 0;
+
+        // Sort top skills
+        analysis.topSkills = Object.entries(analysis.topSkills)
+            .sort(([,a], [,b]) => b - a)
+            .slice(0, 10)
+            .reduce((obj, [skill, count]) => ({ ...obj, [skill]: count }), {});
+
+        console.log("=== Applicant Pool Analysis ===");
+        console.log(`Total Applicants: ${analysis.total}`);
+        console.log(`Average Experience: ${analysis.averageExperience.toFixed(1)} years`);
+        console.log("\nBy Stage:");
+        Object.entries(analysis.byStage).forEach(([stage, count]) => {
+            console.log(`  ${stage}: ${count}`);
+        });
+        console.log("\nTop Locations:");
+        Object.entries(analysis.byLocation).slice(0, 5).forEach(([location, count]) => {
+            console.log(`  ${location}: ${count}`);
+        });
+        console.log("\nMost Common Skills:");
+        Object.entries(analysis.topSkills).slice(0, 5).forEach(([skill, count]) => {
+            console.log(`  ${skill}: ${count} candidates`);
+        });
+
+        return analysis;
+
+    } catch (error) {
+        console.error("Error analyzing applicant pool:", error);
+        return null;
+    }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Stage Management**: Maintain consistent stage naming conventions across your hiring process. Define clear criteria for advancing candidates between stages.
+
+2. **Data Usage**: Use the detailed `get()` method sparingly for performance reasons. Use `getList()` for overview operations and `get()` only when you need complete candidate details.
+
+3. **Automated Processing**: Implement automated stage progression based on candidate qualifications and scores to streamline your hiring process.
+
+4. **Error Handling**: Always check the `success` property before processing applicant data, as applications might be deleted or access permissions might change.
+
+5. **Performance Optimization**: When processing large numbers of applicants, consider implementing batch processing with delays to avoid overwhelming the API.
+
+6. **Privacy Considerations**: Handle candidate personal information responsibly and in compliance with data protection regulations.
+
+---
+
+## Error Handling
+
+All methods return a response object with a `success` boolean property. When `success` is `false`, a `message` property will contain the error description.
+
+```javascript
+// Example error handling
+const result = await behindAPI.easyjob.V10.applicants.get(invalidApplicationId);
+
+if (!result.success) {
+    console.error("Error retrieving applicant:", result.message);
+    // Handle the error appropriately
+    return;
+}
+
+// Process successful result
+const applicantData = result.data;
+```
+
+---
+
+## Integration Notes
+
+The Applicants API works seamlessly with other EasyJob APIs:
+
+- **Job Descriptions**: Applications are linked to specific job postings
+- **Candidate Profiles**: Complete candidate information is accessible through applications
+- **Job Description Candidate Questions**: Candidate responses to custom questions can be tracked alongside applications
+- **Candidate Profile Artifacts**: Resumes and other documents are accessible through the applicant data structure