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
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.
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"
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
- 200
- 400
- 401
- 500
OK
Response Body
Array [
- “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.
]
pagingobjectrequired
Which page of results are being provided
integer<int32>0Total quantity of phone numbers that would be available across all pages for this request.
integer<int32>1The quantity of pages available to fetch data on all requested phone numbers.
integer<int32>1The quantity of phone numbers per page.
integer<int32>100phonesobject[]required
Business ID for this phone number.
60ff7262-d373-4242-8fc8-a3ecfb51d0c1The phone number. Hiya will have standardized all provided phone numbers to E.164 format, if not already.
+12065550123Job name for this phone number.
Corporate office linesTimestamp when this phone number was last registered under this business.
string<date-time>2024-07-29T15:51:28.071ZCurrent registration status of this phone number. One of:
Possible values: [pending, registered, error_invalid, error_registered, error_fraud, error_unexpected, not_found]
pendingExample 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"
}
]
}
Bad Request
Response Body
Array [
]
The unique identifier for the request. This ID can be used to track the request and its associated response.
The timestamp when the request was processed. This field indicates the exact time at which the response was generated.
string<date-time>errorsobject[]required
A list of errors that occurred during the processing of the request. This field provides detailed information about any issues encountered.
The error code that indicates the type of error that occurred. This field provides a standardized way to identify specific errors in the response.
Possible values: [INTERNAL_SERVER_ERROR, MISSING_REQUIRED_FIELD, INVALID_FIELD, DOMAIN_MISMATCH, UNAUTHORIZED, BUSINESS_ALREADY_EXISTS, BUSINESS_NOT_FOUND, BAD_REQUEST]
A human-readable description of the error. This field provides additional context or information about the error that occurred.
Example from Schema
{
"requestId": "string",
"timestamp": "2024-07-29T15:51:28.071Z",
"errors": [
{
"code": "INTERNAL_SERVER_ERROR",
"description": "string"
}
]
}
Unauthorized
Response Body
Array [
]
The unique identifier for the request. This ID can be used to track the request and its associated response.
The timestamp when the request was processed. This field indicates the exact time at which the response was generated.
string<date-time>errorsobject[]required
A list of errors that occurred during the processing of the request. This field provides detailed information about any issues encountered.
The error code that indicates the type of error that occurred. This field provides a standardized way to identify specific errors in the response.
Possible values: [INTERNAL_SERVER_ERROR, MISSING_REQUIRED_FIELD, INVALID_FIELD, DOMAIN_MISMATCH, UNAUTHORIZED, BUSINESS_ALREADY_EXISTS, BUSINESS_NOT_FOUND, BAD_REQUEST]
A human-readable description of the error. This field provides additional context or information about the error that occurred.
Example from Schema
{
"requestId": "string",
"timestamp": "2024-07-29T15:51:28.071Z",
"errors": [
{
"code": "INTERNAL_SERVER_ERROR",
"description": "string"
}
]
}
Internal Server Error
Response Body
Array [
]
The unique identifier for the request. This ID can be used to track the request and its associated response.
The timestamp when the request was processed. This field indicates the exact time at which the response was generated.
string<date-time>errorsobject[]required
A list of errors that occurred during the processing of the request. This field provides detailed information about any issues encountered.
The error code that indicates the type of error that occurred. This field provides a standardized way to identify specific errors in the response.
Possible values: [INTERNAL_SERVER_ERROR, MISSING_REQUIRED_FIELD, INVALID_FIELD, DOMAIN_MISMATCH, UNAUTHORIZED, BUSINESS_ALREADY_EXISTS, BUSINESS_NOT_FOUND, BAD_REQUEST]
A human-readable description of the error. This field provides additional context or information about the error that occurred.
Example from Schema
{
"requestId": "string",
"timestamp": "2024-07-29T15:51:28.071Z",
"errors": [
{
"code": "INTERNAL_SERVER_ERROR",
"description": "string"
}
]
}