Skip to main content

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​


    phones string[]required

    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​

OK

Response Body

application/json

    phonesobject[]required
  • Array [


  • phonestringrequired
    Example: +12065550123

    businessIdstring
    Example: 11111111-1111-1111-1111-111111111111

    reputationAvailablestringrequired

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

    Example: available

    currentReputationobject

    flagStatusrequired

    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.

    Format: string

    Possible values: [flagged, mixed_high, mixed_low, unflagged]

    Example: flagged

    flagCategorystring

    A specific call purpose category; one of “Telemarketer”, “Survey”, “Debt Collector”, “Nonprofit”, or “Political”, among other uncommon values. May not always be set.

    Example: Telemarketer

    maturityMetricstring

    Influencing factor on the phone number’s reputation: does the business consistently use this number to make calls?

    Format: maturity-metric (string)

    Possible values: [good, normal, poor, very_poor]

    Example: good

    desirabilityMetricstring

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

    Format: desirability-metric (string)

    Possible values: [good, normal, poor, very_poor]

    Example: poor

    engagementMetricstring

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

    Format: engagement-metric (string)

    Possible values: [good, normal, poor, very_poor]

    Example: very_poor

    reactionMetricstring

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

    Format: reaction-metric (string)

    Possible values: [good, normal, poor, very_poor]

    Example: very_poor
  • ]

Example 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"
}
}
]
}