Skip to main content

Get a phone number's billable calls by business ID

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

Returns billable call counts for one phone number of a business, identified by the business's Hiya businessId, over the given date range, bucketed by granularity. Works for any number that was registered to this business at some point in the range (total is 0 if it had no billable calls in the range). A number that was not registered to this business during the range returns 404.

Path Parameters​

    businessId string<uuid>required

    The ID of the business, assigned by Hiya.

    Example: 9b8a1c4e-2c0f-4f3d-9a1e-7b3a2b4c6d8f
    phoneNumber billing_E164PhoneNumber (string)required

    The number in E.164 format. Percent-encode the leading 

    +
    as 
    %2B
    in the URL path (
    %2B12065550123
    ).

    Possible values: Value must match regular expression ^\+[1-9]\d{1,14}$

    Example: +12065550123

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

Responses​

The phone number's billable call counts.

Response Body

application/json