Skip to main content

Get phone numbers

GET 

/phone

Provides business ID, job name, and registration status for phone numbers. Request supports either a list of phone numbers to be checked, or a single job name to check all phone numbers with that job name. It is not supported to provide both a list of phone numbers and a job name in the same request.

This API will paginate the response. The first page is page 0. The response will indicate how many pages of responses are available to be requested. The service provides 100 phone numbers per page.

Query Parameters​


    page integer<int32>

    Which page of results should be provided. When calling this API for the first time for a set of numbers, request page 0. Defaults to 0.


    phones string[]

    Individual phone numbers to be checked. Phone numbers must be provided using E.164 formatting and must be URL-encoded, provided as a list separated by ampersands (&). For example, "?phones=%2b12065550123&phones=%2b12065559876"


    jobName string

    Optionally a single job name to request all phone numbers with that job name. NOTE: When searching by job name, it is not supported to also provide individual phone numbers.

Responses​

OK

Response Body

application/json

    pagingobjectrequired

    currentPageintegerrequired

    Which page of results are being provided

    Format: integer<int32>
    Example: 0

    totalElementsintegerrequired

    Total quantity of phone numbers that would be available across all pages for this request.

    Format: integer<int32>
    Example: 1

    totalPagesintegerrequired

    The quantity of pages available to fetch data on all requested phone numbers.

    Format: integer<int32>
    Example: 1

    pageSizeintegerrequired

    The quantity of phone numbers per page.

    Format: integer<int32>
    Example: 100

    phonesobject[]required
  • Array [


  • businessIdstring | null

    Business ID for this phone number.

    Example: 60ff7262-d373-4242-8fc8-a3ecfb51d0c1

    phoneNumberstringrequired

    The phone number. Hiya will have standardized all provided phone numbers to E.164 format, if not already.

    Example: +12065550123

    jobNamestring | null

    Job name for this phone number.

    Example: Corporate office lines

    registeredstring | null

    Timestamp when this phone number was last registered under this business.

    Format: string<date-time>
    Example: 2024-07-29T15:51:28.071Z

    statusstringrequired

    Current registration status of this phone number. One of:

    • “pending”: Registration has not been completed
    • “registered”: Phone number is successfully registered
    • “error_invalid”: The phone number is not valid for its country and cannot be registered.
    • “error_registered”: This phone number is already registered to another business. Please contact Hiya for assistance.
    • “error_fraud”: There is record of this phone number being used for illegal call activity and cannot be registered. Please contact Hiya for assistance.
    • “error_unexpected”: Please contact Hiya for assistance.
    • “not_found”: Phone number could not be found under this account.

    Possible values: [pending, registered, error_invalid, error_registered, error_fraud, error_unexpected, not_found]

    Example: pending
  • ]

Example from Schema​

{
"paging": {
"currentPage": 0,
"totalElements": 1,
"totalPages": 1,
"pageSize": 100
},
"phones": [
{
"businessId": "60ff7262-d373-4242-8fc8-a3ecfb51d0c1",
"phoneNumber": "+12065550123",
"jobName": "Corporate office lines",
"registered": "2024-07-29T15:51:28.071Z",
"status": "pending"
}
]
}