# List Agents GET https://services.leadconnectorhq.com/voice-ai/agents Retrieve a paginated list of agents for given location. ## Authentication Send `Authorization: Bearer ` using: - **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `voice-ai-agents.readonly` ## Parameters ### Header Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Version` | string | Yes | API Version | ### Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `page` | number | No | Page number starting from 1 | | `pageSize` | number | No | Number of items per page | | `locationId` | string | Yes | Location ID | | `query` | string | No | Query | ## OpenAPI Specification ```json { "openapi": "3.0.0", "info": { "title": "LeadConnector API", "version": "v3" }, "servers": [ { "url": "https://services.leadconnectorhq.com" } ], "paths": { "/voice-ai/agents": { "get": { "summary": "List Agents", "operationId": "listAgents", "description": "Retrieve a paginated list of agents for given location.", "parameters": [ { "name": "Version", "in": "header", "description": "API Version", "required": true, "schema": { "type": "string", "enum": [ "v3" ] } }, { "name": "page", "required": false, "in": "query", "description": "Page number starting from 1", "schema": { "minimum": 1, "maximum": 5000, "default": 1, "example": 1, "type": "number" } }, { "name": "pageSize", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 50, "default": 10, "example": 10, "type": "number" } }, { "name": "locationId", "required": true, "in": "query", "description": "Location ID", "schema": { "type": "string" } }, { "name": "query", "required": false, "in": "query", "description": "Query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent list retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAgentsResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestDTO" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedDTO" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableDTO" } } } } }, "security": [ { "bearer": [ "voice-ai-agents.readonly" ] } ] } } }, "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account.", "type": "http" }, "Agency-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.", "type": "http" }, "Agency-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Agency.", "type": "http" } }, "schemas": { "GetAgentsResponseDTO": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items", "example": 150 }, "page": { "type": "number", "description": "Page number starting from 1", "example": 2 }, "pageSize": { "type": "number", "description": "Number of items per page", "example": 10 }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the created agent", "example": "507f1f77bcf86cd799439011" }, "locationId": { "type": "string", "description": "Unique identifier for the location where this agent operates", "example": "LOC123456789ABCDEF" }, "agentName": { "type": "string", "description": "Display name of the voice AI agent", "example": "Customer Support Agent" }, "businessName": { "type": "string", "description": "Name of the business this agent represents", "example": "Acme Corporation" }, "welcomeMessage": { "type": "string", "description": "Greeting message spoken when the agent answers calls", "example": "Hello! Thank you for calling. How can I assist you today?" }, "agentPrompt": { "type": "string", "description": "Custom instructions defining the agent's behavior", "example": "You are a helpful customer service representative." }, "voiceId": { "type": "string", "description": "Identifier for the speech synthesis voice being used", "example": "507f1f77bcf86cd799439011" }, "language": { "type": "string", "description": "Language code for the agent's speech and understanding", "example": "en-US" }, "patienceLevel": { "type": "string", "description": "Current tolerance level for caller response delays", "example": "medium" }, "maxCallDuration": { "type": "number", "description": "Maximum call duration in seconds, between 180-900", "example": 600, "minimum": 180, "maximum": 900 }, "sendUserIdleReminders": { "type": "boolean", "description": "Indicates whether automatic idle reminders are enabled", "example": true }, "reminderAfterIdleTimeSeconds": { "type": "number", "description": "Seconds to wait before sending idle reminders, between 1-20", "example": 5, "minimum": 1, "maximum": 20 }, "inboundNumber": { "type": "string", "description": "Phone number for receiving inbound calls", "example": "+1234567890" }, "numberPoolId": { "type": "string", "description": "Identifier for the number pool managing this agent's phone allocation", "example": "pool_507f1f77bcf86cd799439011" }, "callEndWorkflowIds": { "description": "Array of workflow IDs triggered automatically when calls end", "example": [], "type": "array", "items": { "type": "string" } }, "sendPostCallNotificationTo": { "description": "Current post-call notification settings including recipient configuration", "allOf": [ { "type": "object", "properties": { "admins": { "type": "boolean", "description": "Send notifications to admins", "example": true }, "allUsers": { "type": "boolean", "description": "Send notifications to all users", "example": false }, "contactAssignedUser": { "type": "boolean", "description": "Send notifications to contact assigned user", "example": false }, "specificUsers": { "description": "Specific user IDs to notify", "example": [], "type": "array", "items": { "type": "string" } }, "customEmails": { "description": "Custom email addresses to notify", "example": [], "type": "array", "items": { "type": "string" } } }, "title": "SendPostCallNotificationSchema" } ] }, "agentWorkingHours": { "description": "Time intervals when the agent accepts calls, organized by day of week", "example": [], "type": "array", "items": { "type": "object", "properties": { "dayOfTheWeek": { "type": "number", "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Day of the week for this working hours configuration (Monday=1 to Sunday=7)", "example": 1 }, "intervals": { "description": "Array of time intervals when the agent is available on this day", "example": [ { "startHour": 9, "startMinute": 0, "endHour": 17, "endMinute": 30 } ], "type": "array", "items": { "type": "object", "properties": { "startHour": { "type": "number", "description": "Starting hour of the working interval in 24-hour format (0-23)", "example": 9, "minimum": 0, "maximum": 23 }, "endHour": { "type": "number", "description": "Ending hour of the working interval in 24-hour format (0-23)", "example": 17, "minimum": 0, "maximum": 23 }, "startMinute": { "type": "number", "description": "Starting minute of the working interval (0-59)", "example": 0, "minimum": 0, "maximum": 59 }, "endMinute": { "type": "number", "description": "Ending minute of the working interval (0-59)", "example": 30, "minimum": 0, "maximum": 59 } }, "required": [ "startHour", "endHour", "startMinute", "endMinute" ], "title": "IntervalDTO" } } }, "required": [ "dayOfTheWeek", "intervals" ], "title": "AgentWorkingHoursDTO" } }, "timezone": { "type": "string", "description": "IANA timezone identifier for working hours and scheduling", "example": "America/New_York" }, "isAgentAsBackupDisabled": { "type": "boolean", "description": "Indicates whether this agent is excluded from backup scenarios", "example": false }, "translation": { "description": "Current language translation settings including enablement status and target language", "allOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether translation is enabled", "example": false }, "language": { "type": "string", "description": "Translation language code", "example": "es" } }, "title": "TranslationSchema" } ] }, "actions": { "description": "Raw actions configured for this agent with complete actionParameters structure", "example": [ { "_id": "507f1f77bcf86cd799439011", "actionType": "CALL_TRANSFER", "name": "Transfer to Manager", "actionParameters": { "triggerPrompt": "When caller asks for manager", "triggerMessage": "Let me transfer you", "transferToType": "number", "transferToValue": "+1234567890" } } ], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this action", "example": "507f1f77bcf86cd799439011" }, "actionType": { "type": "string", "description": "Type of action", "enum": [ "CALL_TRANSFER", "DATA_EXTRACTION", "IN_CALL_DATA_EXTRACTION", "WORKFLOW_TRIGGER", "SMS", "APPOINTMENT_BOOKING", "CUSTOM_ACTION", "KNOWLEDGE_BASE" ], "example": "CALL_TRANSFER" }, "name": { "type": "string", "description": "Human-readable name for this action", "example": "Transfer to Manager" }, "actionParameters": { "description": "Action parameters - structure varies by actionType", "oneOf": [ { "type": "object", "properties": { "triggerPrompt": { "type": "string", "description": "When to trigger this action during the call", "example": "When the caller asks to speak to a manager" }, "transferToType": { "type": "string", "description": "Type of transfer destination (currently only \"number\" is supported)", "enum": [ "number" ], "example": "number" }, "transferToValue": { "type": "string", "description": "Phone number to transfer to. Must start with +, include country code, contain only numbers, and be 11-16 characters long (e.g., +12345678901).", "example": "+12345678901" }, "triggerMessage": { "type": "string", "description": "Message to tell the caller before transferring", "example": "Let me transfer you to a manager right away" }, "hearWhisperMessage": { "type": "boolean", "description": "Whether to play whisper message to the receiving party", "example": true } }, "required": [ "triggerPrompt", "transferToType", "transferToValue", "triggerMessage" ], "title": "CallTransferActionParameters" }, { "type": "object", "properties": { "contactFieldId": { "type": "string", "description": "ID of the contact field to be updated with the extracted data", "example": "507f1f77bcf86cd799439011" }, "description": { "type": "string", "description": "Description of what data to extract", "example": "Caller's phone number" }, "examples": { "description": "Example values to help Agent understand the expected format. At least one example is required, maximum 5 examples allowed.", "example": [ "+1234567890", "+9876543210" ], "type": "array", "items": { "type": "string" } }, "overwriteExistingValue": { "type": "boolean", "description": "Whether to overwrite existing field value if already set, default is false", "example": false, "default": false } }, "required": [ "contactFieldId", "description", "examples" ], "title": "DataExtractionActionParameters" }, { "type": "object", "properties": { "contactFieldId": { "type": "string", "description": "ID of the contact field to be updated with the extracted data", "example": "507f1f77bcf86cd799439011" }, "description": { "type": "string", "description": "Description of what data to extract", "example": "Caller's phone number" }, "examples": { "description": "Example values to help Agent understand the expected format. At least one example is required, maximum 5 examples allowed.", "example": [ "+1234567890", "+9876543210" ], "type": "array", "items": { "type": "string" } }, "overwriteExistingValue": { "type": "boolean", "description": "Whether to overwrite existing field value if already set, default is false", "example": false, "default": false } }, "required": [ "contactFieldId", "description", "examples" ], "title": "InCallDataExtractionActionParameters" }, { "type": "object", "properties": { "triggerPrompt": { "type": "string", "description": "When to trigger this workflow", "example": "When caller requests a quote" }, "triggerMessage": { "type": "string", "description": "Message to tell the caller", "example": "Let me start that process for you" }, "workflowId": { "type": "string", "description": "Workflow ID to trigger", "example": "507f1f77bcf86cd799439011" } }, "required": [ "triggerPrompt", "triggerMessage", "workflowId" ], "title": "WorkflowTriggerParameters" }, { "type": "object", "properties": { "triggerPrompt": { "type": "string", "description": "When to send the SMS", "example": "When caller asks for booking confirmation" }, "triggerMessage": { "type": "string", "description": "Message to tell the caller", "example": "I'll send you a confirmation text" }, "messageBody": { "type": "string", "description": "SMS message content to send", "example": "Your appointment is confirmed for tomorrow at 2 PM" } }, "required": [ "triggerPrompt", "triggerMessage", "messageBody" ], "title": "SMSParameters" }, { "type": "object", "properties": { "calendarId": { "type": "string", "description": "Calendar ID to book appointments in", "example": "507f1f77bcf86cd799439011" }, "daysOfOfferingDates": { "type": "number", "description": "Number of days ahead to offer booking dates", "example": 3 }, "slotsPerDay": { "type": "number", "description": "Number of available slots per day", "example": 3 }, "hoursBetweenSlots": { "type": "number", "description": "Hours between available slots", "example": 1 } }, "required": [ "calendarId", "daysOfOfferingDates", "slotsPerDay", "hoursBetweenSlots" ], "title": "AppointmentBookingActionParameters" }, { "type": "object", "properties": { "triggerPrompt": { "type": "string", "description": "When to call the custom API", "example": "When caller provides order number" }, "triggerMessage": { "type": "string", "description": "Message to tell the caller", "example": "Let me check that order status" }, "apiDetails": { "description": "API endpoint configuration", "allOf": [ { "type": "object", "properties": { "url": { "type": "string", "description": "API endpoint URL", "example": "https://api.example.com/orders" }, "method": { "type": "string", "description": "HTTP method", "example": "GET", "enum": [ "POST", "GET" ] }, "authenticationRequired": { "type": "boolean", "description": "Whether authentication is required", "example": true }, "authenticationValue": { "type": "string", "description": "Authentication token or API key (required if authenticationRequired is true)", "example": "token123" }, "headers": { "description": "HTTP headers to include", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "HTTP header name", "example": "id" }, "value": { "type": "string", "description": "HTTP header value", "example": "1234567890" } }, "required": [ "key", "value" ], "title": "CustomActionHeaderDTO" } }, "parameters": { "description": "API parameters to send", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Parameter name", "example": "orderId" }, "description": { "type": "string", "description": "Parameter description", "example": "Order ID to look up" }, "type": { "type": "string", "description": "Parameter type", "example": "string" }, "example": { "type": "string", "description": "Example parameter value", "example": "ORD-12345" } }, "required": [ "name" ], "title": "CustomActionParameterDTO" } } }, "required": [ "url", "method" ], "title": "CustomActionApiDetailsDTO" } ] }, "selectedPaths": { "description": "Selected response paths to extract from API response. Required: at least 1 value if the method is GET. Should be empty if the method is POST.", "example": [ "data.orderId", "status" ], "type": "array", "items": { "type": "string" } } }, "required": [ "triggerPrompt", "triggerMessage", "apiDetails" ], "title": "CustomActionParameters" }, { "type": "object", "properties": { "triggerPrompt": { "type": "string", "description": "When to query the knowledge base", "example": "When caller asks about pricing" }, "knowledgeBaseId": { "type": "string", "description": "Knowledge base ID to query", "example": "507f1f77bcf86cd799439011" } }, "required": [ "triggerPrompt", "knowledgeBaseId" ], "title": "KnowledgeBaseParameters" } ] } }, "required": [ "id", "actionType", "name", "actionParameters" ], "title": "AgentActionResponseDTO" } } }, "required": [ "id", "locationId", "agentName", "businessName", "welcomeMessage", "agentPrompt", "voiceId", "language", "patienceLevel", "maxCallDuration", "sendUserIdleReminders", "reminderAfterIdleTimeSeconds", "timezone", "isAgentAsBackupDisabled", "actions" ], "title": "GetAgentResponseDTO" } } }, "required": [ "total", "page", "pageSize", "agents" ], "title": "GetAgentsResponseDTO" }, "BadRequestDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Bad Request" } }, "title": "BadRequestDTO" }, "UnauthorizedDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Invalid token: access token is invalid" }, "error": { "type": "string", "example": "Unauthorized" } }, "title": "UnauthorizedDTO" }, "UnprocessableDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 422 }, "message": { "example": [ "Unprocessable Entity" ], "type": "array", "items": { "type": "string" } }, "error": { "type": "string", "example": "Unprocessable Entity" } }, "title": "UnprocessableDTO" } } } } ``` ## Code Examples **cURL** ```bash curl -L -X GET 'https://services.leadconnectorhq.com/voice-ai/agents?locationId=' \ -H 'Authorization: Bearer ' \ -H 'Version: v3' ``` **Node.js** ```javascript const options = { method: 'GET', headers: { Authorization: 'Bearer ', Version: 'v3' } }; try { const response = await fetch('https://services.leadconnectorhq.com/voice-ai/agents?locationId=', options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **Python** ```python import requests url = "https://services.leadconnectorhq.com/voice-ai/agents" headers = { "Authorization": "Bearer ", "Version": "v3" } params = { "locationId": "" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` **PHP** ```php 'https://services.leadconnectorhq.com/voice-ai/agents?locationId=', CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ', 'Version: v3', ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` **Java** ```java HttpResponse response = Unirest .get("https://services.leadconnectorhq.com/voice-ai/agents?locationId=") .header("Authorization", "Bearer ") .header("Version", "v3") .asString(); ``` **Go** ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://services.leadconnectorhq.com/voice-ai/agents?locationId=" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Version", "v3") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(string(body)) } ``` **Ruby** ```ruby require 'uri' require 'net/http' url = URI("https://services.leadconnectorhq.com/voice-ai/agents?locationId=") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = "Bearer " request["Version"] = "v3" response = http.request(request) puts response.read_body ``` **PowerShell** ```powershell $headers = @{ "Authorization" = "Bearer " "Version" = "v3" } $response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/voice-ai/agents?locationId=' -Method 'GET' -Headers $headers $response | ConvertTo-Json ```