Check API
For banks, telcos and payment businesses, check one number, MoMo name, merchant ID or website against Agoo Reviews' verified records and confirmed scam reports before money moves.
This is a published preview. Names and fields may still change before general availability; changes will be listed in the changelog.
The Check API answers one question at a time: what does Agoo Reviews know about this phone number, MoMo number, @handle, website or merchant name? It's for partners who move money or connect people to sellers: banks, fintechs, telcos, marketplaces, couriers and lenders. Volta Bank, for example, can check the number a customer is about to send money to, and show its own staff what Agoo knows before the transfer goes.
No record never means safe
An answer gives only confirmed records and official warnings. When Agoo knows nothing, it says so, and that's all it says: never "safe", never a score, never a verdict. Never refuse anyone a service on an answer alone without a person's review.
The answer is the same for every partner. Paying never changes it, and a partner can't add, change or remove a record through the API: reports still come through agoo.reviews and Agoo's own people.
Getting access
Live access is by contract only; there's no self-serve sign-up for live keys. Write to partners@agoohq.com with who you are and what you'll use the answers for. Once the agreement is signed, Agoo sets up your partner area on agoo.reviews, signed in with your Agoo ID and an authenticator app.
Regulators and consumer bodies get live access free, with the same answer and limits, once Agoo has checked the body against its own published notice or registration.
Keys
In your partner area on agoo.reviews, select Keys. Making or revoking a key asks you to confirm with your authenticator. A key is shown once.
| Prefix | Mode | What it does |
|---|---|---|
agoo_ck_test_ | Test | Answers only the published test values, never billed |
agoo_ck_live_ | Live | Answers from Agoo Reviews' records, billed per check; lasts at most 12 months |
A Check API key carries one scope, checks:read, and works only on the Checks operations. Keep it on your servers: never in a website, an app or a URL.
Check one identifier
POST/checkscurl -X POST https://api.agoohq.com/v1/checks \
-H "Authorization: Bearer $AGOO_CHECK_KEY" \
-H "Content-Type: application/json" \
-d '{ "value": "+233200000003" }'| Field | Required | What it is |
|---|---|---|
value | Yes | One phone number, MoMo number, @handle, website or merchant name, 2 to 200 characters. Never a list. |
kind | No | phone, handle, website or merchant, when a value could be more than one (shop.gh is a website or a handle). |
momo_name | No | The name the customer's wallet showed before they confirmed. It's compared with the official name and never kept. |
When a customer is about to pay a MoMo number, send the name their wallet showed:
curl -X POST https://api.agoohq.com/v1/checks \
-H "Authorization: Bearer $AGOO_CHECK_KEY" \
-H "Content-Type: application/json" \
-d '{ "value": "Agoo Test Stores", "kind": "merchant", "momo_name": "AGOO TEST STORE LTD" }'What an answer means
{
"id": "chk_01m6h2j3k4m5n6p7q8r9stvwxy",
"object": "check",
"kind": "phone",
"known": true,
"official": [],
"reports": {
"confirmed": 7,
"kinds": ["fake_seller", "advance_fee"],
"first_month": "2026-03",
"latest_month": "2026-10",
"dispute_waiting": false
},
"warnings": [],
"checked_at": "2026-11-11T10:15:02Z",
"answer_version": "1",
"method_url": "https://agoo.reviews/how-the-score-works#check-api",
"livemode": false
}| Field | What it means |
|---|---|
id | The call's ID (chk_…). Quote it to Agoo about this call. |
known | false means Agoo has no record of it, and message says "We have no record of this." It never means safe. |
official | Each business on Agoo Reviews that has verified this as its own phone, WhatsApp, MoMo or MoMo merchant ID (as), with its name and its page on agoo.reviews. |
register | That business's lines from official registers, as its page shows them. |
reports | Confirmed scam reports only: how many, their kinds, the first and latest month. dispute_waiting is true when the holder has disputed them and a person hasn't decided yet: say so to whoever reads it. |
warnings | Consumer alerts on that business for a regulator's action or for impersonation (cause), with the date. |
impersonating | The businesses a confirmed fake pretends to be, with their pages. |
momo_name_match | When you sent momo_name and the value is an official MoMo: match, lookalike or different. A lookalike is never a match. |
checked_at | When it was answered. Answers are never cached: check again when you need a fresh one. |
answer_version | The version of how answers are worked out. |
method_url | How answers are worked out, in plain words. |
livemode | false for a test key's answer. |
An answer never holds a person's name, who reported something, a report's words, a moderator's summary, a report not yet confirmed, a page that only lists the number, a review, or anything about who else checked it.
Test values
A test key answers only these values, with fixed answers, so you can build every branch of your integration. Any other value with a test key is refused (422, "Test keys answer only the test values."), so a test key is never a free lookup. Send each with its kind, as your live calls should when a value could be more than one: a website on its own also reads as a handle.
| Value | Kind | Outcome |
|---|---|---|
+233 20 000 0001 | phone | no_record |
+233 20 000 0002 | phone | official |
+233 20 000 0003 | phone | reports |
+233 20 000 0004 | phone | warning |
+233 20 000 0005 | phone | official (a MoMo merchant ID) |
+233 20 000 0006 | phone | reports (impersonation, dispute waiting) |
@agoo_test_none | handle | no_record |
@agoo_test_reports | handle | reports |
agoo-test-none.example | website | no_record |
agoo-test-reports.example | website | reports |
Agoo Test None | merchant | no_record |
Agoo Test Stores | merchant | official |
The same list, with each fixed answer, needs no key:
GET/checks/test-valuescurl https://api.agoohq.com/v1/checks/test-valuesYour usage
GET/checks/usagecurl "https://api.agoohq.com/v1/checks/usage?month=2026-11" \
-H "Authorization: Bearer $AGOO_CHECK_KEY"Your own calls by day, live and test, how many were billed, and by outcome. Counts lag the calls by up to a minute. Your partner area shows the same under Usage, and Calls lists the last 90 days (time, key, kind, outcome and request ID, never the value). Look up a past call takes a value and finds your own calls with it, for questions like "did we check this number in June?".
Limits
- A minute limit for each key, from your agreement: 60 checks a minute unless it says otherwise. Every answer carries
RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset; over it, you get429withRetry-After. See rate limits. - Daily and monthly caps from your agreement, read from your usage, which lags by up to a minute: a burst can pass a cap by a few checks before it's refused.
- An allow-list of addresses, if your agreement sets one: calls from anywhere else are refused.
- One identifier a call. There's no list, batch, prefix, wildcard or search, and no watch on an identifier. There are no Check API webhooks, on purpose: watching identifiers would be bulk monitoring.
Unusual patterns, such as sweeping through numbers in sequence, slow a key down at once, and a person at Agoo decides what happens next within one working day. You're told why and can answer.
Errors
Errors are problem details whose detail is written for people.
| Status | When |
|---|---|
401 | The key isn't valid, or it was revoked or has expired. |
403 | Your access is suspended or has ended, or the call came from an address not on your allow-list. |
422 | The value isn't exactly one identifier, or a test key sent a value that isn't a test value. |
429 | Over the key's minute limit, or your agreement's daily or monthly cap. |
Pricing
Banded each month, before VAT, and invoiced monthly in arrears:
| Live checks in the month | Each |
|---|---|
| The first 10,000 | GH₵0.20 |
| The next 90,000 | GH₵0.12 |
| Above 100,000 | GH₵0.06 |
The monthly minimum is GH₵1,000. Every live check is billed, "no record" included; a refused or invalid call never is. Test mode is free for every partner, and regulators and consumer bodies use live keys free within their agreed limits. Invoices are under Invoices in your partner area, each as a PDF.
The terms
Live access follows the Check API terms at agoo.reviews/legal/check-api. In short:
- Use answers only for the purpose stated in your agreement.
- Never compile, resell or publish answers, or build a list of identifiers from them.
- Keep an answer only with your own case record.
- Never refuse anyone a service on an answer alone without a person's review.
- You're responsible for your own customers' data under the Data Protection Act, 2012 (Act 843).
- Agoo may suspend access for misuse.
What Agoo keeps
Agoo never keeps the value you check. It keeps a keyed one-way fingerprint of it for 13 months, with the time, key, kind and outcome, so you can find your own past calls by value and so misuse can be spotted. The wallet name you send is compared and never kept. agoo.reviews' transparency report counts each month's checks by kind of partner, never by name.
Related
Agoo Reviews quick start
Make a Reviews key in your business area on agoo.reviews, read your reviews and score, reply, invite customers after a sale, keep a copy and your catalogue in step, follow cases, your Fix Log, Proof of Work jobs, shared problems and your Complaint Register, and receive signed webhooks.
Authentication
Authenticate with secret or publishable API keys for your own integrations, or with OAuth 2.1 and PKCE for apps that other organisations connect.