Skip to main content

Get a phone number's billable calls by external ID

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

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

    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
    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