SBRLS Developer Docsv2.0REST · JSON · HMAC

External API documentation

Verify Somali businesses with a signed REST API: look up by UBI, confirm certificate of incorporation validity, and resolve licence references — scoped to what the Ministry grants your institution.

Base URL

https://ebusiness.gov.so/api/v2

Quick start Open API explorer

What you can verify

The External API v2 is a read-only verification surface for authorised government agencies and private-sector partners (for example banks). Responses never dump the full registry — only fields your credential was granted.

UBI
Business name and identity by Unique Business Identifier (UBI / BIN).
CoI
Certificate of incorporation validity as VALID or INVALID.
LIC
Licence reference lookup by licence number, including expiry status.

Quick start

01
Get credentials from MoCI
After onboarding, you receive an API key and a one-time Bearer token by email. Store them server-side only.
02
Sign every lookup
Build a compact JSON body, take an ISO-8601 timestamp, and compute HMAC-SHA256(body + timestamp, api_key) as lowercase hex.
03
Call health, then lookup
Ping GET /api/v2 without auth. Then POST /api/v2/lookup with the four signed headers and your identifier.

bash · GET /api/v2

curl -s 'https://ebusiness.gov.so/api/v2' -H 'Accept: application/json'

Authentication

Lookup requests require all four headers. The timestamp must be within ±5 minutes of server time. Sign the exact bytes you transmit — whitespace mismatch is the most common failure.

Signature formula

HMAC-SHA256(METHOD + "\n" + PATH + "\n" + X-Timestamp + "\n" + rawJsonBody, signing_secret) → lowercase hex. PATH is the request path, e.g. /api/v2/lookup.

Sign the exact bytes you send as the request body. Prefer compact JSON (no pretty-print).

Header	Value	Notes
Authorization	Bearer <api_token>	Plaintext token, shown once in the MoCI console at issue/renew and sent to your focal point. Not recoverable — renew to mint a new one.
X-API-KEY	<api_key>	Issued alongside the token and shown once. Identifies your credential. Keep it secret.
X-Timestamp	<ISO-8601>	Must be within ±5 minutes of server time.
X-Signature	<hex HMAC-SHA256>	HMAC of method, path, timestamp and raw body, keyed with the signing secret. The signing secret is issued with the key and never sent.

javascript · sign

const body = JSON.stringify({ identifier: '10000101029' });
const timestamp = new Date().toISOString();
const signature = crypto
  .createHmac('sha256', signingSecret)
  .update(`POST\n/api/v2/lookup\n${timestamp}\n${body}`)
  .digest('hex');

Endpoints

Stable JSON envelope on every response: status, message, and data. Field names in data follow the aliases configured for your client.

GET/api/v2Public

Health check. Returns API version and the documentation URL.

200 — status true, message "API is working"

No request body.

curl

curl -s 'https://ebusiness.gov.so/api/v2' -H 'Accept: application/json'

POST/api/v2/lookupSigned

Verify a published business by UBI (bin) or licence number. Response fields are limited to the grants configured for your credential (field mappings / aliases). Use certificate_valid for incorporation validity.

200 — business bundle with granted fields only

request body

{"identifier":"<UBI or licence number>"}

curl

curl -X POST 'https://ebusiness.gov.so/api/v2/lookup' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'X-API-KEY: <api_key>' \
  -H 'X-Timestamp: <ISO-8601>' \
  -H 'X-Signature: <hex HMAC>' \
  -d '{"identifier":"10000101029"}'

Error codes

Status	Meaning
401	Missing/invalid credentials, timestamp, or HMAC signature
403	Credential has no readable resources configured
404	Auth OK; no matching published business (or identifier not visible to your clearance)
429	Per-client rate limit exceeded (see Retry-After header)

Readable resources

Ministry officers map which resources and fields each institution may read. Aliases rename keys in your response without changing the underlying field.

Resource	Grantable fields
Business business	name, bin (UBI), type, status, registration_date, address, certificate_valid (VALID\|INVALID)
Licences license	license_name, license_type, number, status (incl. EXPIRED), issue_date, expiry_date, state
Owners owners	name, official_type, status
Shareholders shareholders	name, shares, share_percentage (by value), share_value
Addresses addresses	address, city, state, region, district, phone, email, website, is_primary
Activities activities	name, description (external consumers see low-clearance activities only)

Request & response

Aliases below (company_name, coi_valid, …) are examples — your mappings may differ.

request · JSON

{"identifier":"10000101029"}

Requesting access

API access is issued by the Ministry of Commerce and Industry. Do not ship production secrets in browsers or mobile apps.

Registry integration contact

[email protected]

Email for access