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. A number without billable calls for this business in the range returns 404, the same as a number that isn't this business's.

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

    An E.164 phone number, URL-encoded — the leading

    +
    becomes
    %2B
    (e.g.
    %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 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