Skip to main content

Using Reputation Data as a Service

The reputation data provided by the Number Reputation API is intended to support calling enterprises in understanding their own spam labeling, and make improvements to their reputation as a caller. It also can support monitoring and alerting on spam labeling, and can be used when seeking a review and potential removal of a spam label. This guide provides recommendations on how to use the API data based on any particular goal.

Spam Labeling Status​

The API provides spam labeling status as one of four values: "flagged", "mixed_high", "mixed_low", and "unflagged". This is because the spam label status for a phone number is not static, but rather dynamic. Each call is evaluated individually and may have a different spam label. These spam label statuses imply certain common situations:

  • flagged: It is highly likely if the phone number made a call right now, it will be labeled as spam. This tier is used for any phone number that is labeled spam right now by a real-time reputation check, and either has made no previous calls (so is being labeled due to maturity; see below), or many recent calls were labeled (showing this is a persistent state for the number.)

  • mixed_high: Mixed-high is not a common state for a phone number; usually it reflects a transition. These phone numbers either are being labeled spam but that is unusual compared to previous calls, or it is not being labeled spam now but has frequently been labeled in the past. Often, this either reflects a number that just started being labeled (and soon will just be "flagged"), or a number where labeling was just recently removed, such as due to redress (see below).

  • mixed_low: Mixed-low is not a common state for a phone number. In this state the phone number is not being labeled as spam right now and hasn't been labeled as spam often in previous calls, but at least some calls have been labeled. This usually reflects a number where labeling has been removed and soon the number will simply be "unflagged".

  • unflagged: The phone number is not labeled now, nor has it been labeled in recent calls. There is no current reputation issue for this number.

Monitoring and alerting on spam labeling status​

If an API customer wishes to provide a service that monitors for spam labeling status across registered phone numbers, Hiya recommends monitoring for any phone number that is in either the flagged or mixed_high spam labeling status. Any number transitioning from "unflagged" or "mixed_low" to either "mixed_high" or "flagged" is likely a reflection that the number has begun being labeled as spam. It's not advised to wait until a number reaches "flagged" status as this may take a while depending on the call volume of the number.

Spam labeling status includes a real-time spam status check, so labeling status can be queried anytime to confirm current labeling status. This may be especially useful after the redress process. Spam labeling is based on at least the past 1 week of phone calls, so will take at minimum 1 week for a phone number to fully transition from "flagged" to "unflagged" if spam labeling is removed (although the number will drop immediately from "flagged" down to "mixed_high" as soon as the label is removed. For this reason, it may be worthwhile to track what numbers have received redress and are now in "mixed_high" as a result).

Phone numbers with a history of spam labeling are more likely to be labeled in the future, even if they have been granted redress. Hiya suggests monitoring these numbers more closely (daily or several times a day) and note any change in spam labeling status.

Requesting redress to remove a spam label​

Any phone number labeled as spam by Hiya's service is eligible to request "redress", or a removal of that spam label. This request must be provided to Hiya by filling out the form at https://hiyahelp.zendesk.com/hc/en-us/requests/new?ticket_form_id=32894877171859. Some recommendations on this form:

  • This form may be used for phone numbers of multiple businesses at once. Please provide the business information of the requesting business in the form fields.
  • Up to 2,000 phone numbers may be requested at once, by including numbers as a plaintext attachment.
  • To avoid unnecessary delay, ensure phone numbers use proper E.164 format (for example, "+1 2065550123").
  • Ensure requests are made in good faith. This means both that (a) it's known these numbers are being labeled as spam (via the API), and that (b) there is reasonable belief these calls are wanted by recipients.

The spam review process generally takes 2-4 hours, although may be longer if many phone numbers are currently being processed. Hiya will email the results of the review to the contact information provided in the form; Hiya will not reference registered business information and will not email the primary contact associated with the business, only the person referenced in the redress request. Once reviewed, phone numbers are not eligible for redress again for 60 days unless it can be demonstrated that there is a material change in the calling circumstances. More information on redress is available in the API Service Management overview provided with an API key.

Report Card Grades​

The report card grades provided by the Reputation API can be a valuable tool to assist a calling enterprise in understanding why they might struggle with a spam labeling problem. The "maturity" grade indicates numbers that might be flagged due to poor overall calling behavior, while "desirability", "engagement", and "reaction" grades are a direct reflection of how recipients feel about the calls they're receiving from this phone number specifically. Poor grades can be used to provide support in identifying issues with calling practices that can fix both current and future reputation issues.

How report card grades are calculated​

Each report card grade is calculated based off of observed phone calls created by the registered phone number. The "maturity" grade is calculated including phone calls that occurred prior to registration, so a recently-registered phone number may immediately have a high maturity grade. However, the "desirability", "engagement", and "reaction" grades are only calculated using phone calls that take place after registration. It will take at least 4 hours but potentially multiple days for these grades to be available, depending on how many calls a number is creating. A minimum number of observed calls are required, so it is possible for low-call-volume numbers that these metrics will never be calculated.

Using "maturity" grade to understand spam labeling​

One common situation for businesses is to observe a phone number that is known to not have made any recent phone calls, but has a "flagged" spam labeling status. These numbers will also have a "very_poor" maturity grade, and all other grades are null.

This spam labeling is the result of number rotation protections in place against immature phone numbers. If a registered phone number has no call history of its own, Hiya's service may review the sentiment of other, active phone numbers from the same business. This is calculated as an overall reputation of the entire registered business. If a business has a poor reputation for the calls made with its other phone numbers, it is assumed that new numbers will be used in a similar manner and so receive spam flagging status as a reflection of that poor business reputation.

If a business is seeing this number rotation flagging on immature phone numbers, the best course of action is to review the calling practices and report card grades of all their phone numbers to identify the underlying problem in their calling practices. Phone numbers are considered mature after only 6-10 phone calls observed by Hiya, so the best practice is simply to start using the phone number and the label should be removed if the number creates wanted phone calls.

Note: The maturity grade reflects all call activity from a phone number, even before registration. However the other three grades only reflect call traffic from the time of registration. Therefore, recently-registered phone numbers may have a high maturity grade but be unable to show the other three grades until enough call traffic is observed.

Using "desirability", "engagement", and "reaction" grades to understand spam labeling​

These grades directly reflect the quality of recipient interaction with calls being created by a phone number. Poor answer rates, quick hangups, or negative reports / requests to block all future calls are all strong indicators a caller may be calling the wrong people, at the wrong time, or for the wrong reasons. This can often help explain a spam label.

  • Desirability: This grade, based on the reactions of call recipients to calls from this number, shows whether recipients of calls from this number tend to answer the phone when called from this number. It can indicate if the recipients are expecting or want to receive this call. A poor or very_poor grade indicates that calls go unanswered by this number more often than similar phone numbers.

  • Engagement: This grade, based on the reactions of call recipients to calls from this number, reflects if recipients tend to stay on the line when they answer the call. It can be an indicator that recipients are engaging with the inbound call and having a meaningful conversation. A poor or very_poor grade indicates that calls by this number have shorter durations than calls from similar phone numbers.

  • Sentiment: This grade, based on the reactions of recipients to calls from this number, reflects if recipients appear to want any lasting association with the caller. In particular, this can be a reflection if recipients choose to block any future calls, possibly also raising a report against the caller. A poor or very_poor grade indicates that this number is reported as spam or is blocked from creating future phone calls more often than similar phone numbers.

Note: Hiya has published The Definitive Guide to Caller Reputation which outlines how calling behavior affects the reputation report card grades, and how to identify possible specific problems with calling behavior. Also, the Best Practices Guide for enterprises outlines general policies on good and bad calling behavior.