Skip to main content

List a business's phone numbers with their billable calls

GET 
/v1/businesses/{businessId}/billable-calls/phone-numbers

Returns billable call counts for every phone number of a business, identified by the business's Hiya businessId, that had at least one billable call in the given date range, bucketed by granularity. Sortable by phone number or by billable calls; paged. Numbers without billable calls in the range are not listed; use the single-number endpoint to look up a specific number (it returns 0 for a number of yours that had no billable calls).

Path Parameters​

    businessId string<uuid>required

    The ID of the business, assigned by Hiya.

    Example: 9b8a1c4e-2c0f-4f3d-9a1e-7b3a2b4c6d8f

Query Parameters​

    startDate string<date>required

    Start of the date range (inclusive), as 

    YYYY-MM-DD
    . Must be on or before 
    endDate
    . 
    endDate
    may be at most 
    startDate
    plus 15 months, with the day clamped to the end of the month (2026-01-31 → 2027-04-30).

    Example: 2026-05-01
    endDate string<date>required

    End of the date range (inclusive), as 

    YYYY-MM-DD
    . Must be on or after 
    startDate
    . 
    endDate
    may be at most 
    startDate
    plus 15 months, with the day clamped to the end of the month (2026-01-31 → 2027-04-30).

    Example: 2026-05-31
    granularity billing_Granularity (string)

    How to bucket the returned series. Defaults to 

    total
    (no series, just the total for the range).

    Possible values: [total, day, week, month]

    Default value: total
    sortBy string

    Field to sort the phone-number list by. 

    phoneNumber
    sorts by the number as a string, 
    total
    by the billable calls for the range. Ties are broken by phone number, ascending regardless of 
    sortDirection
    .

    Possible values: [phoneNumber, total]

    Default value: phoneNumber
    Example: total
    sortDirection string

    Sort direction. 

    asc
    or 
    desc
    (case-insensitive).

    Possible values: Value must match regular expression ^[Aa][Ss][Cc]$|^[Dd][Ee][Ss][Cc]$

    Default value: asc
    page integer

    Page number, starting at 0. A page past the end returns 

    200
    with an empty list and unchanged 
    paging
    totals.

    Possible values: >= 0 and <= 100000

    Default value: 0
    size integer

    Number of items per page.

    Possible values: >= 1 and <= 200

    Default value: 50

Responses​

A page of per-phone-number billable call counts.

Response Body

application/json