Step 1

Create your account

Create an account by visting this link.
You will now have access to the "My Account" dashboard via:
1. a sidebar link on the left side of your screen
2. a navigation bar link or
3. a dropdown menu on the user icon from the navigation bar.

Step 2

Generate your credentials

On the "My Account" dashboard, navigate to the "API Access" page via the side menu on the left.
Generate your API credentials by clicking the "Generate" button.
NOTE:
API credentials are available in a key-secret pair. You will only get one chance to copy the API Secret when you generate it.
If you re-generate the credentials, only the API Secret is changed.

Step 3

Add the credentials to your app

Update your app's configuration with the credentials

HASHDB_API_KEY=<api_key>
HASHDB_API_SECRET=<api_secret>

Step 4

Make the API Request

Make a request to https://api.hashdb.sevn.co.ke/v1/convert/<sha256_hash> using the credentals obtained in the Authorization HTTP header as shown below:

Authorization: Token <HASHDB_API_KEY>:<HASHDB_API_SECRET>

Sample code to generate hashes can be found at the end of the page

Simple SHA256 MSISDN Hash Generators

You can use these samples to generate MSISDN hashes for testing

NodeJS v14+

const { createHash } = require('crypto')

function msisdn2sha256(msisdn) {

const hash = createHash('sha256');

hash.update(msisdn.toString(), 'utf8');

return `${msisdn} - ${hash.digest().toString('hex')}`;

}

msisdn2sha256(254712345678);

// '254712345678 - 7132104d6aae9c3fac82095a42c2817952bca48e09d98d5bf4ac08218982fb90'

PHP 5+

<?php

function msisdn2sha256($msisdn)

{

$hash = hash('sha256', "{$msisdn}");

return "{$msisdn} - {$hash}";

}

msisdn2sha256(254712345678);

// '254712345678 - 7132104d6aae9c3fac82095a42c2817952bca48e09d98d5bf4ac08218982fb90'

Python 3+

from hashlib import sha256

def msisdn2sha256(msisdn):

hash = sha256(b"%d" % msisdn).hexdigest()

return f"{msisdn} - {hash}"

msisdn2sha256(254712345678)

# '254712345678 - 7132104d6aae9c3fac82095a42c2817952bca48e09d98d5bf4ac08218982fb90'

Example

cURL example in Bash

user@host:~$ export HASHDB_API_KEY=<api_key>
user@host:~$ export HASHDB_SECRET_KEY=<api_secret>
user@host:~$ curl -H "Authorization: Token ${HASHDB_API_KEY}:${HASHDB_API_SECRET}" -vvv https://api.hashdb.sevn.co.ke/v1/convert/ccd0701e8a4f16bbd9a24f1e7af5a91163a7b50f4bad8b4d740daa571b141e76
* Host api.hashdb.sevn.co.ke:443 was resolved.

* IPv6: (none)

* IPv4: •••.•••.•••.•••

* Trying •••.•••.•••.•••...

* schannel: disabled automatic use of client certificate

* ALPN: curl offers http/1.1

* ALPN: server accepted http/1.1

* Connected to api.hashdb.sevn.co.ke (•••.•••.•••.•••) port 443

* using HTTP/1.x

> GET /v1/convert/ccd0701e8a4f16bbd9a24f1e7af5a91163a7b50f4bad8b4d740daa571b141e76 HTTP/1.1

> Host: api.hashdb.sevn.co.ke

> User-Agent: ••••••••••••

> Accept: */*

> Authorization: Token <api_key>:<api_secret>

* Request completely sent off

* schannel: remote party requests renegotiation

* schannel: renegotiating SSL/TLS connection

* schannel: SSL/TLS connection renegotiated

* schannel: remote party requests renegotiation

* schannel: renegotiating SSL/TLS connection

* schannel: SSL/TLS connection renegotiated

< HTTP/1.1 200 OK

< Server: •••••••••••••••

< Date: ••••••••••••••••••••••••••••••

< Content-Type: application/json

< Content-Length: 23

< Connection: keep-alive

< Set-Cookie: ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

< X-Frame-Options: SAMEORIGIN

< Strict-Transport-Security: max-age=63072000; includeSubDomains; preload

< X-Content-Type-Options: nosniff

< X-XSS-Protection: 1; mode=block

< Referrer-Policy: same-origin, strict-origin-when-cross-origin

{"data":"254198564782"}* Connection #0 to host api.hashdb.sevn.co.ke left intact

Responses

Successful Response

Status 200 - OK

{
"data": "254198564782" // The corresponding MSISDN matching the hash
}

Error Responses

Status 400 - Bad Request

{
"message": "The hash you provided doesn't seem to be a valid Kenyan MSISDN" // When the hash could not be converted
}

Status 417 - Expectation Failed

{
"message": "The \"hash\" parameter is missing or malformed" // The error message
}

Status 504 - Gateway Timeout

{
"message": "An upstream connection failed. Please report this via https://hashdb.sevn.co.ke/contact"
}

Report any errors you need help with using this link

Documentation