Skip to main content

Get Profile Phones Cache

GET 
/v1/caches/phones

Downloads a country-specific gzipped TSV file (.tsv.gz) of phone profile data. The response is a 307 redirect to a signed URL that expires in 30 seconds.

The file contains seven tab-separated columns: phone number, reputation level (SPAM, FRAUD, or NEUTRAL), reputation category ID (integer; may be empty), display name, display description, display detail, and display image.

Terms of usage of API: Before you use the Hiya API you must sign and agree with our terms of use that should have been provided in a different document. Use of the Hiya API requires partners to include Hiya's use of data policy either in your Terms of Service, or by making the policy accessible to end users in your app via a screen or link. This is necessary for GDPR and other privacy laws. The content or the link will be provided to you. Hiya is not liable for the use of the API responses.

Introduction​

This document describes the usage of the Hiya Protect Cache API to support local server caches of phone profile data. API integrators may download a country-specific set of phone numbers with their associated reputation levels, categories, and display information.

Get Profile Phones Cache​

Successful requests to the API will return an HTTP status code of 307 'Temporary Redirect'. This response will include a signed URL in the Location header as well as in the body of the request.

The Integrator will need to perform a GET request using the returned URL within 30 seconds, after which the URL will expire and become unusable. In this case, the integrator must make a new API request.

Successful GET requests will return an HTTP status code of 200 OK. Requests made to an expired URL will return a 403 Forbidden response. In very rare cases requests may return a 404 Unknown response. In this case, there has been an error in the process generating the cache file. You may retry the API request after an hour.

The returned cache filename is not meant to be meaningful, and can change over time. Do not rely on a filename for any local comparison operations.

The file will be a gzipped TSV file (.tsv.gz) with seven tab-separated columns:

  • Phone Number: formatted with a forward-slash between country code and national part (e.g. 91/9876543210)
  • Reputation Level: One of three values:
    • FRAUD: A call that Hiya predicts is likely intended to harm the user, such as attempting to steal identity, collect banking or credit card information, or commit extortion.
    • SPAM: A nuisance call that does not rise to the level of FRAUD.
    • NEUTRAL: The reputation was neutral. Hiya cannot ascertain with 100% accuracy that the call is safe — do not display it as verified or zero-risk.
  • Reputation Category: This information will not appear for all numbers in the returned file, as the Hiya Protect solution cannot make a definitive categorization determination for every call analyzed. The reputation category is provided as an integer in the returned file. The current mapping of integer to category is listed in the following table. An integrator's use of these categorizations is entirely at their discretion.
  • Display Name: caller or business name; may be empty
  • Display Description: additional description; may be empty
  • Display Detail: supplementary detail; may be empty
  • Display Image: URL of an associated image; may be empty
IntegerReputation Category
3Debt Collector
4Political Call
5Nonprofit Call
6Telemarketer
7Survey Call
8Scam
9Extortion Scam
10Robocaller
1000Phishing
1001Toll Free
1002Stolen Identity
1003IRS Scam
1004Tax Scam
1005Tech Support Scam
1006Vacation Scam
1007Lucky Winner Scam

Hiya reserves the right to add new reputation categories in the future, so integrators must gracefully handle cases when a reputation category integer not in the current mapping is returned. If you do receive an unexpected reputation category integer, feel free to reach out to Hiya for an updated table.

Supported Countries​

The country query parameter is required and must be uppercase. Supported ISO 3166-1 alpha-2 country codes:

AF, BD, BR, BT, DZ, EG, GH, HK, ID, IL, IN, IQ, JO, JP, KE, KG, KH, KZ, LA, LB, LK, MA, MM, MY, NG, NP, PG, PH, PK, PS, SA, SG, TH, TN, TR, TW, VN, YE, ZA

Example​

91/9876543210 SPAM 6 Example Telemarketer

91/9123456789 FRAUD 8 Scam Caller

91/9000000001 SPAM Company Name

eTags​

When following the redirected URL returned in the Location header from a 307 response, you can utilize ETags to prevent re-downloading the entire cache if it hasn't changed since the last time you downloaded it.

A standard flow for utilizing ETags is:

  1. Store the ETag from your first request
  • Request /v1/caches/phones?country=IN
  • Follow 307 Location signed url to download the cache
  • Read the HTTP response header called ETag from the response (after following redirect) and store it locally
  1. Add the ETag on subsequent requests in If-None-Match HTTP header when following the 307 redirect
  • Request /v1/caches/phones?country=IN
  • Follow 307 Location signed url with If-None-Match: YOUR_ETAG_HERE HTTP header to download the cache
  • If the cache contents haven't changed, you will receive 304 Not Modified response
  • If the cache contents have changed, you will receive the new cache contents and an updated ETag response header value (which you store locally for next request)

Some HTTP clients might do automatic redirection following the 307 response, with clients like this, you won't need to handle the multiple requests in your code. Here is a Python requests library example.

response = requests.get(
    'https://api.hiyaapi.com/v1/caches/phones',
    params={'country': 'IN'},
    auth=HTTPBasicAuth(credential_id, credential_secret),
    headers={'If-None-Match': etag},
    allow_redirects=True
)
if response.status_code == 304:
    print('Cache not changed')
else:
    with open(cache_filename, "wb") as f:
        f.write(response.content)
    print('Cache changed')
    etag = response.headers.get('ETag')
  • See Spammer Cache for spam and fraud numbers only (no display data, no country filter) — use this if you don't need branding or display fields.
  • See Branded Phones Cache for branded display names only (no reputation data) — this is a Hiya Connect cache, available independently of Protect.

Query Parameters​

    country stringrequired

    ISO 3166-1 alpha-2 country code (e.g. 

    IN
    , 
    BR
    , 
    PH
    ). Must be uppercase.

    Possible values: Value must match regular expression ^[A-Z]{2}$

Responses​

Successfully retrieved signed URL for the profile phones cache file

Headers

  • Location

    string

    Contains a signed URL (which expires in 30 seconds) from which you will download the cache file.