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 provider information for each matched hash.

Request Headers

Content-TypestringRequired

Must be application/json.

X-API-KeystringRequired

Your Decode Hash API key.

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 provider.

results[].hashstring

The original hash that was submitted for lookup.

results[].phonestring | null

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

results[].providerstring | null

The mobile network provider. Null if the hash was not found. Possible values: Safaricom, Airtel, Telkom, Faiba, Equitel, Mobile Pay Kenya, Eferio Kenya, Homeland Media, Jambo Telcoms, Infura, Hidiga Investments, Webtribe, NRG Media.

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",
      "provider": "Safaricom"
    },
    {
      "hash": "3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b",
      "phone": "+254722345678",
      "provider": "Airtel"
    },
    {
      "hash": "ef2d127de37b942baad06145e54b0c619a1f22327b2ebbcfbec78f5564afe39d",
      "phone": null,
      "provider": null
    }
  ]
}

Partial Results

Unlike the single lookup endpoint, batch requests always return a 200 status even if some hashes are not found. Check the phone field on each result — it will be null for hashes that could not be 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.