LiveKit Voice Agents - Developer Portal

GET /api/campaigns List all campaigns ▼

Retrieve all recruitment campaigns owned by the authenticated developer account.

Request Headers

Header	Type	Description
x-api-token	string *required	Your API authorization token. Can also be supplied via standard Authorization Bearer header.

Payload Reference

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "campaign_uid": "c001_sales",
    "name": "Backend Python Developer Campaign",
    "status": "active",
    "target_company": "Acme Software Ltd",
    "target_role": "Senior Python Backend Engineer",
    "created_at": "2026-06-08T10:00:00Z"
  }
]

POST /api/campaigns Create a campaign ▼

Initializes a new recruitment hiring campaign. Dictates the targeted job role, skills checklist, threshold scores, custom screening queries, and Voice synthesis configurations.

Request Body Fields

Property	Type	Description
name	string *req	Descriptive campaign name identifier.
target_company	string *req	Company name candidate will be applying to.
target_role	string	Target job title.
min_score_threshold	integer	Flow 1 cut-off threshold score (0-100) to auto-trigger Flow 2 call. Default: 70.
flow_1_custom_questions	array[string]	Specific questions prompt templates to prepend into screening call script.

Payload Reference

{
  "name": "Backend Python Developer Campaign",
  "target_company": "Acme Software Ltd",
  "agent_company": "Apex Recruits",
  "target_role": "Senior Python Backend Engineer",
  "min_score_threshold": 75,
  "enable_second_call": true,
  "flow_1_custom_questions": [
    "Explain the difference between threading and multiprocessing in Python."
  ]
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "campaign_uid": "c001_sales",
  "name": "Backend Python Developer Campaign",
  "status": "draft",
  "target_company": "Acme Software Ltd",
  "target_role": "Senior Python Backend Engineer",
  "created_at": "2026-06-08T10:00:00Z"
}

GET /api/campaigns/<str:id> Get campaign details ▼

Retrieve all properties, prompt templates, criteria settings, and provider configs of a single campaign by ID.

Payload Reference

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "campaign_uid": "c001_sales",
  "name": "Backend Python Developer Campaign",
  "status": "draft",
  "target_company": "Acme Software Ltd",
  "target_role": "Senior Python Backend Engineer",
  "min_score_threshold": 75,
  "enable_second_call": true,
  "flow_1_questions": ["What is Python?"],
  "flow_1_custom_questions": ["Explain the difference between threading and multiprocessing in Python."],
  "stt_provider": "deepgram",
  "tts_provider": "cartesia",
  "llm_provider": "openai",
  "created_at": "2026-06-08T10:00:00Z"
}

PATCH /api/campaigns/<str:id>/update Update a campaign ▼

Partially update properties of a campaign. Note: Supporting both /api/campaigns/<id>/update and /api/campaigns/<id>/patch endpoints.

Payload Reference

{
  "status": "active",
  "min_score_threshold": 80
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "campaign_uid": "c001_sales",
  "name": "Backend Python Developer Campaign",
  "status": "active",
  "updated_at": "2026-06-08T10:15:00Z"
}

DELETE /api/campaigns/<str:id>/delete Delete campaign ▼

Permanently deletes a campaign and purges all candidates records, dialer queues, and call logs from the database.

Payload Reference

{
  "message": "Campaign deleted successfully",
  "campaignId": "550e8400-e29b-41d4-a716-446655440000"
}

GET /api/campaigns/<str:id>/dashboard Retrieve dashboard stats ▼

Fetches aggregated statistics for the campaign, including candidate totals, shortlists count, completed calls count, and total telephony pricing/duration metrics.

Payload Reference

{
  "totalCandidates": 42,
  "shortlisted": 12,
  "callsCompleted": 35,
  "totalCost": "0.00",
  "avgCostPerMinute": "0.0000"
}

GET /api/campaigns/<str:id>/export-all Export candidates sheet ▼

Generates and downloads a complete Excel spreadsheet containing candidate scores, evaluation responses, resumes details, transcripts, and callback information.

Response Headers

Header	Value	Description
Content-Disposition	attachment; filename=campaign-<id>-shortlisted.xlsx	Forces web browser to trigger spreadsheet file download directly.
Content-Type	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	MIME type indicating Microsoft Excel OpenXML file layout.

POST /api/campaigns/<str:id>/start-calls Start automated sequence calls ▼

Changes campaign status to active and initiates outbound sequential phone calls for all candidates who have not yet been dialed.

Payload Reference

{
  "success": true,
  "message": "Campaign calls initiated with automated Flow 1 -> Flow 2 progression",
  "campaignId": "550e8400-e29b-41d4-a716-446655440000",
  "candidatesQueued": 15
}

POST /api/campaigns/<str:id>/retry-rejected Retry call-rejected list ▼

Resets previous rejected call records (due to busy lines, dropped networks, or no answers) and schedules them for redialing.

Request Body Fields

Property	Type	Description
flowNumber	integer	Selects whether to retry Flow 1 or Flow 2 calls. Allowed values: 1, 2. Default: 1.

Payload Reference

{
  "flowNumber": 1
}

{
  "success": true,
  "message": "Retrying 5 rejected candidates",
  "campaignId": "550e8400-e29b-41d4-a716-446655440000",
  "flowNumber": 1,
  "candidatesQueued": 5
}

GET /api/campaigns/<str:id>/script-preview Preview prompts scripts ▼

Generates the system prompt templates, list of questions, custom inputs, opening statements, and closing templates for Flow 1 and Flow 2 dialog agents.

Payload Reference

{
  "flow1": {
    "type": "screening",
    "openingMessage": "Hello! I am the automated recruitment agent at Apex Recruits...",
    "questions": [
      "Can you confirm your current notice period?",
      "What are your current and expected salary expectations?"
    ],
    "skillQuestions": [
      "Describe your hands-on experience using Python web frameworks."
    ],
    "customQuestions": [],
    "closingMessage": "Thank you so much for your time..."
  },
  "flow2": {
    "type": "availability",
    "openingMessage": "Hello Jane! Congrats on passing our first round screening...",
    "questions": [
      "When are you available to join us for the final technical assessment?"
    ],
    "customQuestions": [],
    "closingMessage": "Thank you! You'll receive a confirmation email shortly."
  }
}

POST /api/campaigns/<str:id>/test-call Trigger test call session ▼

Dispatches a mock test candidate and triggers a single outbound call to the provided phone number. Useful for verifying SIP connectivity and testing LLM audio responses.

Request Body Fields

Property	Type	Description
phoneNumber	string *req	The target phone number in E.164 format (e.g. +1234567890).

Payload Reference

{
  "phoneNumber": "+919876543210"
}

{
  "success": true,
  "message": "Test call initiated successfully",
  "callId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}

POST /api/campaigns/<str:id>/pause Pause dialing calling ▼

Halts active sequential calling. Pending queued dialers will be set to failed. Active connected calls are unaffected.

Payload Reference

{
  "message": "Campaign paused successfully",
  "campaignId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "paused"
}

POST /api/campaigns/<str:id>/resume Resume dialing calling ▼

Resumes sequential calling progression. Restarts background dialers thread to pick up the next eligible candidate.

Payload Reference

{
  "message": "Campaign resumed successfully",
  "campaignId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "active"
}

POST /api/campaigns/<str:id>/stop Stop campaign permanently ▼

Shuts down campaign calling operations permanently. Purges dialer queues cache from database. Status changes to stopped.

Payload Reference

{
  "message": "Campaign stopped permanently",
  "campaignId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "stopped"
}

POST /api/campaigns/<str:campaign_id>/call-all/ Bulk dial all candidates ▼

Dial all candidates belonging to the campaign in sequential queue mode or concurrent parallel execution mode.

Request Body Fields

Property	Type	Description
flowNumber	integer	Which voice flow to initiate. Range: 1, 2. Default: 1.
sequential	boolean	If true, calls are placed one by one. If false, calls are fired concurrently. Default: true.

Payload Reference

{
  "flowNumber": 1,
  "sequential": false
}

{
  "message": "Bulk call initiation started (parallel mode)",
  "mode": "parallel",
  "callsQueued": 3,
  "totalEligible": 3,
  "calls": [
    {
      "callId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "candidateId": "fd7d32c5-7f15-4ba8-8f83-eb718cbb3a3a",
      "candidateName": "John Doe"
    }
  ]
}

POST /api/campaigns/<str:id>/upload Upload & parse resumes ▼

Parses and reviews multiple resume documents (PDF, DOCX). Extracts contact information, total years of experience, current employer, candidate location, skills keywords, and calculates an overall ATS compatibility score using OpenAI algorithms.

Request Content Type

Must use multipart/form-data encoder mapping file fields in files array.

Payload Reference

{
  "candidates": [
    {
      "id": "fd7d32c5-7f15-4ba8-8f83-eb718cbb3a3a",
      "name": "John Doe",
      "phone": "+919876543211",
      "email": "john.doe@example.com",
      "overall_status": "pending",
      "resume_score": 85,
      "created_at": "2026-06-08T10:20:00Z"
    }
  ],
  "totalCandidates": 1,
  "uploadStats": {
    "total": 1,
    "succeeded": 1,
    "failed": 0,
    "failedFiles": []
  }
}

GET /api/campaigns/<str:id>/candidates List campaign candidates ▼

Retrieve all candidate records associated with the campaign, including parsed scores, individual call assessment scores, and active callback flags.

Payload Reference

[
  {
    "id": "fd7d32c5-7f15-4ba8-8f83-eb718cbb3a3a",
    "name": "John Doe",
    "phone": "+919876543211",
    "email": "john.doe@example.com",
    "is_deleted": false,
    "created_at": "2026-06-08T10:20:00Z",
    "overall_status": "pending",
    "shortlisted": false,
    "resume_score": 85,
    "call_1_score": null,
    "call_2_score": null,
    "last_call_id": null,
    "last_call_status": null,
    "callback_time_description": null
  }
]

POST /api/campaigns/<str:id>/candidates Add candidate manually ▼

Creates a candidate manually in the campaign database.

Payload Reference

{
  "name": "Jane Doe",
  "phone": "+19876543210",
  "email": "jane@example.com",
  "skills": "Python, Django, PostgreSQL",
  "years_of_experience": 4
}

{
  "id": "fd7d32c5-7f15-4ba8-8f83-eb718cbb3a3a",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+19876543210",
  "overall_status": "pending",
  "created_at": "2026-06-08T10:30:00Z"
}

DELETE /api/campaigns/<str:id>/candidates Delete all candidates ▼

Deletes all candidates lists and call logs inside the campaign.

Payload Reference

{
  "success": true,
  "message": "All candidates deleted",
  "deletedCount": 15
}

GET /api/candidates/<str:id> Retrieve candidate detail ▼

Retrieve parsed resume details, experience tags, and scheduling parameters for a single candidate.

Payload Reference

{
  "id": "fd7d32c5-7f15-4ba8-8f83-eb718cbb3a3a",
  "name": "Jane Doe",
  "phone": "+19876543210",
  "email": "jane@example.com",
  "overall_status": "shortlisted",
  "shortlisted": true,
  "call_1_score": 82,
  "call_2_score": null,
  "resume_score": 85,
  "assessment_date": "2026-06-15",
  "assessment_time": "14:00:00"
}

PATCH /api/candidates/<str:id>/status Modify status & shortlist ▼

Manually updates a candidate overall evaluation status and shortlist tag.

Payload Reference

{
  "overall_status": "qualified",
  "shortlisted": true
}

{
  "id": "fd7d32c5-7f15-4ba8-8f83-eb718cbb3a3a",
  "name": "Jane Doe",
  "overall_status": "qualified",
  "shortlisted": true
}

DELETE /api/candidates/<str:id> Delete single candidate ▼

Deletes a candidate record and their call transcripts.

Payload Reference

HTTP/1.1 204 No Content

GET /api/candidates/<str:id>/calls/<int:flowNumber> Get call script transcript ▼

Retrieve completed call metrics, OpenAI-generated evaluation comments, final score, transcription text, and signed recording link (AWS S3) by candidate ID and Flow number.

Payload Reference

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "GENERATED",
  "flow_number": 1,
  "started_at": "2026-06-08T10:22:00Z",
  "ended_at": "2026-06-08T10:24:30Z",
  "transcript": "Interviewer: Hello, am I speaking with Jane?... Candidate: Yes, this is Jane speaking...",
  "score": 82,
  "analysis": {
    "feedback": "Strong communication and matching skills profile.",
    "insights": ["Experienced in python development"]
  },
  "duration_seconds": 150,
  "recording_url": "https://s3.amazonaws.com/bucket/recordings/call_1.wav?AWSAccessKeyId=..."
}

POST /api/candidates/<str:candidate_id>/call/ Trigger manual candidate call ▼

Initiates a real voice call session manually to a candidate for the specified flow, setting up the Livekit RTC room and triggering the Plivo outbound calling sequence.

Request Body Fields

Property	Type	Description
flowNumber	integer	Selects whether to dial Flow 1 or Flow 2 call. Range: 1, 2. Default: 1.

Payload Reference

{
  "flowNumber": 1
}

{
  "success": true,
  "call": {
    "call_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "status": "INITIATED",
    "room_name": "room_fd7d32c5",
    "call_ref": "call-plivo-uuid-string"
  }
}

GET /api/health/ Check system status ▼

Verifies that the backend web server and relational database connectivity are operational.

Payload Reference

{
  "status": "ok"
}

GET /api/config/ Check env config status ▼

Returns check flags verifying if the external integrations API keys are loaded in the server environment settings.

Payload Reference

{
  "livekit_url": true,
  "livekit_api_key": true,
  "livekit_api_secret": true,
  "openai_api_key": true,
  "deepgram_api_key": true,
  "cartesia_api_key": true
}

GET /api/calls/<str:call_id>/transcript/ Get specific call transcript ▼

Fetch the generated transcript lines and temporary signed AWS S3 download link for the WAV recording file of a specific call by ID.

Payload Reference

{
  "callId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "transcript": "Interviewer: Hello, am I speaking with Jane?... Candidate: Yes, this is Jane speaking...",
  "status": "GENERATED",
  "startedAt": "2026-06-08T10:22:00Z",
  "endedAt": "2026-06-08T10:24:30Z",
  "recording_url": "https://s3.amazonaws.com/bucket/recordings/call_1.wav?AWSAccessKeyId=..."
}

GET /api/calls/<str:call_id>/analysis/ Get specific call analysis ▼

Retrieve details for a single call analysis score, individual criteria marks, general feedback comments, and LLM key insights.

Payload Reference

{
  "callId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "analysis": {
    "score": 82,
    "recommendation": "recommend",
    "feedback": "Strong communication and matching skills profile.",
    "evaluation": [
      {
        "criteria": "Years of experience checking",
        "score": 8,
        "candidate_answer": "4 years working on python backend projects",
        "comments": "Matches criteria"
      }
    ],
    "insights": ["Experienced in python development"]
  },
  "score": 82,
  "flowNumber": 1,
  "status": "GENERATED"
}

POST /api/calls/plivo-answer/ Plivo XML Dialing route ▼

Used internally by Plivo voice server to resolve the XML routing instructions. Binds and connects candidate call UUID into the Livekit SIP room space.

Request Parameters (Query or POST)

Property	Type	Description
room	string *req	LiveKit Room Name identifier.
call_id	string *req	Associated Call ID.

Payload Reference

<Response>
    <Dial>
        <User>sip:phone-candidateuuid@sip.livekit.cloud</User>
    </Dial>
</Response>

POST /api/calls/webhook/ Internal Agent Hook ▼

Processes internal calling event webhooks. Dispatches background threads to handle LLM completion tasks, transcripts, errors, and agent hangup cleanups.

Payload Reference

{
  "event_type": "transcript_complete",
  "call_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "transcript": "Interviewer: Hello!... Candidate: Hi..."
}

{
  "success": true
}

POST /api/webhook/livekit LiveKit external events ▼

Entrypoint for external LiveKit webhook agent calls. Processes transcription completions, rooms creation, participant actions, and errors in background.

Payload Reference

{
  "event_type": "transcript_complete",
  "call_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
  "candidate_id": "fd7d32c5-7f15-4ba8-8f83-eb718cbb3a3a",
  "flow_number": 1,
  "transcript": "Interviewer: Hi!... Candidate: Hello..."
}

{
  "received": true,
  "event_type": "transcript_complete"
}

POST /api/webhook/plivo/answer Plivo connection handler ▼

Called when Plivo dials out and gets answered by the candidate. Answers the channel and hands call over to LiveKit via SIP URI. Note: Supports both GET and POST requests.

Payload Reference

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial callerId="+918035452686">
    <Sip>sip:room_fd7d32c5@projectid.sip.livekit.cloud</Sip>
  </Dial>
</Response>

POST /api/webhook/plivo/status Telephony status hooks ▼

Webhook triggered by Plivo telephony indicating when call status updates (e.g. ringing, in-progress, completed, failed, busy, no-answer, or canceled). Automatically terminates associated Livekit rooms on hangups.

Payload Reference

{
  "CallUUID": "plivo-call-uuid-string",
  "CallStatus": "completed",
  "Duration": "120",
  "HangupCause": "callee-hangup"
}

{
  "received": true,
  "callId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "COMPLETED"
}

AI Telephone Interview Portal

Automated Interview Pipeline

Upload & ATS

Queue & Dial

Flow 1: Screening

Shortlisting

Flow 2: Technical

Environment Config Checks

JSON API Interactive Docs

Interactive CURL Code Generator