Skip to main content

List a business's phone numbers with their billable calls, by external ID

GET 
/v1/businesses/external-id/{externalId}/billable-calls/phone-numbers

Returns billable call counts for every phone number of a business, identified by your own externalId, 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​

    externalId stringrequired

    Your own reference for the business, optionally supplied when it was created. Restricted to letters, digits, 

    .
    , 
    _
    , and 
    -
    so it is safe to use in a URL path. Only resolves businesses for which you set an 
    externalId
    ; a business created without one is addressable only by its Hiya 
    businessId
    , and an unknown 
    externalId
    returns 
    404
    .

    Possible values: non-empty and <= 200 characters, Value must match regular expression ^[A-Za-z0-9._-]+$

    Example: partner-customer-7421

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