v:verza
verza / docs / risk-score-api

Risk score API

The score is the sum of named rules. The rules and the points are in data/risk-rules.json, version 2026-10-12. Points add up and the total is capped at 100. Bands are 0 to 19 low, 20 to 49 review, and 50 or above high.

The score is an input to a person, not a decision. Do not refuse service on this score alone. That limit is the POPIA section 71 rule against a decision with legal effect based solely on automated processing. Nothing is stored. There is no live HLR lookup.

Endpoints

POST /v1/risk-score

A points sum of named rules over a South African phone number, an email address, an ID number and an IP address. The rules and the points are published. The score is an input to a person, not a decision, and service must not be refused on this score alone.

$0.05 per call · example: /v1/risk-score

How you pay

API key. The free tier issues a key at /signup: send it as Authorization: Bearer <key> and calls come off a monthly allowance, no crypto anywhere in that path. Every key comes with a sandbox twin (vz_test_) that never counts against quota and accepts only the documented test inputs, so you can wire up an integration before spending a single call.

Pay per call. Send no key at all and a paid endpoint replies HTTP 402 with the exact payment requirements; an x402 client pays USDC on Base (about two seconds to settle) and retries automatically. No account, no signup, which is what makes it work for autonomous agents.

Either way, invalid input is rejected with a free 400 before any payment is challenged, so you never pay (or spend quota) to learn you made a typo.

Questions

What do I send?
POST /v1/risk-score with at least two of phone, email, id, ip and declared_dob. declared_dob requires id, and that mistake is a free 400. One field is a free 400. An empty body is a 402. A well-formed body that has not been paid is a 402 at $0.05. Unknown keys are a free 400.
Is this a fraud decision?
No. The check text says it is not a fraud prediction, not a credit check, and not a decision. fired lists each rule that matched, with its points. not_evaluated lists the input fields you did not send.
Which rules add points?
An invalid ID is 40. A declared date of birth that disagrees with the ID is 30. An ID under 18 is 20. A disposable email domain is 25. No MX is 20. An email domain under 30 days old is 20, and free-mail providers are skipped. An invalid South African phone number is 25. A premium or other non-geographic line is 10. A Tor exit is 30. A cloud range is 15. A country other than ZA is 10, and only when a country code is present. A role address such as info@ is 5.
What is not scored?
A field you leave out is listed in not_evaluated and adds nothing. An invalid ID does not also score a date-of-birth mismatch or an under-18 rule. A free-mail domain is not scored as young. A .za email domain is listed under not_evaluated with reason za_registry_not_queried. When the domain lookup fails, email_domain_age is added to not_evaluated and the score still returns.

Related

South African ID number validation API South African VAT number validation API NCA credit agreement lawfulness API South African KYB and onboarding API South African contact validation API CIPC registration number check Domain age and registry status API IP address screening API Business pre-screen API Guides: how the interest rate caps work zaref: NCA maximum interest rates