Skip to main content

Fetch reputation data for registered numbers

Once a business and its phone numbers have been registered with Hiya, this service can be used to watch for any potential labeling of calls as spam or fraud. Understanding number reputation status is a critical first step to call success.

Check reputation of any phone number​

For any verified registered phone number, the Get reputation status API call is available to check if one or more phone numbers are having calls labeled as spam. The spam labeling status is provided as one of four possible values:

  • 'flagged' (phone calls are likely being labeled as spam for most recipients)
  • 'mixed_high' (phone calls are likely being labeled as spam for some recipients, or have been labeled often in recent calls)
  • 'mixed_low' (phone calls are not likely labeled as spam, but they have been labeled in the past)
  • 'unflagged' (phone calls from this number are not labeled as spam)

Note: Spam labeling is dynamic for every phone call, not a static property of a phone number. Every call is analyzed based on historical and real-time data. Therefore, not every call from a phone number may have the same label, and the flag status is not a guarantee of future call labeling.

The spam labeling status is updated using a combination of real-time status information, as well as information on previous phone calls created in the past several days or weeks. The API favors more recent phone calls to provide an accurate reflection of current risk of being labeled as spam. The real-time status information is updated with every API request, so a recent reputation change (such as from redress) will be reflected within a few minutes. Historical flagging status is only tracked starting when a phone number is registered, so the flagging status may be less accurate (in particular, less likely to accurately differentiate between "flagged", "mixed_high", and "mixed_low") when first registered. Historical flagging information is updated every hour.

Check the number reputation report card​

The Get reputation status API call also includes several grades meant to assist the calling enterprise in understanding if their calls appear to be valuable to the recipients receiving them. In total, four reputation grades are provided in the reputation report card:

  • Maturity
  • Desirability
  • Engagement
  • Reaction

Each grade reflects the phone number’s standing in that area, as an enum “good”, “normal”, “poor”, and “very_poor”. The "maturity" grade is a reflection of how many calls the phone number has been involved in, and will use call traffic even prior to registration. Therefore, the maturity grade will always be provided and is accurate immediately for new numbers. However for "desirability", "engagement", and "reaction", the calculation of these grades only begins once a phone number is registered. Therefore, these grades will initially return null when registered until the phone number makes sufficient calls after registration. This will take a minimum of 4 hours, but may take longer (days or weeks) if the phone number does not make frequent phone calls, and may never be calculated for extremely low-volume phone numbers. The number reputation report card grades are updated hourly.