Decode Hash Docs
Endpoint

Batch Lookup

Resolve multiple phone number hashes in a single request. Ideal for bulk processing workflows with up to 100 hashes per call.

POST/v1/lookup/batch

Look up multiple phone numbers by their SHA-256 hashes. Returns an array of results with phone number and carrier information for each matched hash.

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

hashesstring[]Required

An array of SHA-256 hashes to look up. Each must be a valid 64-character hexadecimal string. Maximum 100 hashes per request.

Response Body

resultsobject[]

Array of lookup results. Each object contains the original hash, resolved phone number, and carrier.

results[].hashstring

The original hash that was submitted for lookup.

results[].phonestring

The resolved phone number in E.164 format. Null if the hash was not found.

results[].carrierstring

The mobile carrier name. Null if the hash was not found.

results[].foundboolean

Whether the hash was successfully resolved.

lookup_time_msnumber

Total time taken to resolve all hashes, in milliseconds.

Request
curl -X POST https://api.decode.cowdi.co/v1/lookup/batch \
-H   "Content-Type: application/json" \
-H   "X-API-Key: sk_live_xxx" \
-d   '{
    "hashes": [
      "9a880505fc5c7953ad6770d71055719bc9f00d963c815207a1a657402d5b7a54",
      "3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b",
      "ef2d127de37b942baad06145e54b0c619a1f22327b2ebbcfbec78f5564afe39d"
    ]
  }'
Response200 OK
{
  "results": [
    {
      "hash": "9a880505fc5c7953ad6770d71055719bc9f00d963c815207a1a657402d5b7a54",
      "phone": "+254746604674",
      "carrier": "Safaricom",
      "found": true
    },
    {
      "hash": "3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b",
      "phone": "+254722345678",
      "carrier": "Airtel",
      "found": true
    },
    {
      "hash": "ef2d127de37b942baad06145e54b0c619a1f22327b2ebbcfbec78f5564afe39d",
      "phone": null,
      "carrier": null,
      "found": false
    }
  ],
  "lookup_time_ms": 4.5
}

Partial Results

Unlike the single lookup endpoint, batch requests always return a 200 status even if some hashes are not found. Check the found field on each result to determine if the hash was successfully resolved.

Note: Each hash in the batch counts as one lookup against your monthly quota, regardless of whether it was found or not.

Errors

This endpoint may return the following error responses:

400
Bad Request

The hashes field is missing, empty, or exceeds 100 items.

401
Unauthorized

Invalid or missing API key.

402
Payment Required

Not enough remaining quota to process the batch. No hashes are looked up.

422
Unprocessable Entity

One or more hashes are not valid 64-character hex strings.

429
Too Many Requests

Rate limit exceeded. See the Rate Limits page.