Certificate Verification API
Confirm an Akwa Ibom Certificate of Origin from inside your own systems, at volume. Read-only, authenticated per organisation, and returning the live status — a certificate revoked this morning fails this afternoon.
Checking occasionally? You do not need this. The QR code and the public verification page are open to everyone, free of charge, with no registration.
What it does
- Takes a certificate number you already hold and returns its authenticity and current status.
- Returns the live status — no cache warm-up, no nightly job. A revocation or a deceased marking shows on your very next call.
- Confirms whether a PDF you were given is the exact document the State issued, from its hash.
- Runs independently of the application workflow, so certificates stay verifiable even during a workflow outage.
What it will never do
- List, search, browse, range over or export certificates. There is deliberately no such endpoint — you must already hold the number.
- Disclose a NIN, contact details, photograph, uploaded document or death certificate.
- Expose any part of the application workflow, or the officers who handled it.
- Create, amend, approve, sign, revoke or delete anything. It is read-only at the code level, not by convention.
What it costs, and what you agree to
Free
MDAs, Councils and security agencies
No charge at any volume.
Free
The public page and QR code
For everybody, always, with no account.
AkwaRemit
Any other class of organisation
Where the Ministry determines a fee, it is collected through AkwaRemit and by no other means.
Per org
Rate limits
Set per organisation and raised on request through the Ministry.
The terms of use bind your organisation to four things
- 1 Use the API only for the purpose for which you registered.
- 2 Keep your credentials secure. They belong to the organisation, not to a person, and are not transferable.
- 3 Report any suspected compromise of those credentials without delay.
- 4 Do not store or republish the data returned beyond what your own stated purpose requires.
Every call is logged against your organisation with the certificate number, the timestamp, the result and the source address. Where the Ministry has reason to believe an organisation is using the API otherwise than for its registered purpose — or is attempting to harvest certificate numbers — credentials are suspended immediately and the matter referred.
Integrating
OAuth 2.0 client credentials over TLS. A sandbox with published sample certificate numbers covering every status lets you prove the integration before you receive live credentials.
1. Exchange your credentials for a short-lived token
POST /v1/auth/token
Content-Type: application/json
{
"grant_type": "client_credentials",
"client_id": "coo_4kq7x2m9p3wz8n5t",
"client_secret": "sk_••••••••"
}2. Verify one certificate — the only substantive endpoint
GET /v1/certificates/AKS%2FCoO%2FUYO%2F2026%2F000123 Authorization: Bearer <token>
?surname= acts as a second factor. A wrong surname is answered as NOT_FOUND rather than “wrong surname”, so the endpoint cannot be used to test a name against a number. {
"certificateNumber": "AKS/CoO/UYO/2026/000123",
"status": "VALID",
"holderName": "Udo Aniekan Etim",
"village": "Uyo Urban Village 1",
"localGovernmentArea": "Uyo",
"issuingCouncil": "Uyo Local Government Council",
"dateOfIssue": "2026-03-14",
"replacedBy": null,
"verifiedAt": "2026-08-04T09:21:04.118Z"
}The complete endpoint list
| POST /v1/auth/token | Exchange client credentials for a bearer token. |
| GET /v1/certificates/{number} | Verify one certificate and return its status. |
| POST /v1/certificates/{number}/document-check | Confirm a presented file is the document that was issued. You submit its hash; no document content is returned. |
| GET /v1/health | Liveness. Unauthenticated. |
That is the whole surface. There is no fifth endpoint.
Interpreting the status
- VALID
- Genuine and current. Accept it.
- VALID_HOLDER_DECEASED
- Genuine; the Council has recorded that the holder has died. Not revoked.
- REPLACED
- Superseded by a corrected certificate. `replacedBy` carries the new number — check that instead.
- REVOKED
- Cancelled by the issuing Council. Do not accept it.
- NOT_FOUND
- No certificate matches that number. Returned with HTTP 200, never a 404.
Errors and limits
- Malformed certificate number
- 400, with the expected format described
- Missing, expired or invalid token
- 401
- Credentials suspended by the Ministry
- 403, with a reference for you to quote
- No certificate matches the number
- 200 with status NOT_FOUND
- Rate limit exceeded
- 429, with the reset window in the response headers
- Verification service unavailable
- 503 — and this can never be caused by, nor cause, a workflow outage
Versioned under /v1. A breaking change goes into a new version and the previous one is supported for a stated notice period — your integration will not break without warning.
Ready to register?
Name a responsible officer and state your purpose. The Ministry issues credentials to the organisation.