HighLevel Number Pools API

openapi: 3.2.0
info:
  title: Phone System Number Pools API
  description: Documentation for Phone System API
  version: '1.0'
  contact: {}
servers:
- url: https://services.leadconnectorhq.com
tags:
- name: Number Pools
  description: Documentation for number pools management
paths:
  /phone-system/number-pools:
    get:
      operationId: getNumberPoolList
      summary: List Number Pools
      description: Get list of number pools
      parameters:
      - name: locationId
        required: false
        in: query
        example: ve9EPM428h8vShlRW1KT
        description: Location ID to filter pools
        schema:
          type: string
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-07-28'
      responses:
        '200':
          description: Successfully retrieved number pools list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                    description: Indicates if the request was successful
                  data:
                    type: array
                    description: Array of number pool objects
                    items:
                      $ref: '#/components/schemas/NumberPoolDto'
                  total:
                    type: number
                    example: 5
                    description: Total number of pools returned
              examples:
                successful-response:
                  summary: Successful response with number pools
                  value:
                    success: true
                    data:
                    - id: ve9EPM428h8vShlRW1KT
                      name: Sales Team Pool
                      locationId: loc123
                      numbers:
                      - phoneNumber: '+14155552671'
                        friendlyName: Sales Line 1
                      forwardingNumber: '+14155552671'
                      whisper: true
                      whisperMessage: Incoming call from sales line
                      callRecording: true
                      isActive: true
                      inboundCallService:
                        type: voice_ai
                        value: 68e381b296a83800a27cd1
                    total: 1
        '400':
          description: Bad request - Invalid location ID or parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid locationId format
                  error:
                    type: string
                    example: Bad Request
                  statusCode:
                    type: number
                    example: 400
        '401':
          description: Unauthorized - Invalid or missing authentication token
        '403':
          description: Forbidden - Insufficient permissions for this location
      security:
      - Location-Access:
        - numberpools.read
      tags:
      - Number Pools
components:
  schemas:
    NumberPoolDto:
      type: object
      properties:
        id:
          type: string
          example: ve9EPM428h8vShlRW1KT
          description: Unique identifier for the number pool
        name:
          type: string
          example: Sales Team Pool
          description: Human-readable name of the number pool
        locationId:
          type: string
          example: loc123
          description: Location ID this pool belongs to
        numbers:
          type: array
          description: Phone numbers in this pool
          items:
            type: object
            properties:
              phoneNumber:
                type: string
                example: '+14155552671'
                description: E.164 formatted phone number
              friendlyName:
                type: string
                example: Sales Line 1
                description: Human-readable name for the number
        forwardingNumber:
          type: string
          example: '+14155552671'
          description: Number to forward calls to
        whisper:
          type: boolean
          example: true
          description: Whether whisper is enabled
        whisperMessage:
          type: string
          example: Incoming call from sales line
          description: Message played during whisper
        callRecording:
          type: boolean
          example: true
          description: Whether call recording is enabled
        isActive:
          type: boolean
          example: true
          description: Whether the number pool is active
        inboundCallService:
          type:
          - object
          - 'null'
          description: Inbound call service configuration
          properties:
            type:
              type: string
              example: voice_ai
              description: Type of inbound call service
            value:
              type: string
              example: 68e381b296a83800a27cd1
              description: Service configuration value/ID
  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
    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
    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
x-tagGroups:
  name: Phone System
  tags:
  - Phone Numbers
  - Number Pools