Recruit.win Documentation

Recruit.win is an AI-powered HR hiring platform that automates candidate screening, AI phone interviews, and recruitment pipeline management. This documentation covers everything you need to install, configure, and use the platform effectively.

Dashboard

The Dashboard (/app/dashboard) provides an at-a-glance overview of your hiring activity with real-time metrics pulled from your HR data.

Key Metrics

• Total Candidates — Number of candidates across all jobs.
• Total Interviews — Number of AI phone interviews conducted.
• Shortlisted Candidates — Candidates who passed AI screening thresholds.
• Completion Rate — Percentage of interviews completed vs. scheduled.
• Shortlist Rate — Percentage of screened candidates who were shortlisted.
• Active Jobs — Number of currently open positions.

The dashboard also shows recent activity, upcoming interviews, and pipeline distribution charts.

Jobs

The Jobs page (/app/jobs) is where you create and manage job openings. Each job defines the requirements against which candidates are screened.

Creating a Job

1. Click Create Job from the Jobs page.
2. Fill in the job details:
   • Title — e.g., "Senior Software Engineer"
   • Description — Full job description
   • Department — Engineering, Product, Design, etc.
   • Location & Type — Onsite, Remote, or Hybrid
   • Employment Type — Full-time, Part-time, Contract, Internship
   • Salary Range — Min/Max with currency
   • Experience Level — Entry, Mid, Senior, Lead, Executive
   • Required Skills — Skills candidates must have
   • Preferred Skills — Nice-to-have skills
   • Education Level — Minimum education requirement

AI Screening Configuration

Each job has configurable AI screening weights that determine how candidates are scored:

• Skills Weight (default 40%) — How much skill match affects the score
• Experience Weight (default 35%) — How much experience alignment affects the score
• Education Weight (default 25%) — How much education match affects the score
• Shortlist Threshold (default 70) — Candidates scoring above this are auto-shortlisted

Interview Questions

You can define structured interview questions with categories (technical, behavioral, cultural) and weights. These are used by AI agents during phone interviews.

Hiring Widget Toggle

Each job has a toggle to make it visible in the Hiring Widget. When enabled, candidates can apply and take AI interviews directly from your website.

Candidates

The Candidates page (/app/candidates) displays all candidates across your jobs. You can filter by job, pipeline stage, AI score, and more.

Adding Candidates

• Manual Entry — Add candidates one by one with their details.
• Individual CV Upload — Upload a single PDF resume. AI extracts structured data (skills, experience, education) and scores the candidate.
• Bulk ZIP Upload — Upload a ZIP file containing multiple CVs. See CV Upload for details.
• Widget Applications — Candidates apply through the Hiring Widget on your website.
• REST API — Add candidates programmatically via the REST API.

AI Screening Scores

After AI screening, each candidate receives:

• Overall AI Score (0-100) — Composite score based on configured weights
• Skills Score — Match percentage for required and preferred skills
• Experience Score — Alignment with experience requirements
• Education Score — Match with education requirements
• AI Summary — Natural language assessment of the candidate
• Strengths — Key strengths identified by AI
• Weaknesses — Areas where the candidate falls short
• Recommendation — Advance, Hold, or Reject

Candidate Profile

Each candidate profile shows parsed CV data, work history, education, contact information, AI scores, interview history, pipeline stage, and user comments.

Pipeline

The Pipeline page (/app/pipeline) provides a visual board showing candidates organized by their current stage in the hiring process.

Pipeline Stages

Rejected — Candidates can be rejected at any stage.

Stage Descriptions

• Uploaded — CV received but not yet screened by AI.
• AI Screened — AI has analyzed the CV and assigned a score. Candidates above the shortlist threshold automatically advance.
• Shortlisted — Candidate meets requirements and is ready for interview scheduling.
• Interview Scheduled — An AI phone interview has been scheduled.
• Interviewed — AI interview is complete with evaluation scores.
• Hired — Offer extended and accepted.
• Rejected — Candidate did not meet requirements at any stage.

Pipeline History

Every stage change is recorded with a timestamp, reason, and who initiated the change (AI, system, or user). This provides a complete audit trail for each candidate's journey.

CV Upload

The CV Upload page (/app/cv-upload) lets you upload CVs in bulk for processing.

How It Works

1. Select a Job — Choose which job opening the CVs are for.
2. Upload a ZIP File — The ZIP can contain PDF, DOC, or DOCX resume files.
3. Processing — The system extracts each file, parses the content, creates candidate records, and runs AI screening.
4. Results — View processing status: total files, processed, failed, and candidates created.

Interviews

The Interviews page (/app/interviews) manages AI-powered phone interviews with candidates.

Interview Types

• Phone Interviews — AI calls the candidate on their phone number using Twilio or Plivo. The conversation is conducted by an AI agent configured with job-specific questions.
• Widget Interviews — Browser-based interviews initiated through the Hiring Widget.

Interview Flow

1. A shortlisted candidate is scheduled for an interview (manually or via auto-caller).
2. The AI agent calls the candidate at the scheduled time.
3. The agent asks job-specific interview questions configured in the Job settings.
4. After the call, the system generates:
   • Overall Score (0-100)
   • Communication Score — Clarity, articulation, language proficiency
   • Technical Score — Domain knowledge and problem-solving
   • Culture Fit Score — Alignment with company values
   • Per-question Scores — Individual evaluation for each question asked
   • Full Transcript — Complete conversation text
   • AI Evaluation — Written assessment with recommendation (advance/hold/reject)
   • Recording URL — Audio recording of the interview
5. The candidate's pipeline stage updates to "Interviewed" with scores attached.

Auto-Caller

Jobs can be configured with an Auto-Caller that automatically calls shortlisted candidates who meet a minimum AI score threshold. Configure concurrent call limits, retry attempts, and delays in the Job settings.

Hiring Agents

Hiring Agents (/app/agents) are the AI personalities that conduct phone interviews and handle incoming calls.

Agent Types

• Natural (LLM-Powered) — Uses a large language model with a system prompt you write. The AI conversates naturally based on the prompt instructions. Best for open-ended interviews.
• Flow (Visual Editor) — Uses a visual conversation flow you design with the Flow Builder. The AI follows a structured path. Best for standardized screenings.
• Incoming — Handles calls from candidates who call back. Recognizes returning candidates by phone number and personalizes the conversation with their context.

Configuration

• Voice — Choose from available voices (ElevenLabs voice library or OpenAI voices).
• LLM Model — Select the language model and temperature for response generation.
• System Prompt — Define the agent's personality, instructions, and interview guidelines.
• First Message — The opening message the agent says when the call connects. Supports variable substitution (e.g., {{contact_name}}).
• Human Transfer — Configure when and how the agent transfers to a human interviewer.
• Background Sound — Optional ambient audio for a more natural call experience.
• Incoming Calls — Enable incoming call handling and assign a phone number. The agent uses callback recognition to identify returning candidates.

Interview Flows

The Flows page (/app/flows) provides a visual editor for designing structured conversation flows for AI agents.

Flow Builder

The drag-and-drop flow builder lets you create conversation trees with:

• Message Nodes — What the AI says to the candidate
• Question Nodes — Questions with expected answer types
• Condition Nodes — Branch logic based on candidate responses
• Action Nodes — Trigger actions like scheduling, form collection, or call transfer
• End Nodes — Conclude the conversation with a summary

Flow Templates

Pre-built templates are available for common interview scenarios. You can use them as-is or customize them for your needs. Templates include technical screenings, behavioral interviews, and qualification calls.

Compilation

Flows are compiled to the appropriate format for the selected AI engine (ElevenLabs workflow JSON or OpenAI instructions) when assigned to an agent.

Phone Numbers

The Phone Numbers page (/app/phone-numbers) manages the phone numbers used for outbound and inbound calls.

Provisioning

• Twilio Numbers — Search and purchase phone numbers from Twilio by country and area code.
• Plivo Numbers — Search and purchase phone numbers from Plivo.
• SIP Trunks — Use your own SIP trunk provider via the SIP Engine Plugin.

Number Assignment

Assign phone numbers to Hiring Agents to enable:

• Outbound Calls — The number appears as the caller ID when the agent calls candidates.
• Incoming Calls — Candidates can call this number to reach the AI agent. The agent recognizes returning candidates and provides personalized responses.

Hiring Widget

The Hiring Widget is an embeddable JavaScript widget that lets candidates apply to jobs and take AI interviews directly from your company website.

Features

• 6-Step Wizard — Personal details → CV upload → AI analysis → Job matches → Schedule interview → Confirmation
• Multi-Job Matching — CV is scored against all open, widget-enabled jobs
• Score Transparency — Candidates see match percentage with strengths and gaps for each job
• Two Interview Modes — Schedule a date/time or take an instant AI phone interview
• Company Branding — Customize colors, logo, and company name
• Mobile Responsive — Works on all device sizes
• Two Display Modes — Floating button or inline embed

Embedding the Widget

Floating Button Mode

<script
  src="https://yourdomain.com/hiring-widget/embed.js"
  data-token="YOUR_WIDGET_TOKEN"
></script>

Inline Embed Mode

<div id="agenthr-hiring"></div>
<script
  src="https://yourdomain.com/hiring-widget/embed.js"
  data-token="YOUR_WIDGET_TOKEN"
  data-mode="inline"
  data-container="agenthr-hiring"
></script>

Configuration

Manage widget settings from the Jobs page — toggle which jobs appear in the widget, copy embed code, preview the widget, and customize appearance from the Widgets page (/app/tools/widgets).

Knowledge Base

The Knowledge Base (/app/knowledge-base) allows you to upload documents that provide context to AI agents during interviews.

How It Works

1. Upload Documents — Upload PDFs, text files, or other documents containing company information, job details, product knowledge, or interview guidelines.
2. Processing — Documents are automatically chunked, embedded, and stored for retrieval-augmented generation (RAG).
3. Context Injection — During interviews, the AI agent retrieves relevant chunks from the knowledge base to provide accurate, context-aware responses.

This is particularly useful for giving agents access to company policies, product details, or technical specifications they might need to discuss during interviews.

Analytics

The Analytics page (/app/analytics) provides detailed insights into your hiring performance.

Available Metrics

• Pipeline Funnel — Visual funnel showing candidate drop-off at each stage
• Time-to-Hire — Average time from candidate upload to hire
• AI Score Distribution — Distribution of candidate scores across jobs
• Interview Completion Rate — Percentage of scheduled interviews that were completed
• Source Effectiveness — Which candidate sources (LinkedIn, Indeed, Referral, etc.) produce the best results
• Job-level Metrics — Per-job breakdown of candidates, interviews, and hires

Billing & Credits

The Billing page (/app/billing) manages your subscription plan, credits, and payment history.

Plans

• Free Plan — Limited features and call minutes for trying the platform.
• Pro Plan — Full access to all features, higher limits, and priority support.

Credit System

AI phone interviews consume credits based on call duration. Credits can be purchased in packages or included with your subscription plan. The dashboard shows your current credit balance and usage history.

Payment Gateways

The platform supports five payment gateways. Your administrator configures which gateways are available:

• Stripe (credit/debit cards, global)
• Razorpay (India-focused)
• PayPal (global)
• Paystack (Africa-focused)
• MercadoPago (Latin America-focused)

Invoices

PDF invoices are automatically generated for each purchase and available for download from the billing page.

Settings

The Settings page (/app/settings) manages your account and workspace configuration.

• Profile — Name, email, password, avatar
• API Keys — Generate API keys for REST API access with scoped permissions
• Notifications — Configure email notification preferences
• Team Management — Invite team members, assign roles, and set section-wise permissions (requires Team Management plugin)
• Webhooks — Configure webhook endpoints for event notifications with HMAC-SHA256 verification

Admin Panel

The Admin Panel (/admin) is accessible to users with administrator privileges and provides platform-wide management capabilities.

Dashboard

Platform-wide analytics including total users, total candidates, total interviews, active campaigns, phone line usage, and subscription metrics.

User Management

View, search, and manage platform users. Adjust credit balances, change plans, suspend accounts, and view per-user analytics.

API Key Pools

Manage pooled API keys for ElevenLabs, OpenAI, and Twilio. The platform supports multi-key pooling with automatic fallback — if one key hits rate limits, the system automatically routes to another key.

Global Settings

• Platform Branding — Company name, logo, colors, favicon
• Authentication — JWT expiry, session configuration, OTP settings
• Email (SMTP) — Configure or update SMTP settings from the admin panel
• Payment Gateways — Enable/disable and configure Stripe, Razorpay, PayPal, Paystack, MercadoPago
• Call Limits — Default concurrent call limits, retry settings
• LLM Models — Configure which AI models are available and their tier (free/pro)
• Resource Monitoring — View memory usage, set auto-restart thresholds

Plugin Management

Enable or disable platform plugins (REST API, SIP Engine, Team Management). Each plugin adds features and API endpoints without requiring code changes.

REST API Plugin

The REST API plugin provides programmatic access to platform features for external integrations.

Authentication

Authenticate API requests using an API key in the X-API-Key header:

curl -H "X-API-Key: your_api_key_here" \
  https://yourdomain.com/api/v1/contacts

Generate API keys from Settings with scoped permissions (read/write access per resource).

Endpoints

Rate Limiting

API requests are rate-limited per API key. Standard limits are 60 requests per minute for read operations and 30 requests per minute for write operations.

Documentation

Interactive API documentation is available at:

• Redoc (read-only): /api/docs
• Swagger UI (interactive): /api/docs/playground

SIP Engine Plugin

The SIP Engine plugin allows you to use your own SIP trunk provider instead of Twilio or Plivo for telephony.

Supported Engines

• ElevenLabs SIP — Full inbound and outbound call support via SIP trunks connected to ElevenLabs conversational AI.
• OpenAI SIP — Incoming call support via SIP trunks connected to OpenAI Realtime API.

Supported Providers

The SIP Engine supports 13+ SIP trunk providers including Telnyx, Vonage, Bandwidth, SignalWire, and more. Configure your trunk credentials and the platform routes calls through your provider.

Configuration

Set up SIP trunks from the user dashboard at /app/phone-numbers (SIP tab) or manage platform-wide SIP settings from the admin panel.

Troubleshooting

Application Won't Start

Database Connection Errors

• Verify PostgreSQL is running: pg_isready
• Test the connection string: psql $DATABASE_URL -c "SELECT 1"
• Check for firewall rules blocking port 5432.
• Ensure the database user has proper permissions.

AI Screening Not Working

• Verify OPENAI_API_KEY is set and valid.
• Check the admin panel → Settings → OpenAI connection test.
• Ensure the OpenAI key has access to the required models (GPT-4o recommended).
• Check server logs for API error messages.

Interview Calls Failing

• No calls going out:
  • Verify Twilio/Plivo credentials are correct (test connection in Admin Panel).
  • Ensure a phone number is purchased and assigned to the agent.
  • Check the candidate has a valid phone number with country code.
  • Verify you have sufficient credits.
• Calls connect but no AI response:
  • Check ElevenLabs or OpenAI API key validity.
  • Verify the agent has a voice selected.
  • Check WebSocket connectivity (ensure Nginx proxies WebSocket correctly).
• Webhook errors:
  • Ensure APP_URL is publicly accessible (Twilio/Plivo need to reach your server).
  • Check SSL certificate validity.
  • Verify webhook URLs in the server logs.

Hiring Widget Not Loading

• Verify the widget token is correct (copy from Jobs page).
• Check that at least one job has the widget enabled.
• Ensure the script URL is correct and your server is publicly accessible.
• Check browser console for CORS errors — the widget script is served with CORS headers by default.
• If embedding on HTTPS pages, your server must also use HTTPS.

Email Not Sending

• Verify SMTP settings in the admin panel (Settings → Communications).
• Use the "Test Connection" button to verify SMTP connectivity.
• For Gmail: use an App Password (not your regular password) and ensure "Less secure apps" is configured or use OAuth.
• Check that the SMTP port matches your provider (587 for TLS, 465 for SSL, 25 for unencrypted).
• Review server logs for specific SMTP error messages.

Credit/Billing Issues

• Credits not deducting — Check that the payment gateway processed successfully (view transaction history in Billing).
• Insufficient credits — Purchase additional credit packages from the Billing page or ask your admin to adjust your balance.
• Payment failing — Verify payment gateway configuration in the admin panel. Check webhook secrets for Stripe.

Performance Optimization

• Use Node.js cluster mode or a reverse proxy for multi-core utilization.
• Enable Redis and BullMQ for large campaign processing (set ENABLE_BULLMQ=true).
• Monitor memory usage from the Admin Panel dashboard.
• Configure auto-restart thresholds in Admin → Settings to prevent memory leaks from affecting service.
• Use connection pooling for PostgreSQL (configured automatically by default).

Debugging Tips

• Server logs are output to stdout. In production, view them: bash scripts/production.sh logs
• Set NODE_ENV=development for more verbose logging.
• Use the Health Check endpoint: GET /api/health to verify all services.
• Check integration status on startup — the server logs show connection status for each service (ElevenLabs, Twilio, OpenAI, Stripe, SMTP).
• For WebSocket issues, check browser developer tools Network tab for WS connections.

Frequently Asked Questions

Contact Support