HighLevel Dashboard API

openapi: 3.2.0
info:
  title: Voice AI Dashboard API
  description: Documentation for Voice AI API
  version: '1.0'
  contact: {}
servers:
- url: https://services.leadconnectorhq.com
tags:
- name: Dashboard
  description: Documentation for Voice AI API
paths:
  /voice-ai/dashboard/call-logs:
    get:
      operationId: get-call-logs
      summary: List Call Logs
      description: Returns call logs for Voice AI agents scoped to a location. Supports filtering by agent, contact, call type, action types, and date range (interpreted in the provided IANA timezone). Also supports sorting and 1-based pagination.
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-04-15'
      - name: locationId
        required: true
        in: query
        description: Location identifier. Filters results to this location.
        schema:
          type: string
      - name: agentId
        required: false
        in: query
        description: Agent identifier. When provided, returns logs for this agent only.
        schema:
          example: 507f1f77bcf86cd799439011
          type: string
      - name: contactId
        required: false
        in: query
        description: Contact IDs (comma-separated) to filter by.
        schema:
          example: contact123,contact456
          type: string
      - name: callType
        required: false
        in: query
        description: Call type filter.
        schema:
          enum:
          - LIVE
          - TRIAL
          type: string
      - name: startDate
        required: false
        in: query
        description: Start date filter (Unix timestamp). Must be less than endDate. Both startDate and endDate must be provided together.
        schema:
          example: 1679308800000
          type: number
      - name: endDate
        required: false
        in: query
        description: End date filter (Unix timestamp). Must be greater than startDate. Both startDate and endDate must be provided together.
        schema:
          example: 1679395199000
          type: number
      - name: actionType
        required: false
        in: query
        description: Action type filter for call logs (comma-separated ACTION_TYPE values)
        schema:
          example: SMS,CALL_TRANSFER,WORKFLOW_TRIGGER
          enum:
          - CALL_TRANSFER
          - DATA_EXTRACTION
          - IN_CALL_DATA_EXTRACTION
          - WORKFLOW_TRIGGER
          - SMS
          - APPOINTMENT_BOOKING
          - CUSTOM_ACTION
          - KNOWLEDGE_BASE
          type: string
      - name: sortBy
        required: false
        in: query
        description: Field to sort by. Defaults to newest if omitted.
        schema:
          enum:
          - duration
          - createdAt
          type: string
      - name: sort
        required: false
        in: query
        description: Sort direction. Applies only when sortBy is provided.
        schema:
          enum:
          - ascend
          - descend
          type: string
      - name: page
        required: false
        in: query
        description: Page number (1-based).
        schema:
          default: 1
          type: number
      - name: pageSize
        required: false
        in: query
        description: Page size (max 50).
        schema:
          default: 10
          type: number
      responses:
        '200':
          description: Successfully retrieved call logs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallLogsResponseDTO'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/BadRequestDTO
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
      tags:
      - Dashboard
      security:
      - bearer:
        - voice-ai-dashboard.readonly
  /voice-ai/dashboard/call-logs/{callId}:
    get:
      operationId: getCallLog
      summary: Get Call Log
      description: Returns a call log by callId.
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-04-15'
      - name: callId
        required: true
        in: path
        description: Call ID
        schema:
          example: 507f1f77bcf86cd799439011
          type: string
      - name: locationId
        required: true
        in: query
        description: Location ID
        schema:
          example: LOC123456789ABCDEF
          type: string
      responses:
        '200':
          description: Successfully retrieved call log
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallLogDTO'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/BadRequestDTO
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
      tags:
      - Dashboard
      security:
      - bearer:
        - voice-ai-dashboard.readonly
components:
  schemas:
    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
      - triggerMessage
    CallActionSchema:
      type: object
      properties:
        actionId:
          type: string
          description: Action ID reference
          example: 507f1f77bcf86cd799439015
        actionType:
          type: string
          description: Action type
          enum:
          - CALL_TRANSFER
          - DATA_EXTRACTION
          - IN_CALL_DATA_EXTRACTION
          - WORKFLOW_TRIGGER
          - SMS
          - APPOINTMENT_BOOKING
          - CUSTOM_ACTION
          - KNOWLEDGE_BASE
          example: SMS
        actionName:
          type: string
          description: Action name
          example: Send SMS Confirmation
        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'
          - $ref: '#/components/schemas/KnowledgeBaseParameters'
          examples:
            callTransfer:
              summary: Call Transfer Action Parameters
              value:
                transferToType: number
                transferToValue: '+12345678901'
                triggerMessage: Let me transfer you to a manager right away
                hearWhisperMessage: true
            sms:
              summary: SMS Action Parameters
              value:
                triggerPrompt: When caller asks for booking confirmation
                triggerMessage: I'll send you a confirmation text
                messageBody: Your appointment is confirmed for tomorrow at 2 PM
            dataExtraction:
              summary: Data Extraction Action Parameters
              value:
                contactFieldId: 507f1f77bcf86cd799439011
                description: Customer's email address
                examples:
                - john@example.com
                - jane@company.com
                overwriteExistingValue: false
            workflowTrigger:
              summary: Workflow Trigger Action Parameters
              value:
                triggerPrompt: When caller requests a quote
                triggerMessage: Let me start that process for you
                workflowId: 507f1f77bcf86cd799439020
            appointmentBooking:
              summary: Appointment Booking Action Parameters
              value:
                calendarId: 507f1f77bcf86cd799439022
                daysOfOfferingDates: 3
                slotsPerDay: 3
                hoursBetweenSlots: 1
            customAction:
              summary: Custom Action Parameters
              value:
                triggerPrompt: When caller provides order number
                triggerMessage: Let me check that order status
                apiDetails:
                  url: https://api.example.com/orders
                  method: GET
                  authenticationRequired: true
                  authenticationValue: token123
                  parameters:
                  - name: orderId
                    description: Order ID to look up
                    type: string
                    example: ORD-12345
                responsePathsToExtract:
                - data.orderId
                - status
            knowledgeBase:
              summary: Knowledge Base Action Parameters
              value:
                triggerPrompt: When caller asks about pricing
                triggerMessage: Let me look that up for you
                knowledgeBaseId: 507f1f77bcf86cd799439027
                parameters:
                - name: category
                  description: Product category to search
                  type: string
                  example: pricing
        executedAt:
          format: date-time
          type: string
          description: When the action was executed
          example: '2024-01-15T10:32:00.000Z'
        triggerReceivedAt:
          format: date-time
          type: string
          description: When the trigger was received
          example: '2024-01-15T10:31:45.000Z'
      required:
      - actionType
      - actionName
    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
    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
        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
    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
    ExtractedDataSchema:
      type: object
      properties: {}
    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
    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
    KnowledgeBaseParameters:
      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
    TranslationSchema:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether translation is enabled
          example: false
        language:
          type: string
          description: Translation language code
          example: es
    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
    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
    CallLogsResponseDTO:
      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
        callLogs:
          description: Array of call logs
          type: array
          items:
            $ref: '#/components/schemas/CallLogDTO'
      required:
      - total
      - page
      - pageSize
      - callLogs
    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
      - triggerMessage
      - apiDetails
    CallLogDTO:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the call
          example: 507f1f77bcf86cd799439011
        contactId:
          type: string
          description: Associated contact ID
          example: 507f1f77bcf86cd799439012
        agentId:
          type: string
          description: Agent ID associated with the call
          example: 507f1f77bcf86cd799439013
        isAgentDeleted:
          type: boolean
          description: Whether the agent is deleted
          example: false
        fromNumber:
          type: string
          description: Caller phone number
          example: '+1234567890'
        createdAt:
          format: date-time
          type: string
          description: Timestamp when the call was created
          example: '2024-01-15T10:30:00.000Z'
        duration:
          type: number
          description: Call duration in seconds
          example: 180
        trialCall:
          type: boolean
          description: Whether this call was a trial call
          example: false
        executedCallActions:
          description: 'Actions performed during the call. Note: The APPOINTMENT_BOOKING action will only be visible in executedCallActions from Sep 9th 2025.'
          example:
          - actionId: 507f1f77bcf86cd799439015
            actionType: CALL_TRANSFER
            actionName: Transfer to Manager
            actionParameters:
              transferToType: number
              transferToValue: '+12345678901'
              triggerMessage: Let me transfer you to a manager right away
              hearWhisperMessage: true
            executedAt: '2024-01-15T10:32:00.000Z'
            triggerReceivedAt: '2024-01-15T10:31:45.000Z'
          - actionId: 507f1f77bcf86cd799439016
            actionType: SMS
            actionName: Send Confirmation SMS
            actionParameters:
              triggerPrompt: When caller asks for booking confirmation
              triggerMessage: I'll send you a confirmation text
              messageBody: Your appointment is confirmed for tomorrow at 2 PM
            executedAt: '2024-01-15T10:33:30.000Z'
            triggerReceivedAt: '2024-01-15T10:33:15.000Z'
          - actionId: 507f1f77bcf86cd799439017
            actionType: DATA_EXTRACTION
            actionName: Extract Phone Number
            actionParameters:
              contactFieldId: 507f1f77bcf86cd799439018
              description: Customer's phone number
              examples:
              - '+1234567890'
              - '+9876543210'
              overwriteExistingValue: false
            executedAt: '2024-01-15T10:34:15.000Z'
            triggerReceivedAt: '2024-01-15T10:34:00.000Z'
          - actionId: 507f1f77bcf86cd799439019
            actionType: WORKFLOW_TRIGGER
            actionName: Start Follow-up Workflow
            actionParameters:
              triggerPrompt: When caller requests a quote
              triggerMessage: Let me start that process for you
              workflowId: 507f1f77bcf86cd799439020
            executedAt: '2024-01-15T10:35:00.000Z'
            triggerReceivedAt: '2024-01-15T10:34:45.000Z'
          - actionId: 507f1f77bcf86cd799439021
            actionType: APPOINTMENT_BOOKING
            actionName: Book Consultation
            actionParameters:
              calendarId: 507f1f77bcf86cd799439022
              daysOfOfferingDates: 3
              slotsPerDay: 3
              hoursBetweenSlots: 1
            executedAt: '2024-01-15T10:36:45.000Z'
            triggerReceivedAt: '2024-01-15T10:36:30.000Z'
          - actionId: 507f1f77bcf86cd799439023
            actionType: CUSTOM_ACTION
            actionName: Check Order Status
            actionParameters:
              triggerPrompt: When caller provides order number
              triggerMessage: Let me check that order status
              apiDetails:
                url: https://api.example.com/orders
                method: GET
                authenticationRequired: true
                authenticationValue: token123
                headers:
                - key: Content-Type
                  value: application/json
                parameters:
                - name: orderId
                  description: Order ID to look up
                  type: string
                  example: ORD-12345
              responsePathsToExtract:
              - data.orderId
              - status
            executedAt: '2024-01-15T10:37:20.000Z'
            triggerReceivedAt: '2024-01-15T10:37:05.000Z'
          - actionId: 507f1f77bcf86cd799439024
            actionType: IN_CALL_DATA_EXTRACTION
            actionName: Extract Email During Call
            actionParameters:
              contactFieldId: 507f1f77bcf86cd799439025
              description: Customer's email address
              examples:
              - john@example.com
              - jane@company.com
              overwriteExistingValue: true
            executedAt: '2024-01-15T10:31:45.000Z'
            triggerReceivedAt: '2024-01-15T10:31:30.000Z'
          - actionId: 507f1f77bcf86cd799439026
            actionType: KNOWLEDGE_BASE
            actionName: Query Product Info
            actionParameters:
              triggerPrompt: When caller asks about pricing
              triggerMessage: Let me look that up for you
              knowledgeBaseId: 507f1f77bcf86cd799439027
              parameters:
              - name: category
                description: Product category to search
                type: string
                example: pricing
            executedAt: '2024-01-15T10:38:10.000Z'
            triggerReceivedAt: '2024-01-15T10:37:55.000Z'
          type: array
          items:
            $ref: '#/components/schemas/CallActionSchema'
        summary:
          type: string
          description: Call summary
          example: Customer called to inquire about product pricing and was transferred to sales team.
        transcript:
          type: string
          description: Call transcript
          example: 'bot: Hello, how can I help you today?

            human: I would like to know about your pricing...'
        translation:
          description: Transcript translation details
          example:
            translatedTranscript: Translated version of the call transcript
          allOf:
          - $ref: '#/components/schemas/TranslationSchema'
        extractedData:
          description: Dynamic data extracted from the call based on agent configuration
          example:
            phoneNumber: '+1234567890'
            customerName: John Doe
            email: john.doe@example.com
            companyName: Acme Corp
            customField1: Custom value
            customField2: Another value
          additionalProperties: true
          allOf:
          - $ref: '#/components/schemas/ExtractedDataSchema'
        messageId:
          type: string
          description: Message identifier associated with the call
          example: 507f1f77bcf86cd799439014
      required:
      - id
      - agentId
      - isAgentDeleted
      - createdAt
      - duration
      - trialCall
      - executedCallActions
      - summary
      - transcript
  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
x-tagGroups:
  name: Voice AI
  tags:
  - Voice-AI
  - Dashboard
  - Agents
  - Actions