Documentation
Frequently asked questions
If your question isn't here, the fastest path is usually the specific doc page it belongs to; linked throughout, or Support directly.
Getting started
Hosted Verification or Full API; which do I use?
Hosted Verification if you don't want to touch raw NIN/BVN numbers on your own servers at all, you redirect out, we collect and run the check, you get a signed result back. No signing code to write. Full API if you're building your own verification UI and need document upload or facial liveness inside your own app. See Hosted Verification and Full API reference.
What's the base URL?
https://api.uverify.uselodger.com/api/v1 for every Full API endpoint. Hosted Verification's redirect step is the one exception, that goes to https://uverify.uselodger.com/verify/hosted (the app itself, not the API), covered in Hosted Verification.
What's the difference between sandbox and production?
Registering gets you a ck_test_ sandbox project, capped at 100 checks/month, active once you verify your email; same base URL, same code, just a different client_key/api_secret pair. Production (10,000 checks/month, live data) is a separate, manually reviewed request from your dashboard once you know what you're building.
Authentication
Is my api_secret the bearer token?
No. api_secret signs requests (it's the HMAC key); it's never sent over the wire itself and never goes in an Authorization header. The bearer token is a separate, short-lived JWT you get back from POST /auth/token. Full explanation: Authentication.
Do I need two calls, token, then verification; every time?
No. The access token lasts an hour; cache and reuse it across many verification calls. What does need to be fresh on every single request is the HMAC signature, since it's built from the current timestamp. In practice: one background process keeps the token alive, every verification just reuses it plus a freshly computed signature.
Why not just one secret key, like Paystack?
Paystack calls are self-describing, a specific amount, a specific reference, so a leaked key mostly risks money moving through your own account, which you'd notice fast. A U-verify call carries someone else's NIN or BVN, with no amount to flag misuse. The HMAC layer means api_secret itself is never transmitted, so it can't be lifted from a log or proxy the way a bearer key sent on every request could be; the JWT layer means even a leaked bearer token is only useful for an hour. See the full reasoning in Authentication.
I got a 401 TOKEN_EXPIRED; what do I do?
Call POST /auth/token/refresh with your current (expired) token, it works for up to two weeks after expiry, not just before. Only fall back to a full POST /auth/token exchange if the refresh itself fails (meaning it's been more than two weeks, or the token was explicitly logged out).
Can I test the signing flow before writing any code?
Yes : see Testing in Postman for a working collection script that signs every request automatically.
Rate limits
What are the actual limits?
POST /auth/token and /auth/token/refresh share a 10/min-per-IP bucket. Every other authenticated endpoint is a flat 60/min per client (by client_key) ; this is currently the same limit for every account, not tiered by plan. Full table: Full API reference.
What happens if I exceed a rate limit?
A 429 RATE_LIMIT_EXCEEDED response with a Retry-After header telling you how many seconds to wait. X-RateLimit-Limit and X-RateLimit-Remaining are on every response so you can back off before you hit it.
Verification
Which checks are supported?
nin, bvn, drivers_license, voters_card, passport, cac, and credit_bureau for Quick Verify / verification sessions. Document upload and facial liveness are available through verification sessions, not Quick Verify. Full list: Full API reference.
Quick Verify or a verification session, which do I use?
POST /verify (Quick Verify) when you just need a yes/no on a set of IDs, with nothing to poll or look up later. A verification session when you're building an onboarding flow with document and facial capture, or need the result retrievable later. See the Two speeds callout in the Full API reference.
Is there a bulk/batch verification endpoint?
Not currently, each check is its own call. For a bulk use case, loop your own queue and stay under the 60/min client rate limit rather than firing requests in parallel.
Billing & wallet
How does billing work?
Each check debits your project's wallet at the time it runs. Top up via POST /wallet/fund/initialize (returns a Paystack checkout URL) or the Wallet page in your dashboard. See the billing recipe for how to avoid double-charging on page refreshes.
What does a 402 mean?
INSUFFICIENT_BALANCE ; your U-verify wallet can't cover this check's cost. This is separate from any billing layer you run on top for your own users; surface it as "temporarily unavailable", not the end user's fault. Full error reference: Errors & status codes.
Privacy & data
Do you store the raw NIN/BVN I submit?
Verification media (document images, facial captures) is retained 180 days by default, then automatically purged by a scheduled job. Request/audit logs are retained 365 days, then automatically purged. Verification result records, used to answer repeat lookups without re-querying a provider, are retained longer than that; the exact period is one of the items still pending legal review, per the platform's Privacy Policy.
Can I request deletion of a specific record?
There's no self-service deletion endpoint today, retention follows the schedule above automatically. For anything that needs to happen sooner, reach Support directly.
Webhooks
Do you support webhooks?
Yes; for async events like a verification session completing. See Webhooks for the event payload, signature verification, and delivery/retry behaviour.
Troubleshooting
Every request fails with INVALID_SIGNATURE; why?
Almost always signing pretty-printed JSON instead of the exact bytes sent, including the query string in the signed path, or lower-casing the HTTP method. See Common mistakes ; or rule it out entirely by testing in Postman first, where the signing script is known-good.
Where's the full list of error codes?
Errors & status codes ; organized by auth, validation, verification flow, hosted verification, and payments.