Docs

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.

Preview· P9For developers at Check API partners

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.

PrefixModeWhat it does
agoo_ck_test_TestAnswers only the published test values, never billed
agoo_ck_live_LiveAnswers 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/checks
curl -X POST https://api.agoohq.com/v1/checks \
  -H "Authorization: Bearer $AGOO_CHECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "+233200000003" }'
FieldRequiredWhat it is
valueYesOne phone number, MoMo number, @handle, website or merchant name, 2 to 200 characters. Never a list.
kindNophone, handle, website or merchant, when a value could be more than one (shop.gh is a website or a handle).
momo_nameNoThe 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
}
FieldWhat it means
idThe call's ID (chk_…). Quote it to Agoo about this call.
knownfalse means Agoo has no record of it, and message says "We have no record of this." It never means safe.
officialEach 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.
registerThat business's lines from official registers, as its page shows them.
reportsConfirmed 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.
warningsConsumer alerts on that business for a regulator's action or for impersonation (cause), with the date.
impersonatingThe businesses a confirmed fake pretends to be, with their pages.
momo_name_matchWhen you sent momo_name and the value is an official MoMo: match, lookalike or different. A lookalike is never a match.
checked_atWhen it was answered. Answers are never cached: check again when you need a fresh one.
answer_versionThe version of how answers are worked out.
method_urlHow answers are worked out, in plain words.
livemodefalse 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.

ValueKindOutcome
+233 20 000 0001phoneno_record
+233 20 000 0002phoneofficial
+233 20 000 0003phonereports
+233 20 000 0004phonewarning
+233 20 000 0005phoneofficial (a MoMo merchant ID)
+233 20 000 0006phonereports (impersonation, dispute waiting)
@agoo_test_nonehandleno_record
@agoo_test_reportshandlereports
agoo-test-none.examplewebsiteno_record
agoo-test-reports.examplewebsitereports
Agoo Test Nonemerchantno_record
Agoo Test Storesmerchantofficial

The same list, with each fixed answer, needs no key:

GET/checks/test-values
curl https://api.agoohq.com/v1/checks/test-values

Your usage

GET/checks/usage
curl "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-Remaining and RateLimit-Reset; over it, you get 429 with Retry-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.

StatusWhen
401The key isn't valid, or it was revoked or has expired.
403Your access is suspended or has ended, or the call came from an address not on your allow-list.
422The value isn't exactly one identifier, or a test key sent a value that isn't a test value.
429Over 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 monthEach
The first 10,000GH₵0.20
The next 90,000GH₵0.12
Above 100,000GH₵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.

On this page