Get reputation status
GET/reputation
For the provided list of phone numbers, will return information if calls from those phone numbers are likely being labeled as spam due to unwanted calling behavior. Also includes engagement metrics that reflect what calling behaviors might be contributing to the spam label status. For details about labeling status and the engagement metrics, please see API Guide "Fetch reputation data for registered numbers" for more information.
Due to processing time, no more than 100 phone numbers may be provided in a single request. Phone numbers should be in E.164 format. IMPORTANT: Phone numbers must be provided using URL escaped characters. This means the + sign from E.164 phone numbers is replaced with ‘%2b’.
There is typically a service fee for every phone number requested in every request of this API.
Query Parameters
Individual phone numbers to receive current reputation status data (see below). 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".
Possible values: <= 100
Responses
- 200
- 400
- 401
- 403
- 500
OK
Response Body
Array [
]
phonesobject[]required
+1206555012311111111-1111-1111-1111-111111111111Reputation information is only available for registered phone numbers. Returns “unavailable” if reputation information is not available for this phone number. Returns “not_found” if this phone number could not be found registered to any business, or if the phone number was not properly formatted.
Possible values: [available, unavailable, not_found]
availablecurrentReputationobject
Likelihood that calls from this phone number are being labeled as spam. Values include “flagged”, “mixed_high”, “mixed_low”, and “unflagged”. See API Guide "Fetch reputation data for registered numbers" for more information.
stringPossible values: [flagged, mixed_high, mixed_low, unflagged]
flaggedA specific call purpose category; one of “Telemarketer”, “Survey”, “Debt Collector”, “Nonprofit”, or “Political”, among other uncommon values. May not always be set.
TelemarketerInfluencing factor on the phone number’s reputation: does the business consistently use this number to make calls?
maturity-metric (string)Possible values: [good, normal, poor, very_poor]
goodInfluencing factor on the phone number’s reputation: do recipients choose to answer calls from this number? This metric requires call history to be calculated, and may be null if not available.
desirability-metric (string)Possible values: [good, normal, poor, very_poor]
poorInfluencing factor on the phone number’s reputation: are recipients staying on the line after answering these calls? This metric requires call history to be calculated, and may be null if not available.
engagement-metric (string)Possible values: [good, normal, poor, very_poor]
very_poorInfluencing factor on the phone number’s reputation: do recipients rarely complain or block calls from this number? This metric requires call history to be calculated, and may be null if not available.
reaction-metric (string)Possible values: [good, normal, poor, very_poor]
very_poorExample from Schema
{
"phones": [
{
"phone": "+12065550123",
"businessId": "11111111-1111-1111-1111-111111111111",
"reputationAvailable": "available",
"currentReputation": {
"flagStatus": "flagged",
"flagCategory": "Telemarketer",
"maturityMetric": "good",
"desirabilityMetric": "poor",
"engagementMetric": "very_poor",
"reactionMetric": "very_poor"
}
}
]
}
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"
}
]
}
Forbidden
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"
}
]
}