Skip to main content

Get Spammer Cache

GET 
/v1/caches/spammer_phones

Get Spammer Cache

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 Hiya Protect Cache API to support for local server caches of the Hiya Protect service, API integrators may download the current working set of phone numbers. This list includes a description of reputation level and categorization if available

Get Spammer 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 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) which contains three tab-separated columns:

  • Phone Number: A phone number formatted with a forward-slash in between country code and national part (e.g. 1/4250001111 )
  • Reputation Level: There are two possible reputation levels: -- FRAUD: A call that Hiya predict 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
  • 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
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 Suppport 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 that is not in the current mapping below is returned in the API response. If you do receive an unexpected reputation category integer, feel free to reach out to Hiya for an updated table

Example​

1/2065552000 SPAM

1/4255553000 FRAUD

1/3605554000 SPAM 6

1/5095555000 SPAM 10

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/spammer_phones
  • 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/spammer_phones
  • 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/spammer_phones',
    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')

Responses​

Successfully retrieved signed URL for the spam cache file

Headers

  • Location

    string

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