HighLevel Phone Numbers API

openapi: 3.2.0
info:
  title: Phone System Phone Numbers API
  description: Documentation for Phone System API
  version: '1.0'
  contact: {}
servers:
- url: https://services.leadconnectorhq.com
tags:
- name: Phone Numbers
  description: Documentation for phone numbers management
paths:
  /phone-system/numbers/location/{locationId}/available:
    get:
      operationId: available-numbers
      summary: List available phone numbers
      description: Search for available phone numbers to purchase for a specific location. Supports filtering by number pattern, type, and capabilities.
      parameters:
      - name: locationId
        in: path
        description: The unique identifier of the location
        required: true
        schema:
          type: string
        example: ve9EPM428h8vShlRW1KT
      - name: countryCode
        in: query
        description: ISO 3166-1 alpha-2 country code for which to search available numbers
        required: true
        schema:
          type: string
        example: US
      - name: numberTypes
        in: query
        description: Comma-separated list of phone number types to search for (e.g. local, tollFree, mobile)
        required: false
        schema:
          type: string
        example: local,tollFree
      - name: firstPart
        in: query
        description: Filter numbers that begin with this digit pattern
        required: false
        schema:
          type: string
        example: '830'
      - name: lastPart
        in: query
        description: Filter numbers that end with this digit pattern
        required: false
        schema:
          type: string
        example: '825'
      - name: anywhere
        in: query
        description: Filter numbers that contain this digit pattern anywhere
        required: false
        schema:
          type: string
        example: '825'
      - name: smsEnabled
        in: query
        description: Filter for numbers with SMS capability
        required: false
        schema:
          type: boolean
        example: true
      - name: mmsEnabled
        in: query
        description: Filter for numbers with MMS capability
        required: false
        schema:
          type: boolean
        example: true
      - name: voiceEnabled
        in: query
        description: Filter for numbers with voice capability
        required: false
        schema:
          type: boolean
        example: true
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-07-28'
      responses:
        '200':
          description: Successfully retrieved list of available phone numbers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableNumbersResponseDto'
              examples:
                successful-response:
                  summary: Successful response with available numbers
                  value:
                    fingerprintId: '1773314252953'
                    numbers:
                    - phoneNumber: '+18705871861'
                      friendlyName: (870) 587-1861
                      lata: '528'
                      locality: Wynne
                      rateCenter: WYNNE
                      latitude: '35.241800'
                      longitude: '-90.846000'
                      region: AR
                      postalCode: '72396'
                      isoCountry: US
                      addressRequirements: none
                      beta: false
                      capabilities:
                        MMS: true
                        SMS: true
                        voice: true
                      price:
                        number_type: local
                        price: 1.15
                        price_unit: USD
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: countryCode is required
                  error:
                    type: string
                    example: Bad Request
                  statusCode:
                    type: number
                    example: 400
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
        '500':
          description: Internal server error
      security:
      - Location-Access:
        - phonenumbers.read
      tags:
      - Phone Numbers
  /phone-system/numbers/location/{locationId}/purchase:
    post:
      operationId: purchase-phone-number
      summary: Purchase a phone number
      description: Purchase a phone number for a specific location.
      parameters:
      - name: locationId
        in: path
        description: The unique identifier of the location
        required: true
        schema:
          type: string
        example: ve9EPM428h8vShlRW1KT
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-07-28'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchasePhoneNumberBodyDto'
            examples:
              purchase-local-number:
                summary: Purchase a local US number
                value:
                  phoneNumber: '+18305551234'
                  countryCode: US
                  numberType: local
      responses:
        '201':
          description: Phone number successfully purchased. Returns the updated Twilio account state for the location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TwilioAccountResponseDto'
              examples:
                successful-response:
                  summary: Successful purchase response
                  value:
                    id: 8xMPW85D2z5jgcTa5L1p
                    account_sid: ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                    under_ghl_account: true
                    validate_sms: true
                    location_id: aa4PBpxnPc9bs4LSdiW7
                    migration_numbers: []
                    assigned_to_numbers: {}
                    numbers:
                      '+18705871861': conversation
                    number_name:
                      '+18705871861': My Number
                    new_account_sid: ''
        '400':
          description: Bad request - Invalid parameters or number unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Phone number is no longer available
                  error:
                    type: string
                    example: Bad Request
                  statusCode:
                    type: number
                    example: 400
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
        '500':
          description: Internal server error - An unexpected error occurred while purchasing the phone number
      security:
      - Location-Access:
        - phonenumbers.write
      tags:
      - Phone Numbers
  /phone-system/numbers/location/{locationId}:
    get:
      operationId: active-numbers
      summary: List active numbers
      description: Retrieve a paginated list of active phone numbers for a specific location. Supports filtering, pagination, and optional exclusion of number pool assignments.
      parameters:
      - name: locationId
        in: path
        description: The unique identifier of the location
        required: true
        schema:
          type: string
        example: ve9EPM428h8vShlRW1KT
      - name: pageSize
        in: query
        description: How many resources to return in each list page. The default is 50, and the maximum is 1000.
        required: false
        schema:
          type: number
          minimum: 1
          maximum: 1000
          default: 1000
        example: 100
      - name: page
        in: query
        description: The page index for pagination. The default is 0.
        required: false
        schema:
          type: number
          minimum: 0
          default: 0
        example: 0
      - name: searchFilter
        in: query
        description: Filter numbers by phone number pattern. Supports partial matching (e.g., "+91" to find all Indian numbers).
        required: false
        schema:
          type: string
        example: '+91'
      - name: skipNumberPool
        in: query
        description: Whether to exclude numbers that are assigned to number pools. Default is true.
        required: false
        schema:
          type: boolean
          default: true
        example: true
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-07-28'
      responses:
        '200':
          description: Successfully retrieved list of active numbers
          content:
            application/json:
              schema:
                type: object
                properties:
                  numbers:
                    type: array
                    description: Array of phone number objects with detailed configuration
                    items:
                      $ref: '#/components/schemas/DetailedPhoneNumberDto'
                  isUnderGhl:
                    type: boolean
                    description: Whether this account is manged by LeadconnectorHQ
                    example: true
                  pageSize:
                    type: number
                    description: Number of items requested per page
                    example: 100
                    minimum: 1
                    maximum: 1000
                  page:
                    type: number
                    description: Current page index (0-based)
                    example: 0
                    minimum: 0
                  accountStatus:
                    type: string
                    description: Current status of the account
                    example: active
                    enum:
                    - active
                    - suspended
                    - closed
                required:
                - numbers
                - isUnderGhl
                - pageSize
                - page
                - accountStatus
              examples:
                successful-response:
                  summary: Successful response with phone numbers
                  value:
                    numbers:
                    - phoneNumber: '+14155552671'
                      friendlyName: Sales Line 1
                      sid: PN1234567890abcdef1234567890abcde
                      countryCode: US
                      capabilities:
                        voice: true
                        sms: true
                        mms: true
                        fax: false
                      type: local
                      isDefaultNumber: true
                      linkedUser: user_123456789
                      linkedRingAllUsers:
                      - user_123
                      - user_456
                      inboundCallService:
                        type: voice_ai
                        value: 68e381b296a83800a27cd1
                      forwardingNumber: '+14155552672'
                      isGroupConversationEnabled: true
                      addressSid: AD1234567890abcdef1234567890abcde
                      bundleSid: BU1234567890abcdef1234567890abcde
                      dateAdded: '2023-01-15T10:30:00Z'
                      dateUpdated: '2023-02-20T14:45:00Z'
                      origin: twilio
                    - phoneNumber: '+18005551234'
                      friendlyName: Support Toll-Free
                      sid: PN9876543210fedcba9876543210fedcb
                      countryCode: US
                      capabilities:
                        voice: true
                        sms: false
                        mms: false
                        fax: false
                      type: toll-free
                      isDefaultNumber: false
                      linkedUser: null
                      linkedRingAllUsers:
                      - user_789
                      - user_101
                      inboundCallService: null
                      forwardingNumber: null
                      isGroupConversationEnabled: false
                      addressSid: null
                      bundleSid: null
                      dateAdded: '2023-01-16T14:20:00Z'
                      dateUpdated: '2023-01-16T14:20:00Z'
                      origin: twilio
                    isUnderGhl: true
                    pageSize: 100
                    page: 0
                    accountStatus: active
                empty-response:
                  summary: Response when no numbers are found
                  value:
                    numbers: []
                    total: 0
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid locationId format or pagination parameters
                  error:
                    type: string
                    example: Bad Request
                  statusCode:
                    type: number
                    example: 400
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
        '404':
          description: Phone system not connected
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Phone system is not connected to this account
                  statusCode:
                    type: number
                    example: 404
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    example: Internal server error
                  accountStatus:
                    type: string
                    example: suspended
                    description: Account status when error occurs
      security:
      - Location-Access:
        - phonenumbers.read
      tags:
      - Phone Numbers
components:
  schemas:
    AvailableNumbersResponseDto:
      type: object
      properties:
        fingerprintId:
          type: string
          description: Unique fingerprint ID for this search result, required when purchasing one of the returned numbers
          example: '1773314252953'
        numbers:
          type: array
          description: List of available phone numbers matching the search criteria
          items:
            $ref: '#/components/schemas/AvailablePhoneNumberDto'
      required:
      - fingerprintId
      - numbers
    AvailablePhoneNumberDto:
      type: object
      properties:
        phoneNumber:
          type: string
          description: E.164 formatted phone number
          example: '+18705871861'
        friendlyName:
          type: string
          description: Human-readable formatted phone number
          example: (870) 587-1861
        isoCountry:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: US
        lata:
          type:
          - string
          - 'null'
          description: Local Access and Transport Area code
          example: '528'
        locality:
          type:
          - string
          - 'null'
          description: City or locality of the number
          example: Wynne
        rateCenter:
          type:
          - string
          - 'null'
          description: Rate center of the number
          example: WYNNE
        latitude:
          type:
          - string
          - 'null'
          description: Latitude coordinate of the number's location
          example: '35.241800'
        longitude:
          type:
          - string
          - 'null'
          description: Longitude coordinate of the number's location
          example: '-90.846000'
        region:
          type:
          - string
          - 'null'
          description: State or region abbreviation
          example: AR
        postalCode:
          type:
          - string
          - 'null'
          description: Postal code of the number
          example: '72396'
        addressRequirements:
          type: string
          description: Address requirements for purchasing this number
          example: none
          enum:
          - none
          - any
          - local
          - foreign
        beta:
          type: boolean
          description: Whether this is a beta number
          example: false
        capabilities:
          type: object
          description: Communication capabilities supported by this number
          properties:
            MMS:
              type: boolean
              example: true
            SMS:
              type: boolean
              example: true
            voice:
              type: boolean
              example: true
        price:
          type: object
          description: Pricing information for this number
          properties:
            number_type:
              type: string
              description: Type of number for billing purposes
              example: local
            price:
              type: number
              description: Monthly price for this number
              example: 1.15
            price_unit:
              type: string
              description: Currency unit for the price
              example: USD
      required:
      - phoneNumber
      - friendlyName
      - isoCountry
      - addressRequirements
      - beta
      - capabilities
    PurchasePhoneNumberBodyDto:
      type: object
      properties:
        phoneNumber:
          type: string
          description: The phone number to purchase
          example: '+18305551234'
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code of the number
          example: US
        numberType:
          type: string
          description: Type of phone number
          example: local
          enum:
          - local
          - tollFree
          - mobile
        addressSid:
          type:
          - string
          - 'null'
          description: Twilio address SID for compliance
          example: AD1234567890abcdef1234567890abcde
        bundleSid:
          type:
          - string
          - 'null'
          description: Twilio bundle SID for regulatory compliance
          example: BU1234567890abcdef1234567890abcde
        locality:
          type:
          - string
          - 'null'
          description: Locality where the number is being purchased
          example: San Antonio
        region:
          type:
          - string
          - 'null'
          description: Region where the number is being purchased
          example: TX
        fingerprintId:
          type:
          - string
          - 'null'
          description: Unique request ID for idempotency (fingerprint of the purchase request)
          example: fp_abc123def456
        skipLocationKYC:
          type:
          - boolean
          - 'null'
          description: Skip location-level KYC verification if agency-level compliance has already been verified
          example: false
      required:
      - phoneNumber
    DetailedPhoneNumberDto:
      type: object
      properties:
        phoneNumber:
          type: string
          description: E.164 formatted phone number
          example: '+14155552671'
        friendlyName:
          type:
          - string
          - 'null'
          description: Human-readable name assigned to the number
          example: Sales Line 1
        sid:
          type: string
          description: Phone number SID (unique identifier)
          example: PN1234567890abcdef1234567890abcde
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: US
        capabilities:
          type: object
          description: Communication capabilities supported by this number
          properties:
            voice:
              type: boolean
              description: Whether the number supports voice calls
              example: true
            sms:
              type: boolean
              description: Whether the number supports SMS messaging
              example: true
            mms:
              type: boolean
              description: Whether the number supports MMS messaging
              example: true
            fax:
              type: boolean
              description: Whether the number supports fax transmission
              example: false
        type:
          type: string
          description: Type of phone number (local, toll-free, mobile, etc.)
          example: local
          enum:
          - local
          - toll-free
          - mobile
          - national
        isDefaultNumber:
          type: boolean
          description: Whether this is the default outbound number for the location
          example: false
        linkedUser:
          type:
          - string
          - 'null'
          description: User ID of the user assigned to this number
          example: user_123456789
        linkedRingAllUsers:
          type: array
          description: Array of user IDs that should ring when this number is called
          items:
            type: string
          example:
          - user_123
          - user_456
        inboundCallService:
          type:
          - object
          - 'null'
          description: Configuration for inbound call handling service
          properties:
            type:
              type: string
              description: Type of inbound call service
              example: voice_ai
              enum:
              - voice_ai
              - ivr
              - forward
            value:
              type: string
              description: Service configuration value or ID
              example: 68e381b296a83800a27cd1
        forwardingNumber:
          type:
          - string
          - 'null'
          description: Phone number to forward calls to
          example: '+14155552672'
        isGroupConversationEnabled:
          type: boolean
          description: Whether group conversations are enabled for this number (US/CA numbers with SMS/MMS only)
          example: true
        addressSid:
          type:
          - string
          - 'null'
          description: Address SID for compliance purposes
          example: AD1234567890abcdef1234567890abcde
        bundleSid:
          type:
          - string
          - 'null'
          description: Bundle SID for regulatory compliance
          example: BU1234567890abcdef1234567890abcde
        dateAdded:
          type: string
          format: date-time
          description: When the number was originally purchased/added
          example: '2023-01-15T10:30:00Z'
        dateUpdated:
          type: string
          format: date-time
          description: When the number configuration was last updated
          example: '2023-02-20T14:45:00Z'
        origin:
          type: string
          description: Source or origin of the phone number
          example: twilio
          enum:
          - twilio
          - hosted
          - ported
      required:
      - phoneNumber
      - sid
      - countryCode
      - capabilities
      - type
      - isDefaultNumber
      - linkedRingAllUsers
      - isGroupConversationEnabled
    TwilioAccountResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the Twilio account record
          example: 8xMPW85D2z5jgcTa5L1p
        account_sid:
          type: string
          description: Twilio Account SID
          example: ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        under_ghl_account:
          type: boolean
          description: Whether this location is under a GHL-managed Twilio account
          example: true
        validate_sms:
          type: boolean
          description: Whether SMS validation is enabled
          example: true
        location_id:
          type: string
          description: The location ID this Twilio account belongs to
          example: aa4PBpxnPc9bs4LSdiW7
        migration_status:
          type:
          - string
          - 'null'
          description: Current migration status of the account
          example: completed
        migration_numbers:
          type: array
          description: List of numbers being migrated
          items:
            type: string
          example: []
        assigned_to_numbers:
          type: object
          description: Map of phone numbers to assigned user IDs
          additionalProperties:
            type: string
          example: {}
        numbers:
          type: object
          description: Map of phone numbers to their service type (e.g. 'conversation')
          additionalProperties:
            type: string
          example:
            '+18705871861': conversation
        number_name:
          type: object
          description: Map of phone numbers to their friendly names
          additionalProperties:
            type: string
          example:
            '+18705871861': My Number
        new_account_sid:
          type:
          - string
          - 'null'
          description: New account SID if the account has been migrated to new credentials
          example: ''
      required:
      - id
      - account_sid
      - under_ghl_account
      - validate_sms
      - location_id
      - numbers
  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