Caching

The ScamVerify™ API automatically caches lookup results to improve response times and reduce quota consumption. Understanding how caching works helps you optimize both performance and cost.

How It Works

When you look up a phone number, URL, text message, or email, the API checks whether a recent result already exists. If it does, the cached result is returned immediately. If not, a fresh lookup is performed against all data sources.

• Cache duration: 24 hours from the time of the original lookup
• Cached lookups do not consume quota - only the first lookup for a given input counts
• Cached responses are identical to fresh responses in structure and content

Cache Fields in the Response

Every API response includes two fields that indicate cache status:

{
  "risk_score": 82,
  "verdict": "high_risk",
  "cached": true,
  "cache_expires_at": "2026-03-10T14:30:00Z",
  "explanation": "..."
}

Force Refresh

If you need the most up-to-date data (for example, after a known data source update), you can bypass the cache by passing force_refresh: true in your request body:

curl -X POST https://scamverify.ai/api/v1/phone/lookup \
  -H "Authorization: Bearer sv_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+12025551234",
    "force_refresh": true
  }'

When force_refresh is used, the response will show "cached": false and the cache_expires_at will be set 24 hours from the current time.

Cost Optimization

Caching is one of the most effective ways to stretch your quota:

• Repeated lookups are free. If your application checks the same phone number 10 times in a day, only the first lookup consumes quota. The other 9 are served from cache at no cost.
• Batch results are also cached. Items in a batch request that already have cached results will not consume quota.
• Plan your refresh strategy. For most use cases, 24-hour-old data is perfectly adequate. Only use force_refresh when you have a specific reason to believe the data has changed.

Client-Side Caching Recommendations

In addition to server-side caching, consider caching results on your end to further reduce API calls:

1. Store results locally. When you receive a lookup result, store it in your database or in-memory cache along with the cache_expires_at timestamp.

2. Check local cache first. Before making an API call, check if you already have a valid (non-expired) result for that input.

3. Respect the expiration. Use cache_expires_at to determine when your local cache should be invalidated. Do not keep stale data beyond the expiration time.

4. Use ETags or request hashing. For text and email analysis, hash the input content and use it as a cache key on your side. Identical content will produce identical results.

# Example: Simple client-side cache in Python
import hashlib
from datetime import datetime

cache = {}

def lookup_with_cache(phone_number, api_key):
    cache_key = f"phone:{phone_number}"

    # Check local cache first
    if cache_key in cache:
        entry = cache[cache_key]
        if datetime.fromisoformat(entry["cache_expires_at"]) > datetime.utcnow():
            return entry  # Return cached result, no API call needed

    # Make API call
    response = requests.post(
        "https://scamverify.ai/api/v1/phone/lookup",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"phone_number": phone_number},
    )
    result = response.json()

    # Store in local cache
    cache[cache_key] = result
    return result

By combining server-side and client-side caching, you can significantly reduce the number of API calls your application makes while keeping data fresh.