Getting Started with Hiya Protect Cache API - Developer Guide

This guide provides developers with step-by-step instructions for integrating the Hiya Protect Cache API to safeguard users from spam and fraudulent calls. The Hiya Protect Cache API enables local caching of known spammer phone numbers, categorized based on reputation level and threat type.

Prerequisites

1. Sign Up & Obtain API Credentials

• Sign up for an account on Hiya’s developer portal.
• Obtain API credentials necessary for authentication.

2. Agree to Terms of Use

• Before using the Hiya Protect Cache API, you must agree to the terms of use provided separately.
• Ensure that Hiya’s data use policy is incorporated into your application’s Terms of Service or is accessible to end users.

Step 1: Fetching the Spammer Cache

Making the Initial Request

To retrieve the latest spammer cache, make a request to:

GET /v1/caches/spammer_phones

A successful request returns an HTTP 307 Temporary Redirect status with a signed URL in the Location header and response body.

Step 2: Downloading the Cache File

• Perform a GET request using the signed URL within 30 seconds.
• If successful, the response returns an HTTP 200 OK with a .tsv.gz file containing the spammer list.

Handling Response Codes

Status Code	Description
200 OK	Cache Successfully Retrieved
307 Temporary Redirect	Follow the signed URL to fetch the cache
403 Forbidden	Expired or invalid URL; request a new one
404 Unknown	Internal error; retry after one hour

Step 3: Processing the Cache File

Since the returned file is a gzipped TSV file containing tab-separated values (for example...)

Phone Number	Reputation Level	Reputation Category
1/2065552000	SPAM	-
1/4255553000	FRAUD
1/3605554000	SPAM	6 (Telemarketer)
1/5095555000	SPAM	10 (Robocaller)

It needs to be processed before integration possibly into a server application if the intended usage of the cache is to use it in a server application

Step 4: Optimizing Requests with ETags

To prevent unnecessary downloads of unchanged data:

1. Store the ETag from your first successful request.
2. On subsequent requests, include If-None-Match: YOUR_ETAG_HERE in the request header.
3. If the cache is unchanged, a 304 Not Modified response is returned.
4. If changed, a new cache file and updated ETag will be provided.

Implementation Best Practices

• Automate periodic cache refreshes: Fetch new cache files at regular intervals to keep data updated.
• Graceful handling of unknown categories: Log unexpected reputation categories and notify Hiya if necessary.
• Ensure secure API key management: Store credentials securely and rotate them periodically.
• By integrating the Hiya Protect Cache API, developers can provide users with a safer calling experience, minimizing exposure to spam and fraud attempts.