> ## Documentation Index
> Fetch the complete documentation index at: https://help.hoopai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Agents

> Retrieve a paginated list of agents for given location.



## OpenAPI

````yaml /api-reference/voice-ai/openapi.json get /voice-ai/agents
openapi: 3.0.0
info:
  title: Voice AI API
  description: Documentation for Voice AI API
  version: '1.0'
  contact: {}
servers:
  - url: https://services.leadconnectorhq.com
security: []
tags:
  - name: Voice-AI
    description: Documentation for Voice AI API
  - name: Dashboard
    description: Documentation for Voice AI API
  - name: Agents
    description: Documentation for Voice AI API
  - name: Actions
    description: Documentation for Voice AI API
paths:
  /voice-ai/agents:
    get:
      tags:
        - Agents
      summary: List Agents
      description: Retrieve a paginated list of agents for given location.
      operationId: get-agents
      parameters:
        - name: Version
          in: header
          description: API Version
          required: true
          schema:
            type: string
            enum:
              - '2021-04-15'
        - 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:
  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:
            $ref: '#/components/schemas/GetAgentResponseDTO'
      required:
        - total
        - page
        - pageSize
        - agents
    BadRequestDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 400
        message:
          type: string
          example: Bad Request
    UnauthorizedDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 401
        message:
          type: string
          example: 'Invalid token: access token is invalid'
        error:
          type: string
          example: Unauthorized
    UnprocessableDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 422
        message:
          example:
            - Unprocessable Entity
          type: array
          items:
            type: string
        error:
          type: string
          example: Unprocessable Entity
    GetAgentResponseDTO:
      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:
            - $ref: '#/components/schemas/SendPostCallNotificationSchema'
        agentWorkingHours:
          description: >-
            Time intervals when the agent accepts calls, organized by day of
            week
          example: []
          type: array
          items:
            $ref: '#/components/schemas/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:
            - $ref: '#/components/schemas/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:
            $ref: '#/components/schemas/AgentActionResponseDTO'
      required:
        - id
        - locationId
        - agentName
        - businessName
        - welcomeMessage
        - agentPrompt
        - voiceId
        - language
        - patienceLevel
        - maxCallDuration
        - sendUserIdleReminders
        - reminderAfterIdleTimeSeconds
        - timezone
        - isAgentAsBackupDisabled
        - actions
    SendPostCallNotificationSchema:
      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
    AgentWorkingHoursDTO:
      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:
            $ref: '#/components/schemas/IntervalDTO'
      required:
        - dayOfTheWeek
        - intervals
    TranslationSchema:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether translation is enabled
          example: false
        language:
          type: string
          description: Translation language code
          example: es
    AgentActionResponseDTO:
      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
          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:
            - $ref: '#/components/schemas/CallTransferActionParameters'
            - $ref: '#/components/schemas/DataExtractionActionParameters'
            - $ref: '#/components/schemas/InCallDataExtractionActionParameters'
            - $ref: '#/components/schemas/WorkflowTriggerParameters'
            - $ref: '#/components/schemas/SMSParameters'
            - $ref: '#/components/schemas/AppointmentBookingActionParameters'
            - $ref: '#/components/schemas/CustomActionParameters'
      required:
        - id
        - actionType
        - name
        - actionParameters
    IntervalDTO:
      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
    CallTransferActionParameters:
      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
    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
        overwriteExistingValue:
          type: boolean
          description: >-
            Whether to overwrite existing field value if already set, default is
            false
          example: false
          default: false
      required:
        - contactFieldId
        - description
        - examples
    InCallDataExtractionActionParameters:
      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
        overwriteExistingValue:
          type: boolean
          description: >-
            Whether to overwrite existing field value if already set, default is
            false
          example: false
          default: false
      required:
        - contactFieldId
        - description
        - examples
    WorkflowTriggerParameters:
      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
    SMSParameters:
      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
    AppointmentBookingActionParameters:
      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
    CustomActionParameters:
      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:
            - $ref: '#/components/schemas/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
        - apiDetails
    CustomActionApiDetailsDTO:
      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:
            $ref: '#/components/schemas/CustomActionHeaderDTO'
        parameters:
          description: API parameters to send
          type: array
          items:
            $ref: '#/components/schemas/CustomActionParameterDTO'
      required:
        - url
        - method
    CustomActionHeaderDTO:
      type: object
      properties:
        key:
          type: string
          description: HTTP header name
          example: id
        value:
          type: string
          description: HTTP header value
          example: '1234567890'
      required:
        - key
        - value
    CustomActionParameterDTO:
      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
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access Token or Private Integration Token

````