Skip to main content

Get Branded Phones Cache

GET 
/v1/caches/branded_phones

Downloads a gzipped TSV file (.tsv.gz) of branded phone numbers. The response is a 307 redirect to a signed URL that expires in 30 seconds.

The file contains two tab-separated columns: phone number (formatted as CC/national, e.g. 1/4250001111) and display name (may be empty).

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 Connect Branded Phones Cache API to support local server caches of branded phone numbers. API integrators may download the current working set of branded phone numbers with their associated display names.

Get Branded 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 two tab-separated columns:

  • Phone Number: formatted with a forward-slash between country code and national part (e.g. 1/4250001111)
  • Display Name: the branded company name; may be empty

Example​

1/2065550100 Acme Corporation

44/2012345678 Example Ltd

1/4255550199

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/branded_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/branded_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/branded_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')
  • See Spammer Cache for spam and fraud numbers only (reputation level + category, no display data, no country filter).
  • See Profile Phones Cache for a per-country feed combining flagged numbers (SPAM, FRAUD) and branded phones (NEUTRAL) in a single download.

Responses​

Successfully retrieved signed URL for the branded phones cache file

Headers

  • Location

    string

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