Phone Hash API Integration

The Phone Hash Directory provides a REST API for programmatic access to hash lookup, reverse lookup, and phone-to-hash conversion. This developer guide covers authentication, endpoints, request/response formats, rate limits, and best practices for integrating the phone hash API into your applications.

API Overview

The API supports three primary operations:

1. Hash Lookup: Submit a hash (MD5, SHA-1, or SHA-256) and receive existence status and optional metadata.
2. Reverse Lookup: Submit a hash and, when authorized, receive the original phone number.
3. Phone to Hash: Submit a phone number and receive normalized hash(es) in your chosen algorithm(s).

All endpoints use HTTPS and return JSON. Use our hash directory for manual exploration; use the API for automation.

Authentication

API requests require authentication. Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Or as a query parameter (less secure; use only over HTTPS):

?api_key=YOUR_API_KEY

API keys are issued per account. Rotate keys periodically and never expose them in client-side code. For server-to-server integration, use header-based authentication.

Hash Lookup Endpoint

POST /api/v1/lookup

Request body:

{
  "hash": "5d41402abc4b2a76b9719d911017c592",
  "algorithm": "md5"
}

Supported algorithms: md5, sha1, sha256.

Response (200 OK):

{
  "found": true,
  "hash": "5d41402abc4b2a76b9719d911017c592",
  "algorithm": "md5"
}

When found is false, the hash does not exist in our index. For bulk lookup, use the batch endpoint (see documentation).

Reverse Lookup Endpoint

POST /api/v1/reverse-lookup

Request body:

{
  "hash": "5d41402abc4b2a76b9719d911017c592",
  "algorithm": "md5"
}

Response (200 OK, when authorized and found):

{
  "found": true,
  "phone": "+15551234567",
  "hash": "5d41402abc4b2a76b9719d911017c592"
}

Reverse lookup requires authorization. Unauthorized requests return 403. Use our reverse lookup web interface for manual access.

Phone to Hash Endpoint

POST /api/v1/hash

Request body:

{
  "phone": "+15551234567",
  "algorithms": ["md5", "sha256"]
}

Response (200 OK):

{
  "phone": "+15551234567",
  "normalized": "+15551234567",
  "hashes": {
    "md5": "5d41402abc4b2a76b9719d911017c592",
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }
}

Normalization follows E.164. See our phone hash formats guide for format details.

Rate Limits

• Default: 100 requests per minute per API key.
• Bulk endpoints: 10 requests per minute; each request may contain up to 100 items.
• Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

When exceeded, the API returns 429 Too Many Requests. Implement exponential backoff and respect Retry-After if provided.

Error Handling

Status	Meaning
400	Invalid request (malformed hash, unsupported algorithm)
401	Missing or invalid API key
403	Forbidden (e.g., reverse lookup not authorized)
404	Resource not found
429	Rate limit exceeded
500	Server error

Error responses include a message field. Log errors for debugging; see our debugging hashed phones guide for troubleshooting.

Code Examples

Python (requests):

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.phonehashing.com/v1"

def hash_lookup(hash_value, algorithm="md5"):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    payload = {"hash": hash_value, "algorithm": algorithm}
    r = requests.post(f"{BASE_URL}/lookup", json=payload, headers=headers)
    return r.json()

JavaScript (fetch):

async function hashLookup(hashValue, algorithm = 'md5') {
  const response = await fetch('https://api.phonehashing.com/v1/lookup', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ hash: hashValue, algorithm })
  });
  return response.json();
}

Best Practices

• Validate input before sending: hash format (32/40/64 hex chars), phone format (E.164).
• Cache results when appropriate; hashes are deterministic.
• Handle rate limits with backoff; avoid hammering the API.
• Use HTTPS only; never send API keys over HTTP.

API Versioning

We version our API (e.g., /api/v1/). When we introduce breaking changes, we release a new version and maintain the previous version for a deprecation period. Monitor our changelog and migration guides. Include the API version in your integration tests so you're notified when behavior changes. We recommend pinning to a specific version in production rather than using "latest" to avoid surprise breakage. When upgrading, run integration tests against the new version in staging before promoting to production. Review the changelog for breaking changes and migration steps. We provide migration guides for major version upgrades. Migration guides typically include: list of breaking changes, step-by-step migration instructions, code examples for common patterns, and a timeline for deprecation of the old version. We aim to give customers at least six months notice before deprecating a version. Subscribe to our developer newsletter or follow our changelog to stay informed about upcoming changes. We announce deprecations at least six months in advance and provide migration guides. For critical integrations, consider setting up monitoring that alerts when we publish a new API version—review the changelog and plan your migration. Proactive upgrades reduce the risk of last-minute scrambles when a version is deprecated.

Bulk and Batch Endpoints

For high-volume operations, use our batch endpoints. Submit up to 100 hashes per request for lookup or reverse lookup. Batch requests count as a single rate-limit unit for the request but may have higher latency. Implement retry logic for failed items—partial failures are possible. When processing large datasets, chunk into batches of 100 and throttle to respect rate limits. Consider asynchronous processing for very large jobs.

Webhooks and Async Processing

For enterprise customers, we offer webhook notifications when long-running jobs complete. Configure a webhook URL in your account settings; we'll POST a JSON payload when a batch job finishes. Use this for non-blocking integration—submit a job, receive a webhook when done, then fetch results. Include idempotency keys in your requests to handle duplicate webhook deliveries safely.

SDK and Client Libraries

Community-maintained client libraries are available for Python, Node.js, and other languages. See our GitHub repository for links. When using third-party SDKs, verify they match our current API version and handle errors correctly. We recommend testing with our API directly first to understand expected behavior before integrating an SDK.

For hash validation patterns, see our hash validation best practices. To explore the API interactively, visit /hashes, /phones, and /reverse-lookup.