# LOOKUP API — 100M Phone Cryptographic Reverse Lookup Infrastructure

> Ultra-low latency SHA-256 reverse lookup service covering 100,000,000 Kenyan mobile phone records (Safaricom CAK allocations `254XXXXXXXXX`). Resolves `SHA-256(phone_number) -> phone_number` in ~0.5ms.

## Core Capabilities
- Single Reverse Lookup: `GET /v1/lookup/{sha256}` (Sub-millisecond latency, returns `{"number": "254791000000"}`).
- Synchronous Batch Lookup: `POST /v1/lookup/batch` (Up to 500 hashes per request).
- Asynchronous Batch Jobs: `POST /v1/jobs/batch` (Up to 50,000 hashes with live polling and webhooks).
- Forward Number Hashing: `GET /v1/hash/{number}` (Computes canonical SHA-256 digest).
- Self-Service API Key Registration: `POST /v1/users` (Instant API key provisioning).
- Quota & Profile Verification: `GET /v1/users/me` (Inspect active limits).

## Primary Ingress & Endpoints
- Production Ingress: `https://backend.zero-one-logistics.co.ke`
- Web Console: `https://hashreverse.zero-one-logistics.co.ke`
- API Version: `2026-09-12` (header `API-Version: 2026-09-12`)
- Authentication: `X-API-Key: lk_live_<hex>` or `Authorization: Bearer lk_live_<hex>`
- Public Demo: Free public visitors without an API key are granted up to 6 requests before requiring self-service key registration.

## Developer Quotas & Pricing
- Free Tier: 100 requests per day, up to 1,000,000 lookups per year ($0 / forever free).
- Production Tier: KES 4,000 / year (Unlimited lookups, 50,000 async batches, priority routing, webhook alerts).
- Enterprise: Dedicated private cluster, custom SLAs, VPC peering.

## Example Quickstart (cURL)
```bash
curl -X GET "https://backend.zero-one-logistics.co.ke/v1/lookup/1235926f0e31f4c9cee58f172167753b2f94f7574fb89f7adfcbb8724fa0446c" \
  -H "X-API-Key: lk_live_<your_key>" \
  -H "API-Version: 2026-09-12"
```

## Machine-Readable Specifications
- OpenAPI 3.1 Spec: `https://hashreverse.zero-one-logistics.co.ke/openapi.json`
- LLM Discovery Index: `https://hashreverse.zero-one-logistics.co.ke/llms.txt`

## Technical Research Papers & Engineering Articles
- Cryptographic Entropy Analysis: `https://hashreverse.zero-one-logistics.co.ke/blog/why-unsalted-sha256-fails-phone-anonymization` (Mathematical proof of why unsalted SHA-256 fails phone number anonymization across 25.5-bit spaces).
- Fintech Reconciliation Guide: `https://hashreverse.zero-one-logistics.co.ke/blog/mpesa-payment-audit-reconciliation-sha256` (Resolving M-Pesa ledger mismatches when upstream logs only retain SHA-256 hashes).
- High-Performance Architecture: `https://hashreverse.zero-one-logistics.co.ke/blog/architecting-100m-record-sub-millisecond-reverse-lookup` (Distributed shard-per-core indexing, sliding-window rate limiters, and 50K async job queues).
- Daraja Callback Recovery: `https://hashreverse.zero-one-logistics.co.ke/blog/daraja-stk-push-callback-failure-recovery` (Idempotent architecture for handling dropped M-Pesa STK push webhooks and unallocated payments).
- HSM & KMS Security Guide: `https://hashreverse.zero-one-logistics.co.ke/blog/salt-pepper-hmac-phone-number-security` (Why static salting fails against offline GPU cracking and how to implement HMAC-SHA256 with KMS).
- High-Throughput Batch Systems: `https://hashreverse.zero-one-logistics.co.ke/blog/building-zero-copy-batch-hash-processors` (Processing 50,000 hashes in under 42 seconds using zero-copy binary chunks and sharded worker pools).