UBIN - University Business Identification Number

Getting Started

The API is a set of read-only GET endpoints that return application/json. Every response has an ok boolean, an api endpoint name, a version, and a data payload.

Base URL: https://ubin.thestackcompany.com

# Check the API is reachable
curl https://ubin.thestackcompany.com/api/status.php

Try the live index for a machine-readable overview: https://ubin.thestackcompany.com/api

Format, CORS & Rate Limits

Content-Type: application/json; charset=utf-8 on all responses.
CORS: responses include Access-Control-Allow-Origin: *, so browsers can call the API from any origin.
Rate limit: a fair-use limit of 120 requests per minute per IP. Exceeding it returns 429 rate_limited.
Auth: open by default. If a key is ever configured, pass it as ?apikey=YOUR_KEY.
Attribution: when you display a business on your site, link back to the canonical profile (the profile_url in the response).

Verify a UBIN (exact code lookup)

GET/api/verify.php?ubin=UBIN-XXXX-2026-XXXX-X

Looks up a single UBIN code. Returns 404 not_verified if the code is expired, revoked, or does not exist.

Param	Type	Required	Description
`ubin`	string	required*	The full UBIN code to verify, e.g. `UBIN-AKUM-2026-H2I3-H`. Case-insensitive.
`q`	string	alternative	Search query for name/partial code (see next endpoint). Either `ubin` or `q` must be supplied.

# Example request
curl "https://ubin.thestackcompany.com/api/verify.php?ubin=UBIN-AKUM-2026-H2I3-H"

# Example response (200)
{
  "ok": true,
  "api": "ubin.verify",
  "version": "1.0",
  "data": {
    "ubin": "UBIN-AKUM-2026-H2I3-H",
    "business_name": "Bites & More",
    "description": "Small chops and meals delivery.",
    "category": "Food & Beverages",
    "institution": { "code": "AKUM", "name": "Adekunle Ajasin University, Akungba" },
    "campus": "Main Campus",
    "contact": { "email": "...", "phone": "...", "whatsapp": "..." },
    "verified": true,
    "issued_on": "2026-01-10",
    "expires_on": "2027-01-10",
    "trust": { "identity": true, "institution": true, "business_evidence": true, "payment_identity_match": true },
    "profile_url": "https://ubin.thestackcompany.com/business.php?id=1"
  }
}

Search the Verified Registry

GET/api/verify.php?q=<query>&limit=20

Searches businesses by business name or partial UBIN code. Returns only currently verified, non-expired UBINs ordered newest first.

Param	Type	Required	Description
`q`	string	required	Search term. Truncated to 120 characters.
`limit`	int	optional	Max results (1–20). Default 20.

# Example request
curl "https://ubin.thestackcompany.com/api/verify.php?q=Bites&limit=5"

# Response: ok=true, data is an array of business objects (same shape as above),
# and meta carries { "lookup": "search", "query": "Bites", "count": 2 }

List Partner Institutions

GET/api/institutions.php?q=<query>&type=federal&limit=50&offset=0

Lists active partner institutions, optionally filtered by name/code/state/city or institution type. Useful for building enrolment-picker UI.

Param	Type	Required	Description
`q`	string	optional	Matches name, code, state, or city (substring).
`type`	string	optional	Filter by type: `federal`, `state`, or `private`.
`limit`	int	optional	Page size (1–200). Default 50.
`offset`	int	optional	Pagination offset. Default 0.

# Example request
curl "https://ubin.thestackcompany.com/api/institutions.php?type=federal&limit=3"

# Example response (data excerpt)
{
  "ok": true,
  "api": "ubin.institutions",
  "version": "1.0",
  "data": [
    {
      "code": "AAU",
      "name": "Adekunle Ajasin University, Akungba-Akoko",
      "type": "federal",
      "state": "Ondo",
      "city": "Akungba-Akoko",
      "campus": "Main Campus",
      "website": "https://..."
    }
  ],
  "meta": { "count": 3, "total_matching": 238, "limit": 3, "offset": 0 }
}

Registry Status

GET/api/status.php

Returns a quick summary of the registry — great for dashboards and "live" footers.

curl https://ubin.thestackcompany.com/api/status.php

{
  "ok": true,
  "api": "ubin.status",
  "version": "1.0",
  "data": {
    "verified_businesses": 1,
    "institutions": 238,
    "categories": 12,
    "api": "UBIN Public Registry API"
  },
  "meta": { "generated_at": "2026-01-10T12:00:00+00:00", "timezone": "UTC" }
}

Error Codes

HTTP	error.code	Meaning
400	`missing_parameter`	Required parameters were not supplied.
401	`invalid_api_key`	An API key is configured and the supplied key is missing or wrong.
404	`not_verified`	The UBIN exists but is not currently verified (pending, rejected, revoked, or expired).
429	`rate_limited`	Too many requests — slow down and retry shortly.

# Error response shape
{
  "ok": false,
  "error": { "code": "not_verified", "message": "No current, verified UBIN matches this code." }
}

Using from a Website

Because responses include Access-Control-Allow-Origin: *, you can call the API directly from the browser:

// Verify a UBIN on the client
const res = await fetch("https://ubin.thestackcompany.com/api/verify.php?ubin=" + code);
const json = await res.json();
if (json.ok && json.data.verified) {
  showTrustBadge(json.data.profile_url);
}

Always re-check data.verified and data.expires_on — a UBIN is only trustworthy while it is current and verified.

UBIN Public Registry API Free · Open