KYG - Know Your Gamer
KYG (Know Your Gamer) turns a CPF into a player profile: how much the player is worth, how engaged they are, how they behave, and what risk they carry. It is built for iGaming operators who need to decide something about a player — a bonus, a limit, a review — and need the data behind that decision in one call.
The four dimensions
Every profile is organized the same way, whether you ask for one CPF or a thousand.
| Dimension | Answers |
|---|---|
value_dimension | Estimated income, financial capacity, historical and projected LTV |
engagement_dimension | Market aptitude score, player velocity, deposit signature |
behavior_dimension | Deposit volatility, reinvestment rate, first-deposit sensitivity, bonus affinity |
risk_and_clustering_dimension | Onboarding profile, value/engagement cluster, PLD risk score |
Choosing how to query
| You have | Use | Why |
|---|---|---|
| One CPF | GET /api/v1/players/{cpf} | Answers in the same request |
| A handful of CPFs | POST /api/v1/players/batch | Synchronous, holds the connection until every CPF resolves |
| Dozens or more | POST /api/v1/batches | Asynchronous — see Batch queries |
The synchronous batch endpoint holds the HTTP connection open until the last CPF is resolved. That is fine for a few dozen documents and wrong for a thousand: a large batch takes minutes, and a timeout anywhere between you and us loses the whole thing. The asynchronous endpoint exists for that case.
A field with no value comes back as null
nullKYG never fills a gap with an approximation. If we have no income measurement for a CPF, estimated_basic_income.value is null — not a default bracket, not zero.
This matters most in pld_risk:
"pld_risk": { "score": null, "status": null }null means there is no score for this CPF. It does not mean the risk is zero. Zero is a legitimate score, returned when the risk engine evaluated the player and no criterion fired. Treating null as 0 in your rules would read "not measured" as "cleared".
Removed field:responsible_gaming_riskwas removed from the response contract on 2026-08-13. It never had a data source and returnednullfor the entire life of the product. If your integration reads it, remove the reference — it will no longer be present.
Authentication
Every endpoint expects a bearer token:
Authorization: Bearer YOUR_API_KEYResponse format
Responses are JSON. The format query parameter accepts only json; any other value returns 400 UNSUPPORTED_FORMAT rather than quietly serving JSON to a caller who asked for something else.
Rate limits
| Limit | Value |
|---|---|
| Requests per minute, per operator | 1,000 |
| Batch submissions per minute, per operator | 10 |
| Batches in flight at once, per operator | 50 |
| CPFs per asynchronous batch | 1,000 |
The submission limit counts batches, not documents. Ten submissions per minute at a thousand CPFs each is ten thousand documents per minute.
Exceeding a limit returns 429 with a Retry-After header.
Updated about 1 hour ago