Decode Hash Docs
Endpoint

Single Lookup

Resolve a single phone number hash to its verified phone number and carrier information.

POST/v1/lookup

Look up a phone number by its SHA-256 hash. Returns the verified phone number in E.164 format along with carrier details.

Request Headers

Content-TypestringRequired

Must be application/json.

X-API-KeystringRequired

Your Decode Hash API key. Starts with sk_live_ or sk_test_.

Request Body

hashstringRequired

The SHA-256 hash of the phone number to look up. Must be a valid 64-character hexadecimal string.

Response Body

phonestring

The resolved phone number in E.164 format (e.g., +254746604674).

carrierstring

The mobile carrier associated with this number (e.g., Safaricom, Airtel, Telkom).

lookup_time_msnumber

Time taken to resolve the hash, in milliseconds.

Request
curl -X POST https://api.decode.cowdi.co/v1/lookup \
-H   "Content-Type: application/json" \
-H   "X-API-Key: sk_live_xxx" \
-d   '{
    "hash": "9a880505fc5c7953ad6770d71055719bc9f00d963c815207a1a657402d5b7a54"
  }'
Response200 OK
{
  "phone": "+254746604674",
  "carrier": "Safaricom",
  "lookup_time_ms": 1.2
}

Errors

This endpoint may return the following error responses:

401
Unauthorized

Invalid or missing API key.

402
Payment Required

Monthly lookup quota exceeded. Upgrade your plan.

404
Not Found

The hash does not match any known phone number.

422
Unprocessable Entity

Invalid hash format. Must be a 64-character hex string.

429
Too Many Requests

Rate limit exceeded. See the Rate Limits page.

Response404 Not Found
{
  "error": {
    "code": "hash_not_found",
    "message": "The provided hash does not match any known phone number."
  }
}