terminal REST API & Real-Time Event Architecture

Integrate WaMax ATS Into Your Enterprise Architecture.

Build seamless recruitment workflows between your internal ERP, CRM, and WaMax's 5-channel WhatsApp automation engine. Ingest candidates, trigger AI passport MRZ extraction, conduct automated voice audits, and capture private client portal selections via authenticated webhooks.

code Browse 8 Core Endpoints play_circle Interactive Sandbox

Median Latency

< 42ms

High-Speed Sockets

Rate Limit

120/min

Burst 300/min

Uptime SLA

99.98%

Fault-Tolerant

Security

HMAC-256

Signed Payloads

API Fundamentals & Base URL

All requests to the WaMax Enterprise ATS API are made over HTTPS and return standard JSON payloads. All timestamps are formatted according to ISO-8601 (UTC).

Base Endpoint https://hr.whatyouwantkerala.in/api/v1

Authentication & Authorization

WaMax utilizes API Bearer tokens generated from your Super Admin / Agency dashboard. Pass your unique secret key in the HTTP Authorization header.

Authorization: Bearer wmx_live_9a8b7c6d5e4f3a2b1...

Content-Type: application/json

X-WaMax-Tenant: apex-overseas-recruitment

security

Security Practice

Never expose your wmx_live_* keys in client-side code or public repositories. Store API tokens in server environment variables or enterprise secret vaults.

Enterprise Specification

Core ATS API Endpoints

Recruitment Ingestion

1. Submit Candidate Application

POST /api/v1/candidates/apply

Ingests a candidate record directly into the WaMax ATS pipeline. Automatically links to the client's recruitment requisition and initializes background MRZ validation.

curl -X POST https://hr.whatyouwantkerala.in/api/v1/candidates/apply \
  -H "Authorization: Bearer wmx_live_9a8b7c6d5e4f3a2b1..." \
  -H "Content-Type: application/json" \
  -d '{
    "client_slug": "sobha-realty",
    "name": "Faheem Al-Noor",
    "phone": "+919876543210",
    "trade_applied": "Heavy Duty HVAC Technician",
    "experience_years": 6,
    "passport_doc_url": "https://storage.wamax.pro/docs/pass_sample.jpg",
    "voice_note_url": "https://storage.wamax.pro/audio/voice_int.ogg"
  }'

Response: 201 Created

{
  "success": true,
  "candidate_id": "cand_98124_faheem",
  "pipeline_stage": "Screened & Vetted",
  "client_review_url": "https://hr.whatyouwantkerala.in/client_portal.html?token=pt_98fa2...",
  "created_at": "2026-10-07T16:30:00Z"
}

Optical Vision Engine

2. AI Passport MRZ & Validity Verification

POST /api/v1/ocr/passport-mrz

Processes candidate passport images to extract ICAO 9303 standard 2-line Machine Readable Zone (MRZ) characters. Calculates age, validates expiry date against destination GCC visa criteria, and returns clean structured JSON.

Request Body (JSON)

{
  "candidate_id": "cand_8923a",
  "document_url": "https://storage.wamax.pro/docs/pass_arjun.jpg",
  "destination_country": "UAE",
  "minimum_validity_months": 6
}

Response: 200 OK

{
  "success": true,
  "mrz_status": "VALID_PASS",
  "extracted": {
    "passport_number": "V8923411",
    "nationality": "IND",
    "dob": "1997-04-12",
    "age_years": 29,
    "gender": "M",
    "expiry_date": "2032-04-11",
    "months_to_expiry": 66,
    "eligible_for_visa": true
  },
  "confidence_score": 0.994
}

Voice AI Intelligence

3. Audio Assessment & Fluency Scoring

POST /api/v1/voice/screen

Evaluates WhatsApp voice notes recorded by candidates during automated screening. Returns transcription, keyword matching for specific trades, and overall language competence.

Response: 200 OK

{
  "success": true,
  "candidate_id": "cand_8923a",
  "audio_score": 96.5,
  "language_detected": "English (Indian Dialect)",
  "trade_keywords_found": ["HVAC Chillers", "Compressor Overhaul", "Ductwork"],
  "summary": "Candidate clearly explains 6 years gulf experience maintaining central chilled water systems."
}

Pipeline Management

4. Live Pipeline Status & Stage Transitions

GET /api/v1/candidates/pipeline

Returns live counts and candidate summaries across all 5 recruitment stages: Applied, Screened & Vetted, Interview Requested, Client Selected, and Visa In Process.

{
  "success": true,
  "stages": {
    "applied": 142,
    "screened": 89,
    "client_review": 38,
    "interview_requested": 14,
    "visa_selected": 22
  },
  "total_active_candidates": 305
}

Update Stage via PATCH: PATCH /api/v1/candidates/:id/stage

Payload: {"new_stage": "Visa In Process", "notify_candidate_whatsapp": true}

Employer Collaboration

5. Client Review Portal Decision Hook

POST /api/client-hiring/portal/decision

Endpoint invoked when an overseas employer reviews candidates in their token-protected portal (`/client-portal?token=...`). Personal contact details are masked, and decision updates instantly sync back to your agency ATS.

curl -X POST https://hr.whatyouwantkerala.in/api/client-hiring/portal/decision \
  -H "Content-Type: application/json" \
  -d '{
    "token": "d748f2c01991ab39c4a...",
    "candidate_id": "cand_8923a",
    "decision": "INTERVIEW_REQUESTED",
    "interview_date": "2026-10-12T10:00:00Z",
    "client_feedback": "Impressive gulf credentials. Proceed with video interview."
  }'

Outbound Communications

6. Dispatch WhatsApp Notification

POST /api/v1/whatsapp/send

Sends a direct WhatsApp message to candidate or client using one of your 5 active WhatsApp SIM slots. Supports plain text, PDF attachments (interview calls, visa copies), or interactive list menus.

{
  "slot_number": 1,
  "to": "+919876543210",
  "message": "Congratulations! Sobha Realty has scheduled your interview for Monday, 10 AM.",
  "document_attachment_url": "https://storage.wamax.pro/docs/interview_call_8923a.pdf"
}

Real-Time Event Architecture

Webhook Subscriptions

Instead of continuous polling, configure your webhook endpoint in the Admin Console to receive instantaneous JSON payloads when hiring events occur.

Event Name	Trigger Condition	Typical Action
candidate.applied	New candidate completes WhatsApp or web form	Create profile in agency ERP
passport.mrz_verified	AI Optical parser confirms passport validity	Update compliance checklist
voice.screened	Audio interview analysis complete	Attach fluency rating to CRM
client.decision_submitted	Overseas employer shortlists candidate	Notify candidate via WhatsApp

verified HMAC-SHA256 Signature Verification

Every webhook request includes an X-WaMax-Signature header generated using your secret webhook key. Verify this signature to confirm request authenticity:

const crypto = require('crypto');

const signature = req.headers['x-wamax-signature'];

const expected = crypto.createHmac('sha256', WEBHOOK_SECRET).update(req.rawBody).digest('hex');

if (signature !== expected) return res.status(401).send('Invalid signature');

Live Test Console

Interactive API Sandbox

Simulate real-time requests against the WaMax ATS runtime. Choose an endpoint, inspect the request structure, and execute test payloads instantly.

Target Endpoint

Request Payload (JSON)

Response Inspector 200 OK • 38ms

{\n  "status": "ready",\n  "message": "Select an endpoint and click Execute to test live response."\n}

Rate Limits & HTTP Response Codes

To guarantee high availability and protect against abusive traffic, API requests are subject to token-bucket rate limiting. Rate limit headers are provided on every response:

X-RateLimit-Limit

Maximum permitted requests (120/min per tenant).

X-RateLimit-Remaining

Number of remaining calls in current 60s window.

X-RateLimit-Reset

Unix timestamp when rate budget replenishes.

Standard HTTP Status Codes

200 / 201 Request processed successfully.

400 Bad Request (Invalid payload or missing params).

401 Unauthorized (Missing or invalid API token).

429 Too Many Requests (Rate limit threshold reached).

Primary Default AI Multi-Model

ScaleMax AI Multi-Model Gateway

OpenAI-Compatible Chat Protocol

ScaleMax is the primary default AI engine powering candidate screening, live recruiter chat, voice transcript analysis, and resume parsing across WaMax. ScaleMax supports Anthropic (Claude & Fable), OpenAI GPT-6, Google Gemini 3, DeepSeek V4, GLM, Grok, and open-weight models with instant automatic fallback to secondary providers.

Token Budget Surface (Recommended) https://api.scalemax.pro/token/v1/chat/completions

Used for accounts with fixed token budgets (sm_live_... keys).

API Credit Surface (USD) https://api.scalemax.pro/v1/chat/completions

Used for standard USD pay-as-you-go credit keys.

Sample cURL Request:

curl "https://api.scalemax.pro/token/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_SCALEMAX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "system", "content": "You are WaMax Recruiter AI."},
      {"role": "user", "content": "Evaluate candidate skills for Heavy Duty Technician."}
    ]
  }'

Model	Provider Family	Context	Max Output	Rate / 1M Tokens (In / Out)
Sonnet 4.6 Recommended	Anthropic	1,000,000	384,000	$0.44 / $1.32
Claude Haiku 5.5	Anthropic	1,000,000	128,000	$0.10 / $0.50
Gemini 3 Flash (Preview)	Google Gemini	1,050,000	65,500	$0.50 / $3.00
GPT-6 Luna	OpenAI	1,050,000	128,000	$0.10 / $0.50
DeepSeek V4 Flash	DeepSeek	1,000,000	384,000	$0.19 / $0.51
LongCat 2.5 Preview	Specialty	1,000,000	262,000	FREE ($0.00 / $0.00)