REST API Reference — AI Screening Tools Endpoints

Base URL: https://api.jobasean.com All endpoints accept and return JSON unless noted otherwise. HTTPS only.

Authentication

JWT Pass Authorization: Bearer <token> header. Obtain token from POST /api/login.

Public No auth header needed. Rate limited by IP.

Turnstile Cloudflare Turnstile token in request body. For form-submitted endpoints only.

CV Screening

POST /api/aiva/routine/bpo

Screen a Candidate CV

Submit a candidate CV and job requirements. Returns a hire/hold/reject decision with a 0–100 score and written rationale. Free tier: 3 calls per day per IP, no key required. For higher volume, pass an API key in the request body.

AuthPublic

Rate limit3 / day (free) · Unlimited with key

Content-Typeapplication/json

Request body

        
{
  "job_title": "Customer Service Representative",
  "job_description": "Handle inbound calls for a BPO. English fluency required.",
  "cv_text": "John Santos — 2 years call center experience at Teleperformance Cebu...",
  "api_key": ""  // optional — leave empty for free tier
}
      

Field	Type	Required	Notes
job_title	string	Required	Role you are hiring for
job_description	string	Required	Full requirements and responsibilities
cv_text	string	Required	Extracted plain text from the candidate CV
api_key	string	Optional	Leave empty for free tier (3/day per IP)

Response — 200 OK

{
  "score": 78,
  "decision": "INTERVIEW",
  "rationale": "Strong call center background with 2 years relevant experience. English proficiency demonstrated...",
  "strengths": ["2 years BPO experience", "Cebu-based"],
  "gaps": ["No collections experience mentioned"]
}
      

Score bands: 80–100 = HIRE · 60–79 = INTERVIEW · 40–59 = HOLD · 0–39 = REJECT

AIVA — Async Video Interview

POST /api/aiva/interview

Create a Video Interview

Employer creates a video interview for a candidate. Returns a token and a candidate-facing link. The candidate opens the link in their browser, records answers to each question, and submits. No app or download required. Free tier: 3 per day per IP. Pass an API key for unlimited.

AuthPublic

Rate limit3 / day (free) · Unlimited with key

Content-Typeapplication/json

Request body

        
{
  "candidate_email": "candidate@example.com",  // email-lock — only this email can submit
  "job_role": "Customer Service Representative",
  "questions": [
    "Tell us about your call center experience.",
    "How do you handle an angry caller?"
  ],
  "api_key": ""  // optional — leave empty for free tier
}
      

Field	Type	Required	Notes
candidate_email	string	Required	Only this email can submit — prevents link sharing
job_role	string	Required	Shown to candidate on the interview page
questions	array of strings	Required	Up to 10 questions. Max 15 minutes recording per question.
api_key	string	Optional	Leave empty for free tier (3/day per IP)

Response — 200 OK

{
  "token": "abc123xyz",
  "interview_url": "https://aiscreeningtools.com/aiva-interview-record.html?token=abc123xyz",
  "expires_at": "2026-07-27T12:00:00Z"
}
      

GET /api/aiva/interview/{token}

Load Interview Questions (Candidate)

Called by the candidate-facing recording page. Returns the job role and list of questions for the interview identified by token. Does not return any scoring data or employer information.

AuthPublic

Rate limit20 / min

Response — 200 OK

{
  "job_role": "Customer Service Representative",
  "questions": [
    "Tell us about your call center experience.",
    "How do you handle an angry caller?"
  ]
}
      

POST /api/aiva/interview/{token}/submit

Submit Video Responses (Candidate)

Candidate submits their recorded video answers. Each video is uploaded to Bunny CDN, transcribed via OpenAI Whisper, and scored by AIVA. The submitted email must match the email the employer specified when creating the interview. Duplicate submissions are rejected. Proctoring data (tab switches, paste events, timing) is collected automatically by the recording page.

AuthPublic (email-locked)

Rate limit10 / min

Content-Typemultipart/form-data

Form fields

Field	Type	Required	Notes
candidate_email	string	Required	Must match the email set by the employer
video_0, video_1 … video_N	file (video/*)	Required	One file per question, named by index
tab_switches	integer	Optional	Proctoring — number of tab-away events
paste_events	integer	Optional	Proctoring — number of paste events
time_on_questions_sec	integer	Optional	Total time candidate spent on question screen
recording_duration_sec	integer	Optional	Total video recording duration in seconds

Response — 200 OK

{
  "status": "submitted",
  "responses_scored": 2
}
      

Returns 403 if candidate_email does not match the invite. Returns 409 if already submitted.

GET /api/aiva/interview/{token}/results

Get Interview Results (Employer)

Returns the scored video responses for a completed interview. Each response includes the Whisper transcript, AIVA score (0–100), decision, and proctoring signals. Available once the candidate has submitted.

AuthPublic (token-gated)

Rate limit20 / min

Response — 200 OK

{
  "job_role": "Customer Service Representative",
  "candidate_email": "candidate@example.com",
  "responses": [
    {
      "question_index": 0,
      "question": "Tell us about your call center experience.",
      "transcript": "I have two years of experience at Teleperformance handling inbound...",
      "score": 82,
      "decision": "HIRE",
      "tab_switches": 0,
      "paste_events": 0
    }
  ]
}
      

Score bands: 80–100 = HIRE · 60–79 = INTERVIEW · 40–59 = HOLD · 0–39 = REJECT

AIVA — BPO Text Assessment

POST /api/aiva/assessment

Create a Text Assessment

Employer creates a BPO Core assessment for a candidate. Returns a token and a candidate-facing link. The candidate completes 7 tests covering typing speed and accuracy, email writing, grammar, attention to detail, chat simulation, reading comprehension, and tone recognition. Total time approximately 20 minutes. Scored 0–100 automatically. Free tier: 3 per day per IP.

AuthPublic

Rate limit3 / day (free) · Unlimited with key

Content-Typeapplication/json

Request body

        
{
  "candidate_email": "candidate@example.com",
  "job_role": "Customer Service Representative",
  "api_key": ""  // optional — leave empty for free tier
}
      

Field	Type	Required	Notes
candidate_email	string	Required	Candidate's email — used for results tracking
job_role	string	Required	Shown to candidate on the assessment page
api_key	string	Optional	Leave empty for free tier (3/day per IP)

Response — 200 OK

{
  "token": "def456uvw",
  "assessment_url": "https://aiscreeningtools.com/aiva-assessment.html?token=def456uvw",
  "expires_at": "2026-07-27T12:00:00Z"
}
      

GET /api/aiva/assessment/{token}

Load Assessment Pack (Candidate)

Called by the candidate-facing assessment page. Returns the BPO Core test pack with questions and prompts. Answer keys and scoring rubrics are stripped from the response — candidates see only what they need to complete the tests.

AuthPublic

Rate limit20 / min

Response — 200 OK

{
  "job_role": "Customer Service Representative",
  "pack": "bpo_core",
  "tests": [
    { "id": "typing", "label": "Typing Speed & Accuracy" },
    { "id": "email_writing", "label": "Email Writing", "prompt": "A customer emails to report a billing error..." },
    { "id": "grammar", "label": "Grammar & Sentence Correction" },
    { "id": "attention_to_detail", "label": "Attention to Detail" },
    { "id": "chat_simulation", "label": "Chat Simulation" },
    { "id": "reading_comprehension", "label": "Reading Comprehension" },
    { "id": "tone_recognition", "label": "Tone Recognition" }
  ]
}
      

POST /api/aiva/assessment/{token}/submit

Submit Assessment Answers (Candidate)

Candidate submits all 7 test answers in a single JSON body. Auto-scored fields (typing, MCQ grammar, attention to detail, reading comprehension, tone recognition) are scored instantly — 0 to 46 points. Email writing and chat simulation are scored by AIVA Claude on 9 dimensions each — 0 to 54 points. Total score: 0–100.

AuthPublic

Rate limit10 / min

Content-Typeapplication/json

Request body

        
{
  "candidate_email": "candidate@example.com",
  "typing_wpm": 52,
  "typing_accuracy": 96,        // percentage 0–100
  "email_answer": "Dear Customer, Thank you for contacting us...",
  "grammar_answers": [1, 2, 0, 3],  // MCQ indices
  "attention_answers": [0, 1, 1, 0],
  "chat_answers": [
    "I understand your frustration. Let me look into that right away."
  ],
  "reading_answers": [2, 0, 1, 3],
  "tone_answers": [1, 0, 2, 1]
}
      

Response — 200 OK

{
  "total_score": 83,
  "auto_score": 41,    // typing + MCQ tests, max 46
  "aiva_score": 42,    // email + chat simulation, max 54
  "decision": "HIRE"
}
      

Score bands: 80–100 = HIRE · 60–79 = INTERVIEW · 40–59 = HOLD · 0–39 = REJECT

GET /api/aiva/assessment/{token}/results

Get Assessment Results (Employer)

Returns the scored assessment response for a submitted token. Results are sorted by total score descending so the strongest candidates appear first. Available once the candidate has submitted.

AuthPublic (token-gated)

Rate limit20 / min

Response — 200 OK

{
  "job_role": "Customer Service Representative",
  "results": [
    {
      "candidate_email": "candidate@example.com",
      "total_score": 83,
      "auto_score": 41,
      "aiva_score": 42,
      "typing_wpm": 52,
      "typing_accuracy": 96,
      "decision": "HIRE",
      "submitted_at": "2026-07-20T09:14:00Z"
    }
  ]
}
      

Social Profile Check

POST /api/social/check

Run a Social Media Profile Scan

Submit up to 5 social profile URLs for one candidate. Returns 6 behavioral dimension scores (1–10) plus Part A text flag analysis. Requires a Cloudflare Turnstile token (from the web form) and an email address for rate limiting. For programmatic access without a Turnstile token, use the MCP tool social_profile_scan instead.

AuthTurnstile + email rate-limit

Rate limit3 / day per email

Content-Typeapplication/json

For Claude agents and automated workflows, use the MCP tool social_profile_scan — it handles auth automatically. See the MCP Tools Reference.

Request body

        
{
  "candidate_name": "Maria Reyes",
  "email": "recruiter@yourcompany.com",  // rate-limit key
  "platforms": {
    "facebook": "https://www.facebook.com/maria.reyes.example",
    "tiktok": "",
    "instagram": "",
    "linkedin": "",
    "twitter": ""
  },
  "turnstile_token": "<cloudflare-turnstile-token>"
}
      

Response — 200 OK

{
  "candidate_name": "Maria Reyes",
  "platforms_checked": ["facebook"],
  "part_a_flags": {
    "profanity": false,
    "employer_complaints": false,
    "threats_or_violence": false,
    "drug_references": false
  },
  "part_b_scores": {
    "online_professionalism": 8,
    "written_communication": 7,
    "interpersonal_disposition": 9,
    "resilience_positivity": 8,
    "community_engagement": 6,
    "overall_impression": 8
  },
  "summary": "No flags detected. Strong professional presentation across observed platforms..."
}
      

CONNECT — Video Profiles

POST /api/connect/invite

Create a Screening Invite Link

Generate a unique invite link to send to a candidate. When the candidate opens the link, the CONNECT widget auto-opens with your job role and custom questions pre-loaded. The recorded video appears in your employer inbox after email verification and moderation.

AuthJWT (employer)

Rate limit20 / min

Content-Typeapplication/json

Request body

        
{
  "candidate_email": "candidate@example.com",  // optional
  "job_role": "Customer Service Representative",
  "questions": [
    "Tell us about your call center experience.",
    "How do you handle an angry caller?"
  ]
}
      

Field	Type	Required	Notes
job_role	string	Required	Shown to candidate in the widget
questions	array of strings	Required	Up to 10 questions. Shown in widget before recording.
candidate_email	string	Optional	Pre-fills candidate email if provided

Response — 200 OK

{
  "token": "abc123xyz",
  "invite_url": "https://aiscreeningtools.com/connect.html?invite=abc123xyz",
  "expires_at": "2026-07-13T12:00:00Z"
}
      

GET /api/connect/videos

Get Employer Inbox (Video Submissions)

Returns all video submissions for your employer account. Only returns videos where the candidate has verified their email and moderation has passed. Includes Bunny CDN embed URLs for direct playback.

AuthJWT (employer)

Rate limit30 / min

Response — 200 OK

{
  "videos": [
    {
      "id": "uuid-here",
      "candidate_name": "John Santos",
      "candidate_email": "john@example.com",
      "job_role": "Customer Service Representative",
      "bunny_embed_url": "https://iframe.mediadelivery.net/embed/572707/video-id",
      "submitted_at": "2026-07-06T10:30:00Z",
      "moderation_status": "approved"
    }
  ]
}
      

Only email_verified = true and moderation_status = approved videos are returned.

Maya AI

POST /api/chat

Maya Conversational Chat

Send a message to Maya and get a conversational AI response. Used by the chat panel on aiscreeningtools.com. Maya answers questions about products, pricing, and BPO workflows. Pass country_code: "hub" for the AI Screening Tools context (as opposed to a Thailand job search context).

AuthPublic

Rate limit30 / min

Content-Typeapplication/json

Request body

        
{
  "message": "What does CONNECT cost for a 200-agent BPO?",
  "country_code": "hub",
  "session_id": "optional-session-uuid",
  "language": "English"
}
      

Response — 200 OK

{
  "reply": "For a 200-agent BPO, the CONNECT Engage tier at $199/month covers up to 5,000 profile views...",
  "session_id": "session-uuid"
}
      

POST /api/maya-evaluate

Maya Evaluation (Structured Prompt)

Send a structured evaluation prompt to Maya. Returns a direct AI response without conversational history. Used internally by the CONNECT assessments tool and by the AIVA MCP screening tools. Unlike /api/chat, this endpoint takes a single prompt and returns a single answer — no session maintained.

AuthPublic

Rate limit20 / min

Content-Typeapplication/json

Request body

        
{
  "prompt": "Rate this candidate for a collections role. CV: 3 years collections, met targets...",
  "country_code": "ph",
  "language": "English"
}
      

Response — 200 OK

{
  "reply": "Strong collections candidate. 3 years directly relevant experience..."
}
      

Newsletter

POST /api/newsletter/subscribe

Subscribe to Newsletter

Subscribe an email address to the BPO insights newsletter. Silent duplicate handling — submitting an existing email returns 200 or 204 without error. New subscribers receive a welcome email and are added to the drip sequence.

AuthPublic

Rate limit3 / min per IP

Content-Typeapplication/json

Request body

        
{
  "email": "recruiter@yourcompany.com",
  "language": "en",
  "source_page": "bpo-packages"
}
      

Response — 201 Created (new subscriber)

{ "status": "subscribed" }

Returns 200 or 204 silently for existing subscribers. Never returns an error for duplicate emails.

Error Responses

Status	Meaning	Common cause
400	Bad Request	Missing required field or invalid format
401	Unauthorized	JWT token missing or expired
403	Forbidden	Turnstile verification failed
422	Unprocessable	Request body schema error (FastAPI validation)
429	Too Many Requests	Rate limit exceeded — wait and retry
500	Server Error	Upstream AI API failure — retry after a few seconds

This page is the complete REST API reference for the AI Screening Tools platform at api.jobasean.com. The candidate screening API accepts a CV and job role, runs AI scoring using our AIVA engine, and returns a hire decision with written rationale — designed for BPO hiring workflows where manual first-round screening creates bottlenecks. The social profile check API scans Facebook, TikTok, Instagram, and LinkedIn profiles and returns six behavioral dimension scores. The Maya chat API powers AI workflow automation for inbound and outbound conversations across WhatsApp, Viber, LINE, and website widgets. Deployment partners and technical integrators use these endpoints to embed AI agent tools directly into existing ATS platforms and HR systems.

← API Documentation MCP Tools Reference →