{"info":{"_postman_id":"cff87b0a-f239-4ae5-b249-3a4236af4508","name":"Integration API","description":"

Changelog

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Version	Date	Changes
1.0	2024-03-19	Initial version
2.0	2024-09-30	Free Spins support & Model update
2.1	2024-10-11	Refactor value formats
3.0	2024-11-06	Lobby support
3.1	2024-11-18	Game Round History support
3.2	2025-01-13	Get Providers support
3.3	2025-02-14	Refactor types & Update description
3.4	2025-04-02	Added non-game transactions support
3.5	2025-06-04	Game providerGameId support & Transaction providerRoundId support
3.6	2025-06-24	Update supported currencies
3.7	2025-07-31	Add brand id support
3.8	2025-09-11	Remove brand support
3.9	2025-09-29	Add multi-currency support & Get Player Details support
3.10	2025-10-01	Affiliate support
3.11	2025-10-10	Free Spins Completed
3.12	2025-11-08	Session mechanism

Introduction

Casino is the entity which works with the players.
Aggregator Provider is the entity which provides single API for integrations.

Casino provides:

Callback Url
\n
IPs to whitelist.
\n

Aggregator Provider provides:

API Url
\n
Basic Auth Username
\n
Basic Auth Password
\n
Brand Id
\n
IPs to whitelist.
\n

Formats

Money

Money amount is passed with minor units
Examples: 2.50 EUR = 250, 10.50 TRY = 1050

Currency is passed as string
Examples: EUR, TRY

Supported Currencies:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Currency	Name	Minor Units
AED	United Arab Emirates Dirham	2
ALL	Albanian Lek	2
AMD	Armenian Dram	2
ANG	Netherlands Antillean Guilder	2
AOA	Angolan Kwanza	2
ARS	Argentine Peso	2
AUD	Australian Dollar	2
AWG	Aruban Florin	2
AZN	Azerbaijani Manat	2
BAM	Bosnia-Herzegovina Convertible Mark	2
BBD	Barbadian Dollar	2
BDT	Bangladeshi Taka	2
BGN	Bulgarian Lev	2
BHD	Bahraini Dinar	3
BIF	Burundian Franc	0
BMD	Bermudian Dollar	2
BND	Brunei Dollar	2
BOB	Bolivian Boliviano	2
BOV	Bolivian Mvdol	2
BRL	Brazilian Real	2
BSD	Bahamian Dollar	2
BTN	Bhutanese Ngultrum	2
BWP	Botswanan Pula	2
BYN	Belarusian Ruble	2
BZD	Belize Dollar	2
CAD	Canadian Dollar	2
CDF	Congolese Franc	2
CHE	WIR Euro	2
CHF	Swiss Franc	2
CHW	WIR Franc	2
CLF	Unidad de Fomento (Chile)	4
CLP	Chilean Peso	2
CNY	Chinese Yuan	2
COP	Colombian Peso	2
COU	Unidad de Valor Real	2
CRC	Costa Rican Colón	2
CUC	Cuban Convertible Peso	2
CUP	Cuban Peso	2
CVE	Cape Verdean Escudo	2
CZK	Czech Koruna	2
DJF	Djiboutian Franc	0
DKK	Danish Krone	2
DOP	Dominican Peso	2
DZD	Algerian Dinar	2
EGP	Egyptian Pound	2
ERN	Eritrean Nakfa	2
ETB	Ethiopian Birr	2
EUR	Euro	2
FJD	Fijian Dollar	2
FKP	Falkland Islands Pound	2
GBP	British Pound Sterling	2
GEL	Georgian Lari	2
GHS	Ghanaian Cedi	2
GIP	Gibraltar Pound	2
GMD	Gambian Dalasi	2
GNF	Guinean Franc	0
GTQ	Guatemalan Quetzal	2
GYD	Guyanaese Dollar	2
HKD	Hong Kong Dollar	2
HNL	Honduran Lempira	2
HRK	Croatian Kuna	2
HTG	Haitian Gourde	2
HUF	Hungarian Forint	2
IDR	Indonesian Rupiah	2
ILS	Israeli New Shekel	2
INR	Indian Rupee	2
IQD	Iraqi Dinar	3
IRR	Iranian Rial	2
ISK	Icelandic Króna	0
JMD	Jamaican Dollar	2
JOD	Jordanian Dinar	3
JPY	Japanese Yen	0
KES	Kenyan Shilling	2
KGS	Kyrgyzstani Som	2
KHR	Cambodian Riel	2
KMF	Comorian Franc	0
KPW	North Korean Won	2
KRW	South Korean Won	0
KWD	Kuwaiti Dinar	3
KYD	Cayman Islands Dollar	2
KZT	Kazakhstani Tenge	2
LAK	Lao Kip	2
LBP	Lebanese Pound	2
LKR	Sri Lankan Rupee	2
LRD	Liberian Dollar	2
LSL	Lesotho Loti	2
LYD	Libyan Dinar	3
MAD	Moroccan Dirham	2
MDL	Moldovan Leu	2
MGA	Malagasy Ariary	2
MKD	Macedonian Denar	2
MMK	Myanmar Kyat	2
MNT	Mongolian Tögrög	2
MOP	Macanese Pataca	2
MRU	Mauritanian Ouguiya	2
MUR	Mauritian Rupee	2
MVR	Maldivian Rufiyaa	2
MWK	Malawian Kwacha	2
MXN	Mexican Peso	2
MXV	Mexican Unidad de Inversion	2
MYR	Malaysian Ringgit	2
MZN	Mozambican Metical	2
NAD	Namibian Dollar	2
NGN	Nigerian Naira	2
NIO	Nicaraguan Córdoba	2
NOK	Norwegian Krone	2
NPR	Nepalese Rupee	2
NZD	New Zealand Dollar	2
OMR	Omani Rial	3
PAB	Panamanian Balboa	2
PEN	Peruvian Sol	2
PGK	Papua New Guinean Kina	2
PHP	Philippine Peso	2
PKR	Pakistani Rupee	2
PLN	Polish Złoty	2
PYG	Paraguayan Guaraní	0
QAR	Qatari Riyal	2
RON	Romanian Leu	2
RSD	Serbian Dinar	2
RUB	Russian Ruble	2
RWF	Rwandan Franc	0
SAR	Saudi Riyal	2
SBD	Solomon Islands Dollar	2
SCR	Seychellois Rupee	2
SDG	Sudanese Pound	2
SEK	Swedish Krona	2
SGD	Singapore Dollar	2
SHP	Saint Helena Pound	2
SLL	Sierra Leonean Leone	2
SOS	Somali Shilling	2
SRD	Surinamese Dollar	2
SSP	South Sudanese Pound	2
STN	São Tomé and Príncipe Dobra	2
SVC	Salvadoran Colón	2
SYP	Syrian Pound	2
SZL	Swazi Lilangeni	2
THB	Thai Baht	2
TJS	Tajikistani Somoni	2
TMT	Turkmenistani Manat	2
TND	Tunisian Dinar	3
TOP	Tongan Paʻanga	2
TRY	Turkish Lira	2
TTD	Trinidad and Tobago Dollar	2
TWD	New Taiwan Dollar	2
TZS	Tanzanian Shilling	2
UAH	Ukrainian Hryvnia	2
UGX	Ugandan Shilling	0
USD	United States Dollar	2
USN	US Dollar (Next day)	2
UYI	Uruguay Peso en Unidades Indexadas	0
UYU	Uruguayan Peso	2
UZS	Uzbekistani Som	2
VND	Vietnamese Đồng	0
VUV	Vanuatu Vatu	0
WST	Samoan Tala	2
XAF	Central African CFA Franc	0
XCD	East Caribbean Dollar	2
XOF	West African CFA Franc	0
XPF	CFP Franc	0
YER	Yemeni Rial	2
ZAR	South African Rand	2
ZMW	Zambian Kwacha	2
ZWL	Zimbabwean Dollar	2
VEF	Venezuelan Bolívar	2
XAG	Silver (troy ounce)	0
XAU	Gold (troy ounce)	0
XBA	European Composite Unit	0
XBB	European Monetary Unit	0
XBC	European Unit of Account 9	0
XBD	European Unit of Account 17	0
XDR	Special Drawing Rights	0
XPD	Palladium (troy ounce)	0
XPT	Platinum (troy ounce)	0
XSU	SUCRE	0
XTS	Code Reserved for Testing	0
XUA	ADB Unit of Account	0
XXX	No Currency	0
XBT	Bitcoin	8
BTC	Bitcoin	8
ADA	Cardano	6
BCH	Bitcoin Cash	8
BNB	Binance Coin	18
CRO	Cronos	18
DAI	Dai	18
DOGE	Dogecoin	8
ETH	Ethereum	18
LINK	Chainlink	18
LTC	Litecoin	8
POL	Polygon	18
SAND	The Sandbox	18
SOL	Solana	9
TRX	TRON	6
UNI	Uniswap	18
USDC	USD Coin	6
USDT	Tether	6
XRP	Ripple	6

Date And Time

Date and Time are passed in Unix Timestamp using UTC timezone (epochconverter) - number of milliseconds from the epoch of 1970-01-01T00:00:00Z.
Examples: 2024-03-15T11:42:03+00:00 = '1710499323000'

Locale

User's locale should be passed in ISO-639 + '_' + ISO-3166 format (ISO-639, ISO-3166).

Locales:

Locale	Region
af_ZA	Afrikaans (South Africa)
ar_AR	Arabic
ar_AE	Arabic (U.A.E.)
ar_BH	Arabic (Bahrain)
ar_DZ	Arabic (Algeria)
ar_EG	Arabic (Egypt)
ar_IQ	Arabic (Iraq)
ar_JO	Arabic (Jordan)
ar_KW	Arabic (Kuwait)
ar_LB	Arabic (Lebanon)
ar_LY	Arabic (Libya)
ar_MA	Arabic (Morocco)
ar_OM	Arabic (Oman)
ar_QA	Arabic (Qatar)
ar_SA	Arabic (Saudi Arabia)
ar_SY	Arabic (Syria)
ar_TN	Arabic (Tunisia)
ar_YE	Arabic (Yemen)
az_AZ	Azeri (Latin) (Azerbaijan)
be_BY	Belarusian (Belarus)
bg_BG	Bulgarian (Bulgaria)
bs_BA	Bosnian (Bosnia and Herzegovina)
ca_ES	Catalan (Spain)
cs_CZ	Czech (Czech Republic)
cy_GB	Welsh (United Kingdom)
da_DK	Danish (Denmark)
de_AT	German (Austria)
de_CH	German (Switzerland)
de_DE	German (Germany)
de_LI	German (Liechtenstein)
de_LU	German (Luxembourg)
dv_MV	Divehi (Maldives)
el_GR	Greek (Greece)
el_EL	Greek (Greece)
en_AU	English (Australia)
en_BZ	English (Belize)
en_CA	English (Canada)
en_CB	English (Caribbean)
en_GB	English (United Kingdom)
en_IE	English (Ireland)
en_JM	English (Jamaica)
en_NZ	English (New Zealand)
en_PH	English (Republic of the Philippines)
en_TT	English (Trinidad and Tobago)
en_US	English (United States)
en_ZA	English (South Africa)
en_ZW	English (Zimbabwe)
es_AR	Spanish (Argentina)
es_BO	Spanish (Bolivia)
es_CL	Spanish (Chile)
es_CO	Spanish (Colombia)
es_CR	Spanish (Costa Rica)
es_DO	Spanish (Dominican Republic)
es_EC	Spanish (Ecuador)
es_ES	Spanish (Spain)
es_GT	Spanish (Guatemala)
es_HN	Spanish (Honduras)
es_MX	Spanish (Mexico)
es_NI	Spanish (Nicaragua)
es_PA	Spanish (Panama)
es_PE	Spanish (Peru)
es_PR	Spanish (Puerto Rico)
es_PY	Spanish (Paraguay)
es_SV	Spanish (El Salvador)
es_UY	Spanish (Uruguay)
es_VE	Spanish (Venezuela)
et_EE	Estonian (Estonia)
eu_ES	Basque (Spain)
fa_IR	Farsi (Iran)
fi_FI	Finnish (Finland)
fo_FO	Faroese (Faroe Islands)
fr_BE	French (Belgium)
fr_CA	French (Canada)
fr_CH	French (Switzerland)
fr_FR	French (France)
fr_LU	French (Luxembourg)
fr_MC	French (Principality of Monaco)
gl_ES	Galician (Spain)
gu_IN	Gujarati (India)
he_IL	Hebrew (Israel)
hi_IN	Hindi (India)
hr_BA	Croatian (Bosnia and Herzegovina)
hr_HR	Croatian (Croatia)
hu_HU	Hungarian (Hungary)
hy_AM	Armenian (Armenia)
id_ID	Indonesian (Indonesia)
is_IS	Icelandic (Iceland)
it_CH	Italian (Switzerland)
it_IT	Italian (Italy)
ja_JP	Japanese (Japan)
ka_GE	Georgian (Georgia)
kk_KZ	Kazakh (Kazakhstan)
kn_IN	Kannada (India)
ko_KR	Korean (Korea)
kok_IN	Konkani (India)
ky_KG	Kyrgyz (Kyrgyzstan)
lt_LT	Lithuanian (Lithuania)
lv_LV	Latvian (Latvia)
mi_NZ	Maori (New Zealand)
mk_MK	FYRO Macedonian (Former Yugoslav Republic of Macedonia)
mn_MN	Mongolian (Mongolia)
mr_IN	Marathi (India)
ms_BN	Malay (Brunei Darussalam)
ms_MY	Malay (Malaysia)
mt_MT	Maltese (Malta)
nb_NO	Norwegian (Bokm?l) (Norway)
nl_BE	Dutch (Belgium)
nl_NL	Dutch (Netherlands)
nn_NO	Norwegian (Nynorsk) (Norway)
ns_ZA	Northern Sotho (South Africa)
pa_IN	Punjabi (India)
pl_PL	Polish (Poland)
ps_AR	Pashto (Afghanistan)
pt_BR	Portuguese (Brazil)
pt_PT	Portuguese (Portugal)
qu_BO	Quechua (Bolivia)
qu_EC	Quechua (Ecuador)
qu_PE	Quechua (Peru)
ro_RO	Romanian (Romania)
ru_RU	Russian (Russia)
sa_IN	Sanskrit (India)
se_FI	Sami (Northern) (Finland)
se_NO	Sami (Northern) (Norway)
se_SE	Sami (Northern) (Sweden)
sk_SK	Slovak (Slovakia)
sl_SI	Slovenian (Slovenia)
sq_AL	Albanian (Albania)
sr_BA	Serbian (Latin) (Bosnia and Herzegovina)
sr_SP	Serbian (Latin) (Serbia and Montenegro)
sv_FI	Swedish (Finland)
sv_SE	Swedish (Sweden)
sw_KE	Swahili (Kenya)
syr_SY	Syriac (Syria)
ta_IN	Tamil (India)
te_IN	Telugu (India)
th_TH	Thai (Thailand)
tl_PH	Tagalog (Philippines)
tn_ZA	Tswana (South Africa)
tr_TR	Turkish (Turkey)
tt_RU	Tatar (Russia)
uk_UA	Ukrainian (Ukraine)
ur_PK	Urdu (Islamic Republic of Pakistan)
uz_UZ	Uzbek (Latin) (Uzbekistan)
vi_VN	Vietnamese (Viet Nam)
xh_ZA	Xhosa (South Africa)
zh_CN	Chinese (S)
zh_HK	Chinese (Hong Kong)
zh_MO	Chinese (Macau)
zh_SG	Chinese (Singapore)
zh_TW	Chinese (T)
zu_ZA	Zulu (South Africa)

Security

Each request between casino and aggregator provider and vice versa must contain basic auth header (Basic access authentication)
Example for username 'name' and password 'password':
Authorization: Basic bmFtZTpwYXNzd29yZA==

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"48907826","collectionId":"cff87b0a-f239-4ae5-b249-3a4236af4508","publishedId":"2sBXwnsXYK","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-06-12T13:55:07.000Z"},"item":[{"name":"Casino Aggregator API","item":[{"name":"Aggregator API","item":[{"name":"Games API","item":[{"name":"Get Game Link","id":"2c46b2d1-44c5-4a22-9649-b72bd7f627a3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"gameId\": \"234f4893-6bdc-4dea-82bb-6e351976836e\",\n \"urls\": {\n \"returnUrl\": \"https://example.com\",\n \"depositUrl\": \"https://example.com\"\n },\n \"user\": {\n \"externalId\": \"externalId\",\n \"username\": \"test\",\n \"name\": \"test\",\n \"surname\": \"test\",\n \"honorific\": \"Mr\",\n \"ip\": \"0.0.0.0\",\n \"locale\": \"tr_TR\",\n \"device\": {\n \"operatingSystem\": \"LINUX\",\n \"platform\": \"BROWSER\"\n },\n \"currency\": \"TRY\"\n },\n \"session\": {\n \"externalId\": \"your-session-id\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/games/link","description":"

Returns the Landing URL of the chosen game. Casino has to forward User to returned URL. There are several ways to forward the User:

Embed URL into iframe on your site;
\n
Redirect User to URL;
\n
Open URL in new window/tab of browser.
\n

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
gameId(string, required) - Id from get games request
\n
urls (object, required)
\n
- returnUrl (string, required) - Url to provider page on casino
  \n
- depositUrl (string required) - Url to deposit page on casino
  \n
\n
user (object, required)
\n
- externalId (string, required) - User id in casino system. Must be unique
  \n
- username (string, required)
  \n
- name (string, optional)
  \n
- surname (string, optional)
  \n
- honorific (enum, optional) - Values: 'Mr', 'Mrs', 'Ms', 'Miss'
  \n
- ip (string, required)
  \n
- locale (string, required)
  \n
- device (object, required)
  \n
  - operatingSystem (enum, required) - Values 'WINDOWS', 'LINUX', 'MACOS', 'IOS', 'ANDROID'
    \n
  - platform (enum, required) - Values 'BROWSER', 'NATIVE'
    \n
  \n
- currency (string, required) - User currency
  \n
\n
session (object, optional)
\n
- externalId (string, required) - Session Id in casino system. Will be attached to callbacks in Casino API, see session object
\n

Response Body Description:

Object:

link(string, required) - Link to open game

Returns the Landing URL of the chosen game in Demo mode.

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
gameId(string, required) - Id from get games request
\n
urls (object, required)
\n
- returnUrl (string, required) - Url to provider page on casino
  \n
- depositUrl (string required) - Url to deposit page on casino
  \n
\n
user (object, required)
\n
- ip (string, required)
  \n
- locale (string, required)
  \n
- device (object, required)
  \n
  - operatingSystem (enum, required) - Values 'WINDOWS', 'LINUX', 'MACOS', 'IOS', 'ANDROID'
    \n
  - platform (enum, required) - Values 'BROWSER', 'NATIVE'
    \n
  \n
\n

Response Body Description:

Object:

link(string, required) - Link to open game

Returns the list of games available for brand

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
provider (string, optional) - Provider which games should be returned. If not present all games will be returned
\n

Response Body Description:

List of Objects:

id (string, required) - Id of the game. Unique among all games
\n
providerGameId (string, required) - Id of the game in provider system.
\n
name (string, required)
\n
isActive (boolean, required)
\n
isDemoAvailable (boolean, required)
\n
isFreeBonusBuyAvailable (boolean, required) - if this game is applicable for free bonus buys
\n
previewImages (list of objects, required)
\n
- size (enum, required) - Values: 'S', 'M', 'L'
  \n
- url (string, required) - Url to game's preview image
  \n
\n
backgroundImageUrl (string, optional) - Url to game's background image
\n
provider (string, required) - Provider name
\n
product (enum, required) - Values: 'LIVE_CASINO', 'CASINO', 'GAMES', 'VIRTUAL'
\n
createdAt (long, required) - Created at timestamp
\n
devices (list of enums, required) - Values: 'DESKTOP', 'MOBILE'
\n
gameTags (list of objects, required)
\n
- id (string, required)
  \n
- name (string, required)
  \n
\n
betValues (list of objects, required) - Bet values to create free spins
\n
- currency (string, required) - Bet value currency
  \n
- values (list of long, required) - Possible free spins bets values. Values are in Money format
  \n
\n
rtp (object, optional) - Game RTP value
\n
- type (string, required) - RTP object type (Fixed)
  \n
- value (double, required) - RTP value
  \n
\n

Returns details about game providers.

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider

Response Body Description:

List of Objects:

name (string, required) - Provider name
\n
roundHistory (boolean, required)
\n
products (list of enum, required) - Values: 'VIRTUAL', 'GAMES', 'LIVE_CASINO', 'CASINO', 'SPORTS', 'POKER'
\n
bonuses (list of enum, required) - Values: 'FREE_SPINS'
\n

Retursn jackpot feed. Process of fetching jackpot data is asynchronious and it's expected to use some sort of polling mechanism to get latest jackpot details.

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
providers (string array, required) - Ids of providers to fetch jackpots
\n
currency (enum, required) - Currency of jackpot
\n

Response Body Description:

Response body is a dedicated jackpot pool

List of Objects:

provider (string, required) - Provider name
\n
name (string, optional) - Name of a jackpot given by provider
\n
gameIds (string array, optional) - Game ids applicable for jackpot
\n
tiers (object array, required) - Tiers for that pool
\n
- level (int, required) - Jackpot level
  \n
- amount (long, required) - Jackpot amount
  \n
- currency (enum, required) - Jackpot amount currency
  \n
- winnersCount (int, optional) - Jackpot Tier winner count given by provider
  \n
\n

Provides methods to display and launch games on a Casino.

\n","event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"42d3e40b-e97b-44f4-890c-a81533946245"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"3f6b26c2-0e78-45da-9b52-b8c2b76cc06c"}}],"_postman_id":"23b1bc3d-c1e8-45a4-ac7e-91568ed26d72","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{username}"},{"key":"password","value":"{password}"}]},"isInherited":true,"source":{"_postman_id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","name":"Casino Aggregator API","type":"folder"}}},{"name":"Free Spins API","item":[{"name":"Get Player Active Free Spins","id":"36f6146b-3ba0-4eab-9619-151bf8562445","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"externalId\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/free-spins","description":"

Returns currently active player Free Spins.

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
externalUserId (string, required) - User id in casino system
\n

Response Body Description:

List of Objects:

externalFreeSpinsId (string, required) - Id of Free Spins in casino system
\n
internalUserId (string, required) - User id in aggregator provider system
\n
externalUserId (string, required) - User id in casino system
\n
gameIds (string array, required) - Ids from get games request
\n
betValue (object, required) - Bet value from games request
\n
- currency (string, required) - Bet value currency
  \n
- value (long, required) - Bet value from games request. In Money format
  \n
\n
amount (integer, required) - Amount of free spins
\n
currentAmount (integer, required) - Amount of used free spins
\n
startDate (long, required) - Free Spins start date timestamp
\n
endDate (long, required) - Free Spins end date timestamp
\n

Endpoint for creating Free Spins

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
externalFreeSpinsId (string, required) - Id of Free Spins in casino system
\n
user (object, required)
\n
- externalId (string, required) - User id in casino system. Must be unique
  \n
- username (string, required)
  \n
- name (string, optional)
  \n
- surname (string, optional)
  \n
- honorific (enum, optional) - Values: 'Mr', 'Mrs', 'Ms', 'Miss'
  \n
- currency (string, required) - User currency
  \n
- locale (string, required)
  \n
\n
gameId (string, required) - Id from get games request
\n
amount (integer, required) - Amount of free spins
\n
betValue (object, required) - Bet value from games request
\n
- currency (string, required) - Bet value code currency
  \n
- value (long, required) - Bet value from games request. In Money format
  \n
\n
startDate (long, required) - Free Spins start date timestamp
\n
endDate (long, required) - Free Spins end date timestamp
\n

Response Body Description:

Object:

externalFreeSpinsId (string, required) - Id of Free Spins in casino system
\n
internalUserId (string, required) - User id in aggregator provider system
\n
externalUserId (string, required) - User id in casino system
\n
gameId (string, optional) - Id from get games request
\n
gameIds (string array, optional) - Ids from get games request, either gameId or gameIds should be present. If both provided behaviour is undefined
\n
betValue (object, required) - Bet value from games request
\n
- currency (string, required) - Bet value code currency
  \n
- value (long, required) - Bet value from games request. In Money format
  \n
\n
startDate (long, required) - Free Spins start date timestamp
\n
endDate (long, required) - Free Spins end date timestamp
\n

Endpoint for creating Free Spins

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
externalFreeSpinsId (string, required) - Id of Free Spins in casino system
\n
user (object, required)
\n
- externalId (string, required) - User id in casino system. Must be unique
  \n
- username (string, required)
  \n
- name (string, optional)
  \n
- surname (string, optional)
  \n
- honorific (enum, optional) - Values: 'Mr', 'Mrs', 'Ms', 'Miss'
  \n
- currency (string, required) - User currency
  \n
- locale (string, required)
  \n
\n
gameIds (string array, required) - Ids from get games request
\n
betValue (object, required) - Bet value from games request
\n
- currency (string, required) - Bet value code currency
  \n
- value (long, required) - Bet value from games request. In Money format
  \n
\n
startDate (long, required) - Free Spins start date timestamp
\n
endDate (long, required) - Free Spins end date timestamp
\n

Response Body Description:

Object:

externalFreeSpinsId (string, required) - Id of Free Spins in casino system

Endpoint for cancelling Free Spins

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
externalFreeSpinsId (string, required) - Id of Free Spins in casino system
\n
externalUserId (string, required) - User id in casino system
\n

Response Body Description:

Object:

internalUserId (string, required) - User id in aggregator provider system
\n
externalUserId (string, required) - User id in casino system
\n
externalFreeSpinsId (string, required) - Id of Free Spins in casino system
\n

Provides methods to manage rewards (freespins, freebets, prizes).

\n","event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"9170c482-9e2b-475d-88f5-32b654cc2908"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"ad35bcc4-40f4-4f01-91e0-a036b51ef943"}}],"_postman_id":"508dfbec-90be-4a3c-b712-95935bee278c","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{username}"},{"key":"password","value":"{password}"}]},"isInherited":true,"source":{"_postman_id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","name":"Casino Aggregator API","type":"folder"}}},{"name":"Lobby API","item":[{"name":"Get Lobby Link","id":"0244a303-61e7-4e56-bb84-f65f1a935f5c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"urls\": {\n \"returnUrl\": \"https://example.com\",\n \"depositUrl\": \"https://example.com\"\n },\n \"user\": {\n \"externalId\": \"externalId\",\n \"username\": \"test\",\n \"name\": \"test\",\n \"surname\": \"test\",\n \"honorific\": \"Mr\",\n \"ip\": \"0.0.0.0\",\n \"locale\": \"tr_TR\",\n \"device\": {\n \"operatingSystem\": \"LINUX\",\n \"platform\": \"BROWSER\"\n },\n \"currency\": \"TRY\"\n },\n \"session\": {\n \"externalId\": \"your-session-id\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/lobby/link","description":"

Returns the Landing URL of the Lobby.

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
urls (object, required)
\n
- returnUrl (string, required) - Url to provider page on casino
  \n
- depositUrl (string, required) - Url to deposit page on casino
  \n
\n
user (object, required)
\n
- externalId (string, required) - User id in casino system. Must be unique
  \n
- username (string, required)
  \n
- name (string, optional)
  \n
- surname (string, optional)
  \n
- honorific (enum, optional) - Values: 'Mr', 'Mrs', 'Ms', 'Miss'
  \n
- ip (string, required)
  \n
- locale (string, required)
  \n
- device (object, required)
  \n
  - operatingSystem (enum, required) - Values 'WINDOWS', 'LINUX', 'MACOS', 'IOS', 'ANDROID'
    \n
  - platform (enum, required) - Values 'BROWSER', 'NATIVE'
    \n
  \n
- currency (string, required) - User currency
  \n
\n
session (object, optional)
\n
- externalId (string, required) - Session Id in casino system. Will be attached to callbacks in Casino API, see session object
\n

Response Body Description:

Object:

link(string, required) - Link to open lobby

Returns the Landing URL of the Demo Lobby.

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
urls (object, required)
\n
- returnUrl (string, required) - Url to provider page on casino
  \n
- depositUrl (string, required) - Url to deposit page on casino
  \n
\n
user (object, required)
\n
- ip (string, required)
  \n
- locale (string, required)
  \n
- device (object, required)
  \n
  - operatingSystem (enum, required) - Values 'WINDOWS', 'LINUX', 'MACOS', 'IOS', 'ANDROID'
    \n
  - platform (enum, required) - Values 'BROWSER', 'NATIVE'
    \n
  \n
\n

Response Body Description:

Object:

link(string, required) - Link to open lobby

Provides methods to show Games Lobby.

Games Lobby contains all games availbale to brand and ready to play

\n","event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"7e730260-6efb-497e-9ec6-04bab9b97353"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"97e68375-1d4a-4900-a831-a5ceafeb7ca5"}}],"_postman_id":"9264259b-7b40-4169-8bd1-4fb87aded43a","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{username}"},{"key":"password","value":"{password}"}]},"isInherited":true,"source":{"_postman_id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","name":"Casino Aggregator API","type":"folder"}}},{"name":"Round API","item":[{"name":"Get Private Round History","id":"01b75b86-d3c5-4611-9bc5-ff41624af71e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"externalId\",\n \"roundId\": \"6a95ba3a-1448-4824-998c-045552421f62\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/round/private/history","description":"

Returns the URL of a game round detail. Designed for Backoffice usage, because there might be sensitive data here.

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider i
\n
externalUserId (string, required) - User id in casino system
\n
roundId (string, required) - Id of the round
\n

Response Body Description:

Object:

value (string, required) - URL that contains round info in provider system, it's preferred to insert it into iframe.src attribut

Returns the URL of a game round replay. This API should be only used to retrive replays for rounds with big multipliers.

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider i
\n
externalUserId (string, required) - User id in casino system
\n
roundId (string, required) - Id of the round
\n

Response Body Description:

Object:

value (string, required) - URL that contains round replay in provider system, it's preferred to insert it into iframe.src attribut

Returns the URL of a game round detail. Designed for Public usage, i.e. you can use this API to display link on your Player UI.

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider i
\n
externalUserId (string, required) - User id in casino system
\n
roundId (string, required) - Id of the round
\n

Response Body Description:

Object:

value (string, required) - URL that contains round info in provider system, it's preferred to insert it into iframe.src attribut

This report returns all the game rounds that were started by a certain player but not completed yet.
Customer is expected to use this API

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider i
\n
externalUserId (string, required) - User id in casino system
\n
providers (string array, optional) - Provider value received from providers endpoint, if no given - all prvoiders will be used
\n
products (enum array, optional) - Values: 'LIVE_CASINO', 'CASINO', 'GAMES', 'VIRTUAL', if empty will search for all products
\n

Response Body Description:

Array of objects:

id (string, required) - ID of pending round
\n
gameId (string, required) - game identifier
\n
betAmount (number, required) - pending bet amount
\n
currency (enum, required) - round currency
\n

Requests sent from Casino to Aggregator Provider

\n","event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"50f7b66c-2005-4e9b-b715-2cce5fe50329"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"5a5ddc99-ae68-4df8-9ade-b3425cdb5f81"}}],"_postman_id":"ee254cf7-0b95-41f2-b462-69dcfc4514a9","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{username}"},{"key":"password","value":"{password}"}]},"isInherited":true,"source":{"_postman_id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","name":"Casino Aggregator API","type":"folder"}}},{"name":"Casino API","item":[{"name":"Get Balance","id":"77773b9d-6a91-4ff8-b55f-baf50ba574db","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"internalUserId\": \"037ee5a8-d09f-4b0a-9f5d-dc5d12d0d48b\",\n \"externalUserId\": \"externalId\",\n \"currency\": \"TRY\",\n \"session\": {\n \"externalId\": \"your-session-id\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{callbackUrl}/get-balance","description":"

Called when player's balance is needed. Casino is expected to return player's current balance

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
internalUserId (string, required) - User id in aggregator provider system
\n
externalUserId (string, required) - User id in casino system
\n
currency (string, required) - User currency
\n
provider (string, optional) - Provider which requests the balance. This value might not be available in certain situations
\n
session (object, optional)
\n
- externalId (string, required) - Session Id in casino system received on game launch
\n
gameId(string, optional) - Game Id
\n

Response Body Description:

Object:

externalUserId (string, required) - User id in casino system
\n
balance (long, required) - In Money format
\n
currency (string, required) - User currency
\n

Endpoint used for various transactions:

BET - Called when the User places a bet.
\n
WIN - Called when the User wins.
\n
ROLLBACK - Called when there is need to roll back the effect of the referenced transaction.
\n
FREE_SPINS_BET - Called when the User places a Free Spins bet.
\n
FREE_SPINS_WIN - Called when the User wins in Free Spins round.
\n

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
internalUserId (string, required) - User id in aggregator provider system
\n
externalUserId (string, required) - User id in casino system
\n
txType (enum, required) - Values: 'BET', 'WIN', 'ROLLBACK', 'FREE_SPINS_BET', 'FREE_SPINS_WIN'
\n
txId (string, required) - Id of the transaction. Unique among all txs
\n
roundId (string, required) - Id of the round in aggregator system
\n
providerRoundId (string, required) - Id of the round in provider system
\n
isForced (boolean, required) - BET should be accepted even if player doesn't have enough money on balance (balance can go negative)
\n
isJackpot (boolean, required) - Indicates if current transaction is related to jackpot
\n
isBonusBuy (boolean, required) - Indicates if current transaction is related to bonus buy
\n
isRoundFinished (boolean, required)
\n
isPromotion (boolean, required) - Transaction is related to a promotion bet / win
\n
amount (long, required) - Transaction amount. In Money format
\n
currency (string, required) - User currency
\n
provider (string, required) - Provider name
\n
rolledBackTxId (string, optional) - Not null in case of rollback. Tx id to rollback
\n
externalFreeSpinsId (string, optional) - Not null in case of free spins transaction
\n
gameId (string, optional) - Id from get games request. Can be null in case of jackpots, tips etc
\n
timestamp (long, required) - Transaction process timestamp in aggregator provider system
\n
session (object, optional)
\n
- externalId (string, required) - Session Id in casino system received on game launch
\n
details (object, optional) - Sportsbook bet context. Populated only for sportsbook transactions; null for casino game transactions. See \"Sportsbook Scheme\" folder for the schema.
\n

Response Body Description:

Object:

txId (string, required) - Transaction id in casino system
\n
externalUserId (string, required) - User id in casino system
\n
balance (long, required) - Balance after transaction. In Money format
\n
currency (string, required) - User currency
\n

\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{username}"},{"key":"password","value":"{password}"}]},"isInherited":true,"source":{"_postman_id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","name":"Casino Aggregator API","type":"folder"}},"urlObject":{"path":["transaction"],"host":["{callbackUrl}"],"query":[],"variable":[]}},"response":[{"id":"5e3fd44b-549e-4331-b239-9220e0c8f6cc","name":"bet","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Basic e3VzZXJuYW1lfTp7cGFzc3dvcmR9","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"internalUserId\": \"037ee5a8-d09f-4b0a-9f5d-dc5d12d0d48b\",\n \"externalUserId\": \"externalId\",\n \"txType\": \"BET\",\n \"txId\": \"af7d269d-c6c7-472a-a4c7-b73b9d78ab24\",\n \"roundId\": \"6a95ba3a-1448-4824-998c-045552421f62\",\n \"providerRoundId\": \"providerRoundId\",\n \"isForced\": false,\n \"isRoundFinished\": false,\n \"amount\": 200,\n \"currency\": \"TRY\",\n \"provider\": \"provider\",\n \"rolledBackTxId\": null,\n \"externalFreeSpinsId\": null,\n \"gameId\": \"234f4893-6bdc-4dea-82bb-6e351976836e\",\n \"timestamp\": 1710772705668,\n \"isJackpot\": false,\n \"isBonusBuy\": true,\n \"session\": {\n \"externalId\": \"your-session-id\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{callbackUrl}/transaction"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"txId\": \"845676317\",\n \"externalUserId\": \"externalId\",\n \"balance\": \"133937020\",\n \"currency\": \"TRY\"\n}"},{"id":"fa8be0e5-37f3-439e-98dc-efd7487db139","name":"fail - bet","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Basic e3VzZXJuYW1lfTp7cGFzc3dvcmR9","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"internalUserId\": \"037ee5a8-d09f-4b0a-9f5d-dc5d12d0d48b\",\n \"externalUserId\": \"externalId\",\n \"txType\": \"BET\",\n \"txId\": \"af7d269d-c6c7-472a-a4c7-b73b9d78ab24\",\n \"roundId\": \"6a95ba3a-1448-4824-998c-045552421f62\",\n \"providerRoundId\": \"providerRoundId\",\n \"isForced\": false,\n \"isRoundFinished\": false,\n \"amount\": 20000,\n \"currency\": \"TRY\",\n \"provider\": \"provider\",\n \"rolledBackTxId\": null,\n \"externalFreeSpinsId\": null,\n \"gameId\": \"234f4893-6bdc-4dea-82bb-6e351976836e\",\n \"timestamp\": 1710772705668,\n \"isJackpot\": false,\n \"isBonusBuy\": true,\n \"session\": {\n \"externalId\": \"your-session-id\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{callbackUrl}/transaction"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\" : 106,\n \"errorMessage\" : \"Not enough funds\"\n}"},{"id":"10d90634-4ceb-4970-a86c-a4761c03123a","name":"free spins bet","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Basic e3VzZXJuYW1lfTp7cGFzc3dvcmR9","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"internalUserId\": \"037ee5a8-d09f-4b0a-9f5d-dc5d12d0d48b\",\n \"externalUserId\": \"externalId\",\n \"txType\": \"FREE_SPINS_BET\",\n \"txId\": \"af7d269d-c6c7-472a-a4c7-b73b9d78ab24\",\n \"roundId\": \"6a95ba3a-1448-4824-998c-045552421f62\",\n \"providerRoundId\": \"providerRoundId\",\n \"isForced\": false,\n \"isRoundFinished\": false,\n \"amount\": 0,\n \"currency\": \"TRY\",\n \"provider\": \"provider\",\n \"rolledBackTxId\": null,\n \"externalFreeSpinsId\": \"05699a64-e4a0-4091-86cd-b5e9d3823f67\",\n \"gameId\": \"234f4893-6bdc-4dea-82bb-6e351976836e\",\n \"timestamp\": 1710772705668,\n \"isJackpot\": false,\n \"isBonusBuy\": true,\n \"session\": {\n \"externalId\": \"your-session-id\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{callbackUrl}/transaction"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"txId\": \"123676317\",\n \"externalUserId\": \"externalId\",\n \"balance\": \"133937020\",\n \"currency\": \"TRY\"\n}"},{"id":"8fa2835a-9419-4079-b0ab-42abb6c65ad3","name":"rollback","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Basic e3VzZXJuYW1lfTp7cGFzc3dvcmR9","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"internalUserId\": \"037ee5a8-d09f-4b0a-9f5d-dc5d12d0d48b\",\n \"externalUserId\": \"externalId\",\n \"txType\": \"ROLLBACK\",\n \"txId\": \"af7d269d-c6c7-472a-a4c7-b73b9d78ab24\",\n \"roundId\": \"6a95ba3a-1448-4824-998c-045552421f62\",\n \"providerRoundId\": \"providerRoundId\",\n \"isForced\": false,\n \"isRoundFinished\": true,\n \"amount\": 200,\n \"currency\": \"TRY\",\n \"provider\": \"provider\",\n \"rolledBackTxId\": \"0192f780-33d8-7481-a8ae-d331c9ba50e2\",\n \"externalFreeSpinsId\": null,\n \"gameId\": \"234f4893-6bdc-4dea-82bb-6e351976836e\",\n \"timestamp\": 1710772705668,\n \"isJackpot\": false,\n \"isBonusBuy\": true,\n \"session\": {\n \"externalId\": \"your-session-id\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{callbackUrl}/transaction"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"txId\": \"735676317\",\n \"externalUserId\": \"externalId\",\n \"balance\": \"133938120\",\n \"currency\": \"TRY\"\n}"},{"id":"9744371a-2fb9-4634-9a5c-53cd04c994a5","name":"win","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Basic e3VzZXJuYW1lfTp7cGFzc3dvcmR9","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"internalUserId\": \"037ee5a8-d09f-4b0a-9f5d-dc5d12d0d48b\",\n \"externalUserId\": \"externalId\",\n \"txType\": \"WIN\",\n \"txId\": \"af7d269d-c6c7-472a-a4c7-b73b9d78ab24\",\n \"roundId\": \"6a95ba3a-1448-4824-998c-045552421f62\",\n \"providerRoundId\": \"providerRoundId\",\n \"isForced\": false,\n \"isRoundFinished\": true,\n \"amount\": 200,\n \"currency\": \"TRY\",\n \"provider\": \"provider\",\n \"rolledBackTxId\": null,\n \"externalFreeSpinsId\": null,\n \"gameId\": \"234f4893-6bdc-4dea-82bb-6e351976836e\",\n \"timestamp\": 1710772705668,\n \"isJackpot\": false,\n \"isBonusBuy\": true,\n \"session\": {\n \"externalId\": \"your-session-id\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{callbackUrl}/transaction"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"txId\" : \"145676328\",\n \"externalUserId\" : \"externalId\",\n \"balance\" : \"133938020\",\n \"currency\" : \"TRY\"\n }"},{"id":"66d32ef9-43c7-4f8f-8020-478e3bb0e2ec","name":"free spins win","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Basic e3VzZXJuYW1lfTp7cGFzc3dvcmR9","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"internalUserId\": \"037ee5a8-d09f-4b0a-9f5d-dc5d12d0d48b\",\n \"externalUserId\": \"externalId\",\n \"txType\": \"FREE_SPINS_WIN\",\n \"txId\": \"af7d269d-c6c7-472a-a4c7-b73b9d78ab24\",\n \"roundId\": \"6a95ba3a-1448-4824-998c-045552421f62\",\n \"providerRoundId\": \"providerRoundId\",\n \"isForced\": false,\n \"isRoundFinished\": true,\n \"amount\": 200,\n \"currency\": \"TRY\",\n \"provider\": \"provider\",\n \"rolledBackTxId\": null,\n \"externalFreeSpinsId\": \"05699a64-e4a0-4091-86cd-b5e9d3823f67\",\n \"gameId\": \"234f4893-6bdc-4dea-82bb-6e351976836e\",\n \"timestamp\": 1710772705668,\n \"isJackpot\": false,\n \"isBonusBuy\": true,\n \"session\": {\n \"externalId\": \"your-session-id\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{callbackUrl}/transaction"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"txId\" : \"441676328\",\n \"externalUserId\" : \"externalId\",\n \"balance\" : \"133938020\",\n \"currency\" : \"TRY\"\n }"}],"_postman_id":"e0372ad2-57fb-4067-b901-6417f894914f"},{"name":"End Round","id":"cbefb9a0-e5d4-4323-9cfa-8ebcf833370b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"internalUserId\": \"037ee5a8-d09f-4b0a-9f5d-dc5d12d0d48b\",\n \"externalUserId\": \"externalId\",\n \"roundId\": \"6a95ba3a-1448-4824-998c-045552421f62\",\n \"providerRoundId\": \"providerRoundId\",\n \"isRoundFinished\": true,\n \"currency\": \"TRY\",\n \"provider\": \"provider\",\n \"gameId\": \"234f4893-6bdc-4dea-82bb-6e351976836e\",\n \"timestamp\": 1710772705668,\n \"session\": {\n \"externalId\": \"your-session-id\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{callbackUrl}/end-round","description":"

Called to notify about round end.

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
internalUserId (string, required) - User id in aggregator provider system
\n
externalUserId (string, required) - User id in casino system
\n
roundId (string, required) - Id of the round
\n
providerRoundId (string, required) - Id of the round in provider system
\n
isRoundFinished (boolean, required)
\n
currency (string, required) - User currency
\n
provider (string, required) - Provider name
\n
gameId (string, optional) - Id from get games request. Can be null in case of jackpots, tips etc
\n
timestamp (long, required) - End round timestamp in aggregator provider system
\n
session (object, optional)
\n
- externalId (string, required) - Session Id in casino system received on game launch
\n
details (object, optional) - Sportsbook bet context. Populated only for sportsbook transactions; null for casino game transactions. See \"Sportsbook Scheme\" folder for the schema.
\n

Response Body Description:

Object:

externalUserId (string, required) - User id in casino system
\n
balance (long, required) - Balance in Money format
\n
currency (string, required) - User currency
\n

Called to notify about free spins completion.

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
internalUserId (string, required) - User id in aggregator provider system
\n
externalUserId (string, required) - User id in casino system
\n
externalFreeSpinsId (string, required) - Free spins id that you used for its create
\n
currency (enum, required) - Currency of rpvodied amounts
\n
totalWinAmount (long, required) - Total winning amount of a free spin
\n
txId (string, required) - Free spins total win transaction id for operation idempotency
\n

Response Body Description:

Object:

externalUserId (string, required) - User id in casino system
\n
balance (long, required) - In Money format
\n
currency (string, required) - User currency
\n

Called to fetch player details by provided token.

This API is optional, it might become mandatory to be implemented depending on the product scope received by the casino

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider
\n
token (string, required) - Token received from integration that will allow it to fetch player details
\n

Response Body Description:

Object:

externalUserId (string, required) - User id in casino system
\n
username (string, required)
\n
name (string, optional)
\n
surname (string, optional)
\n
honorific (enum, optional) - Values: 'Mr', 'Mrs', 'Ms', 'Miss'
\n

Requests sent from Aggregator Provider to Casino

\n","event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"c6590a27-dc88-4b63-a79f-301d59369022"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"62352c3c-1aea-4a4b-b976-80b190303b8f"}}],"_postman_id":"8cf8d392-ab55-4c73-ac34-2d9330409293","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{username}"},{"key":"password","value":"{password}"}]},"isInherited":true,"source":{"_postman_id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","name":"Casino Aggregator API","type":"folder"}}}],"id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{username}"},{"key":"password","value":"{password}"}]},"isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"f6f7c879-aa4e-4886-9d19-12b839cc4787"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"86f94022-fff1-4a32-8bb4-967edd8fd12b"}}],"_postman_id":"28e4b9aa-5074-4e38-a307-dc748b3b33b8","description":""},{"name":"Sportsbook Scheme","item":[{"name":"Transaction Details","item":[],"id":"4a13db02-fd13-4fca-aac0-fe7094548113","description":"

Transaction Details

Schema of the details object attached to sportsbook-originated Transaction and End Round callbacks.

Populated only for sportsbook transactions; null for casino game transactions.

Object

method (enum, required) - Sportsbook event that triggered the notify. Values: 'ACCOUNT_DETAILS', 'EDIT_BET', 'BET_CANCELED', 'CREATE_BET_BATCH', 'CREATE_BET', 'BET_SETTLED', 'BET_CASH_OUT', 'BET_PARTIAL_CASH_OUT', 'BET_CREATE_FAILED', 'BET_ODDS_BOOST_SETTLED', 'BET_ODDS_BOOST_CANCELED', 'CREATE_FORECAST', 'SETTLE_FORECAST', 'CANCEL_FORECAST'
\n
bet (object, required) - Snapshot of the underlying sportsbook bet (see Bet section below)
\n
bonus (object, optional) - Bonus associated with a transaction
\n
- playerBonusId (string, required) - Identifier of a player bonus
\n

Bet (details.bet):

betId (string, required) - Bet id in sportsbook system
\n
totalCoefficient (double, required) - Total bet coefficient
\n
eventPicks (array, required) - Picks placed on regular sport events (see Event Pick section)
\n
outrightPicks (array, required) - Picks placed on outright (long-term) markets (see Outright Pick section)
\n
createTime (long, required) - Timestamp in milliseconds when the bet was placed
\n
anyPickForLiveEvent (boolean, required) - True if at least one pick in the bet was placed on a live event
\n
betStructure (object, required) - Structural summary of the bet (see \"Bet Structure\" section in this folder)
\n
result (enum, optional) - Bet settlement state. Null while the bet is still pending. Values: 'WIN', 'LOSS', 'PARTIAL_WIN', 'PARTIAL_LOSS', 'CANCELED', 'PENDING', 'CASH_OUTED', 'RETURN', 'UNKNOWN'
\n
settledAt (long, optional) - Timestamp in milliseconds when the bet was settled
\n
cashOutAt (long, optional) - Timestamp in milliseconds when the bet was cashed out
\n
canceledAt (long, optional) - Timestamp in milliseconds when the bet was canceled
\n

Event Pick (details.bet.eventPicks[]):

pickId (string, required) - Pick id in sportsbook system
\n
sportName (string, required) - Sport name. New values may be added over time. Integrators MUST NOT declare a closed enum with exactly these values on their side; treat the field as an open string and handle unknown values gracefully so the integration does not break when a new value is introduced. Sport name is a free-form string aligned with the codes in the Sports section below.
\n
sportId (string, required) - Sport id (UUID). See the Sports section below for the full id → code mapping.
\n
categoryName (string, required) - Sport category name
\n
categoryId (string, required) - Sport category id
\n
tournamentName (string, required) - Tournament name
\n
tournamentId (string, required) - Tournament id
\n
coefficient (string, required) - Pick coefficient
\n
result (string, required) - Pick settlement result. New values may be added over time. Integrators MUST NOT declare a closed enum with exactly these values on their side; treat the field as an open string and handle unknown values gracefully so the integration does not break when a new value is introduced. Values:
\n
- no_result - pick not settled yet
  \n
- win - pick won; payout = coefficient
  \n
- loss - pick lost; payout = 0
  \n
- half_win - half of stake wins at full odds, the other half returns; payout = (coefficient + 1) / 2
  \n
- half_loss - half of stake lost, the other half returns; payout = 1 / 2
  \n
- _return - stake refunded; payout = 1
  \n
- void - pick voided (e.g. cash-out); payout determined separately
  \n
- partial_win:: - dynamic value emitted when the pick partially won at the given coefficient (the part after :: is the actual coefficient, e.g. partial_win::1.85). Parse the prefix partial_win:: and extract the trailing number.
  \n
\n
banker (boolean, required) - True if the pick is marked as a banker in a system bet
\n
contribution (double, optional) - Pick contribution to the total coefficient
\n
eventStatus (enum, required) - Sport event status. New values may be added over time. Integrators MUST NOT declare a closed enum with exactly these values on their side; treat the field as an open string and handle unknown values gracefully so the integration does not break when a new value is introduced. Values:
\n
- not_started
  \n
- in_progress
  \n
- finished
  \n
- cancelled
  \n
- interrupted
  \n
- postponed
  \n
- retired
  \n
- corrupted
  \n
\n
eventId (string, required) - Sport event id
\n
eventName (string, required) - Sport event name
\n
outcome (object, required) - Outcome descriptor identifying which market the pick was placed on and which outcome was selected (see \"Outcome\" section in this folder).
\n
participants (object, required) - Map keyed by participant slot, value is a Participant object with name (string) and teamId (string, UUID).
\n
finalScore (object, optional) - Final score of the event with team1 (float) and team2 (float).
\n

Outright Pick (details.bet.outrightPicks[]):

pickId (string, required) - Pick id in sportsbook system
\n
sportName (string, required) - Sport name. New values may be added over time. Integrators MUST NOT declare a closed enum with exactly these values on their side; treat the field as an open string and handle unknown values gracefully so the integration does not break when a new value is introduced. Sport name is a free-form string aligned with the codes in the Sports section below.
\n
sportId (string, required) - Sport id (UUID). See the Sports section below for the full id → code mapping.
\n
categoryName (string, required) - Sport category name
\n
categoryId (string, required) - Sport category id
\n
tournamentName (string, required) - Tournament name
\n
tournamentId (string, required) - Tournament id
\n
coefficient (string, required) - Pick coefficient
\n
result (string, required) - Pick settlement result. New values may be added over time. Integrators MUST NOT declare a closed enum with exactly these values on their side; treat the field as an open string and handle unknown values gracefully so the integration does not break when a new value is introduced. Values:
\n
- no_result - pick not settled yet
  \n
- win - pick won; payout = coefficient
  \n
- loss - pick lost; payout = 0
  \n
- half_win - half of stake wins at full odds, the other half returns; payout = (coefficient + 1) / 2
  \n
- half_loss - half of stake lost, the other half returns; payout = 1 / 2
  \n
- _return - stake refunded; payout = 1
  \n
- void - pick voided (e.g. cash-out); payout determined separately
  \n
- partial_win:: - dynamic value emitted when the pick partially won at the given coefficient (the part after :: is the actual coefficient, e.g. partial_win::1.85). Parse the prefix partial_win:: and extract the trailing number.
  \n
\n
banker (boolean, required) - True if the pick is marked as a banker in a system bet
\n
contribution (double, optional) - Pick contribution to the total coefficient
\n
outcomeParameterHash (object, required) - Outcome descriptor for the outright market.
\n
outrightId (string, required) - Outright market id
\n
outrightName (string, required) - Outright market name
\n

Example payload

Bet on Kylian Mbappe (Real Madrid, team p1) to score over 1.5 goals in the full match against Manchester City. Market score_oupt from group oupt.

{\n  \"method\": \"BET_SETTLED\",\n  \"bet\": {\n    \"betId\": \"b1f8a8a4-2eb3-4b16-8d6c-2a4a25c5c5c5\",\n    \"totalCoefficient\": 2.10,\n    \"eventPicks\": [\n      {\n        \"pickId\": \"1c1a8a01-1111-4111-9111-111111111111\",\n        \"sportName\": \"soccer\",\n        \"sportId\": \"d6934640-cf1d-11e9-864b-0242ac13000a\",\n        \"categoryName\": \"International Clubs\",\n        \"categoryId\": \"22222222-2222-2222-2222-222222222222\",\n        \"tournamentName\": \"UEFA Champions League\",\n        \"tournamentId\": \"33333333-3333-3333-3333-333333333333\",\n        \"coefficient\": \"2.10\",\n        \"result\": \"win\",\n        \"banker\": false,\n        \"contribution\": null,\n        \"eventStatus\": \"finished\",\n        \"eventId\": \"44444444-4444-4444-4444-444444444444\",\n        \"eventName\": \"Real Madrid vs Manchester City\",\n        \"outcome\": {\n          \"scopeName\": \"normal_time\",\n          \"scopeNumber\": 0,\n          \"scoreType\": \"score\",\n          \"marketGroup\": \"oupt\",\n          \"marketParameters\": {\n            \"player\": \"kylian_mbappe\",\n            \"team\": \"p1\",\n            \"total\": \"1.5\"\n          },\n          \"outcomeParameters\": {\n            \"@kind\": \"enum\",\n            \"outcome\": \"over\"\n          }\n        },\n        \"participants\": {\n          \"1\": { \"name\": \"Real Madrid\", \"teamId\": \"55555555-5555-5555-5555-555555555555\" },\n          \"2\": { \"name\": \"Manchester City\", \"teamId\": \"66666666-6666-6666-6666-666666666666\" }\n        },\n        \"finalScore\": { \"team1\": 2.0, \"team2\": 1.0 }\n      }\n    ],\n    \"outrightPicks\": [],\n    \"createTime\": 1710849600000,\n    \"anyPickForLiveEvent\": false,\n    \"betStructure\": { \"betType\": \"SINGLE\", \"totalPicks\": 1, \"picksPerSelection\": [1], \"bankersCount\": 0 },\n    \"result\": \"win\",\n    \"settledAt\": 1710856800000,\n    \"cashOutAt\": null,\n    \"canceledAt\": null\n  }\n}\n\n

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"4992d7cf-ea0f-4444-8bf9-9d7bcf5bf58a"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"950efc47-5495-4a42-8dac-41ccce8390c7"}}],"_postman_id":"4a13db02-fd13-4fca-aac0-fe7094548113"},{"name":"Bet Structure","item":[],"id":"4e1b9162-53b8-48b5-8ce1-85d068dba43b","description":"

Bet Structure

Structural summary of a bet, exposed at details.bet.betStructure.

The platform represents bet structure with a compact string (e.g. 1/1, 3/3, 2/3, 2/3:3/3, 2/3|B1). This object exposes the same information as parsed values, so an integration does not need to parse the string itself.

Object

betType (enum, required) - Bet structure. Values: 'SINGLE' (one pick), 'PARLAY' (all picks must win), 'SYSTEM' (any K out of N must win, possibly across several selection groups).
\n
totalPicks (int, required) - Total number of picks N in the bet.
\n
picksPerSelection (array, required) - For each selection group, the number of picks K that must win for that group to pay out. SINGLE/PARLAY have one entry equal to totalPicks; SYSTEM may have several entries with K < N.
\n
bankersCount (int, required) - Number of picks marked as bankers. Bankers must always win for any combination to settle.
\n

Reading `picksPerSelection`

Each entry is the K of a K/N selection group. The number of winning combinations the bet pays out on equals sum over K of C(N, K).

Examples:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Bet structure	`betType`	`totalPicks`	`picksPerSelection`	`bankersCount`
Single (`1/1`)	SINGLE	1	`[1]`	0
Accumulator on 3 picks (`3/3`)	PARLAY	3	`[3]`	0
2-of-3 system (`2/3`)	SYSTEM	3	`[2]`	0
Trixie (`2/3:3/3`)	SYSTEM	3	`[2, 3]`	0
Patent (`1/3:2/3:3/3`)	SYSTEM	3	`[1, 2, 3]`	0
Yankee (`2/4:3/4:4/4`)	SYSTEM	4	`[2, 3, 4]`	0
System with 3 banker picks(3/4\|B3)	SYSTEM	7	`[3]`	3

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"ece11d39-d979-460d-b5e0-cd60832181d1"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"eb5ec529-3b15-42a2-8e65-05a70e0f8602"}}],"_postman_id":"4e1b9162-53b8-48b5-8ce1-85d068dba43b"},{"name":"Outcome","item":[],"id":"82926e1c-fd81-43d2-989d-c165c3b99fdb","description":"

Outcome

Outcome descriptor attached to an Event Pick (details.bet.eventPicks[].outcome). Identifies which market the pick was placed on and which outcome of that market was selected.

Object

scopeName (enum, required) - Scope of the event the market refers to (which segment of the event the score / metric is measured over). New values may be added over time. Integrators MUST NOT declare a closed enum with exactly these values on their side; treat the field as an open string and handle unknown values gracefully so the integration does not break when a new value is introduced. Values:
\n
- half
- full_event
- normal_time
- period
- over_times
- over_time
- penalties
- penalty
- quarter
- set
- game
- frame
- round
- inning
- sudden_death
- kicking_competition
- half_time
- half_time_overtime
- end_break
- set_break
- time_out
- technical_time_out
- medical_time_out
- quarter_break
- overtime_break
- intermission
- pause
- interval
- lunch_break
- tea_break
- break
- rest
- change_ends
- map
- extra_inning
- over
- delivery
- session
- super_over
\n
scopeNumber (int, required) - Ordinal of the scope inside the event. half=1 → first half, period=2 → second period, set=3 → third set. For scopes that occur once per event (e.g. full_event, normal_time) typically 0.
\n
scoreType (enum, required) - Metric the market is built on. New values may be added over time. Integrators MUST NOT declare a closed enum with exactly these values on their side; treat the field as an open string and handle unknown values gracefully so the integration does not break when a new value is introduced. Values:
\n
- score
- yellow_card
- red_card
- corner
- offside
- sub
- time
- shots
- throw_in
- woodwork
- goal_kick
- save
- ast
- tkl
- foul_c
- foul_d
- reb
- free_throw
- pt3
- pt2
- point
- game
- shot_on_goal
- foul
- winner_number
- place_number
- fact
- s4
- s6
- boundary
- wicket
- wicket_or_boundary
- runout
- extra
- maiden
- performance
- ball
- knock_down
- gm
- victory
- penalty
- draw
- loss
- to_nil
\n
marketGroup (enum, required) - Market family the pick belongs to. New values may be added over time. Integrators MUST NOT declare a closed enum with exactly these values on their side; treat the field as an open string and handle unknown values gracefully so the integration does not break when a new value is introduced. The same applies to the marketParameters and outcomeParameters maps listed under each marketGroup below — new keys may appear in the map, and new values may appear for an existing key (including the outcome kind value). Treat both keys and values as open: never declare a closed enum on the integrator side, and skip unknown entries without failing. Values:
\n
- 1x2
  - description: Market with 3 outcomes. 1st outcome: win home_team, 2nd draw, 3rd win away_team
  - marketParameters: none
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=enum, outcome=draw
    - kind=id, outcome=p2
    \n
  \n
- 1x2_ou
  - description: Combined market: match result (1x2) and total over/under.
  - marketParameters: total (example: 2.5)
  - outcomeParameters:
    - kind=id_enum, outcome=p1_over
    - kind=id_enum, outcome=p1_under
    - kind=enum, outcome=draw_over
    - kind=enum, outcome=draw_under
    - kind=id_enum, outcome=p2_over
    - kind=id_enum, outcome=p2_under
    \n
  \n
- 1x2_teams_to_score
  - description: Who wins the match and witch teams to score. Only team that has won scores or both? If draw the same
  - marketParameters: none
  - outcomeParameters:
    - kind=id_enum, outcome=p1_both
    - kind=id_id, outcome=p1_p1
    - kind=enum, outcome=draw_both
    - kind=enum, outcome=draw_none
    - kind=id_enum, outcome=p2_both
    - kind=id_id, outcome=p2_p2
    \n
  \n
- 1x2_early_payout
  - description: Market with 3 outcomes. 1st outcome: win home_team, 2nd draw, 3rd win away_team
  - marketParameters: rp (example: 5), sd (example: 2)
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=enum, outcome=draw
    - kind=id, outcome=p2
    \n
  \n
- win_most_periods
  - description: Which team wins the most periods, or tie.
  - marketParameters: none
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=enum, outcome=draw
    - kind=id, outcome=p2
    \n
  \n
- triple_result
  - description: Result of each of 3 periods combined (all 27 permutations of P1/X/P2).
  - marketParameters: none
  - outcomeParameters:
    - kind=period123, period1=p1, period2=p1, period3=p1
    - kind=period123, period1=p1, period2=p1, period3=draw
    - kind=period123, period1=p1, period2=p1, period3=p2
    - kind=period123, period1=p1, period2=draw, period3=p1
    - kind=period123, period1=p1, period2=draw, period3=draw
    - kind=period123, period1=p1, period2=draw, period3=p2
    - kind=period123, period1=p1, period2=p2, period3=p1
    - kind=period123, period1=p1, period2=p2, period3=draw
    - kind=period123, period1=p1, period2=p2, period3=p2
    - kind=period123, period1=draw, period2=p1, period3=p1
    - kind=period123, period1=draw, period2=p1, period3=draw
    - kind=period123, period1=draw, period2=p1, period3=p2
    - kind=period123, period1=draw, period2=draw, period3=p1
    - kind=period123, period1=draw, period2=draw, period3=draw
    - kind=period123, period1=draw, period2=draw, period3=p2
    - kind=period123, period1=draw, period2=p2, period3=p1
    - kind=period123, period1=draw, period2=p2, period3=draw
    - kind=period123, period1=draw, period2=p2, period3=p2
    - kind=period123, period1=p2, period2=p1, period3=p1
    - kind=period123, period1=p2, period2=p1, period3=draw
    - kind=period123, period1=p2, period2=p1, period3=p2
    - kind=period123, period1=p2, period2=draw, period3=p1
    - kind=period123, period1=p2, period2=draw, period3=draw
    - kind=period123, period1=p2, period2=draw, period3=p2
    - kind=period123, period1=p2, period2=p2, period3=p1
    - kind=period123, period1=p2, period2=p2, period3=draw
    - kind=period123, period1=p2, period2=p2, period3=p2
    \n
  \n
- winning_margin
  - description: Winning margin: exact score difference (1, 2, or more than 2).
  - marketParameters: none
  - outcomeParameters:
    - kind=value, outcome=1, predicate=eq
    - kind=value, outcome=2, predicate=eq
    - kind=value, outcome=2, predicate=gt
    \n
  \n
- winning_margin_yn
  - description: Either Team to Win By {{number}} Goals
  - marketParameters: number (example: 2)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- longest_consecutive
  - description: Longest Consecutive points
  - marketParameters: none
  - outcomeParameters:
    - kind=value, outcome=2, predicate=eq
    - kind=value, outcome=3, predicate=eq
    - kind=value, outcome=4, predicate=eq
    - kind=value, outcome=5, predicate=eq
    \n
  \n
- to_score_race
  - description: Who first scores one goal and seven goals, or another specified amount
  - marketParameters: number (example: 1,7)
  - outcomeParameters:
    - kind=id_sequence, outcome=p1,p1
    - kind=id_sequence, outcome=p1,p2
    - kind=id_sequence, outcome=p2,p1
    - kind=id_sequence, outcome=p2,p2
    \n
  \n
- race
  - description: First To Score {{number}} Goals
  - marketParameters: number (example: 2)
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=enum, outcome=no
    - kind=id, outcome=p2
    \n
  \n
- scopes_with_result
  - description: How many scopes will be finished with outcome specified in market parameter
  - marketParameters: score (example: p1)
  - outcomeParameters:
    - kind=value, outcome=0, predicate=eq
    - kind=value, outcome=1, predicate=eq
    - kind=value, outcome=2, predicate=eq
    - kind=value, outcome=3, predicate=eq
    \n
  \n
- scopes_with_total
  - description: How many scopes will be finished with specified total
  - marketParameters: total (example: 19)
  - outcomeParameters:
    - kind=value, outcome=0, predicate=eq
    - kind=value, outcome=1, predicate=eq
    - kind=value, outcome=2, predicate=eq
    - kind=value, outcome=3, predicate=eq
    \n
  \n
- score_count
  - description: How many arrows will hit the target to the specified score area
  - marketParameters: score (example: 8)
  - outcomeParameters:
    - kind=value, outcome=0, predicate=eq
    - kind=value, outcome=1, predicate=eq
    - kind=value, outcome=2, predicate=eq
    - kind=value, outcome=3, predicate=eq
    - kind=value, outcome=4, predicate=eq
    - kind=value, outcome=5, predicate=eq
    - kind=value, outcome=6, predicate=eq
    \n
  \n
- interval_1x2
  - description: Market with 3 outcomes. 1st outcome: win home_team, 2nd draw, 3rd win away_team. Score selected from time range.
  - marketParameters: from (example: 1), to (example: 10)
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=enum, outcome=draw
    - kind=id, outcome=p2
    \n
  \n
- 12
  - description: Win home or away. This market used in sports where draw outcome doesn't exist
  - marketParameters: none
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=id, outcome=p2
    \n
  \n
- 12_score
  - description: Kiron table tennis is played until score reaches 7. But if score 6:6 player should score 2 goals to win 6:8, or 7:9 etc
  - marketParameters: score (example: 7)
  - outcomeParameters:
    - kind=id_enum, outcome=p2_equal
    - kind=id_enum, outcome=p1_over
    - kind=id_enum, outcome=p2_equal
    - kind=id_enum, outcome=p2_over
    \n
  \n
- dc
  - description: Double chance. 3 outcomes: DRAW or Win home_team / No DRAW / Draw or Win away_team.
  - marketParameters: none
  - outcomeParameters:
    - kind=id_enum, outcome=p1_draw
    - kind=id_enum, outcome=p2_draw
    - kind=enum, outcome=no_draw
    \n
  \n
- interval_dc
  - description: Double chance. 3 outcomes: DRAW or Win home_team / No DRAW / Draw or Win away_team. Score selected from time range.
  - marketParameters: from (example: 1), to (example: 10)
  - outcomeParameters:
    - kind=id_enum, outcome=p1_draw
    - kind=id_enum, outcome=p2_draw
    - kind=enum, outcome=no_draw
    \n
  \n
- ah
  - description:
    \n
    Asian handicap. The 'team' parameter is always p1; for p2 the handicap sign is inverted automatically.\n The 'handicap' parameter determines the settlement type:
    \n
    1. HARD handicap (x.5, e.g. -1.5, +0.5, +2.5):\nOnly win or loss. Handicap is added to the team's score; if adjusted score > opponent → win, otherwise → loss.\nExample: handicap=-1.5, score 1:3 → 1:(3-1.5)=1:1.5 → p2 wins. score 1:2 → 1:(2-1.5)=1:0.5 → p2 loses.
      \n
    2. SOFT handicap (x.0, e.g. -2.0, 0.0, +1.0):\nWin, loss, or return. Same as hard but when adjusted scores are equal → return (stake refunded).\nExample: handicap=-2, score 1:3 → 1:(3-2)=1:1 → return. score 1:4 → 1:2 → p2 wins. score 1:2 → 1:0 → p2 loses.\nSpecial case ZERO handicap (0.0): team wins → win, draw → return, team loses → loss.
      \n
    3. QUARTER handicap (x.25 or x.75, e.g. -0.25, +1.75, +2.25):\nSplit into two equal bets: soft (x.0) and hard (x.5). E.g. handicap=1.25 splits to 1.0(soft) + 1.5(hard).\nCombined result via matrix: soft=return+hard=win → half_win, soft=return+hard=loss → half_loss,\nsoft=win+hard=win → win, soft=loss+hard=loss → loss.\nExample: handicap=+0.25 splits to 0.0 and +0.5. Score 1:1 → soft(0.0)=return, hard(+0.5)=win → half_win.\nScore 0:1 → soft(0.0)=loss, hard(+0.5)=loss → loss.
      \n
    \n
    Possible results: win, loss, half_win, half_loss, return.
    \n
  - marketParameters: team (example: p1), handicap (example: 2.75)
    \n
  - outcomeParameters:
    \n
    - kind=id, outcome=p1
    - kind=id, outcome=p2
    \n
  \n
- interval_ah
  - description:
    \n
    Asian handicap in the time interval (minutes. The 'team' parameter is always p1; for p2 the handicap sign is inverted automatically.\n The 'handicap' parameter determines the settlement type:
    \n
    1. HARD handicap (x.5, e.g. -1.5, +0.5, +2.5):\nOnly win or loss. Handicap is added to the team's score; if adjusted score > opponent → win, otherwise → loss.\nExample: handicap=-1.5, score 1:3 → 1:(3-1.5)=1:1.5 → p2 wins. score 1:2 → 1:(2-1.5)=1:0.5 → p2 loses.
      \n
    2. SOFT handicap (x.0, e.g. -2.0, 0.0, +1.0):\nWin, loss, or return. Same as hard but when adjusted scores are equal → return (stake refunded).\nExample: handicap=-2, score 1:3 → 1:(3-2)=1:1 → return. score 1:4 → 1:2 → p2 wins. score 1:2 → 1:0 → p2 loses.\nSpecial case ZERO handicap (0.0): team wins → win, draw → return, team loses → loss.
      \n
    3. QUARTER handicap (x.25 or x.75, e.g. -0.25, +1.75, +2.25):\nSplit into two equal bets: soft (x.0) and hard (x.5). E.g. handicap=1.25 splits to 1.0(soft) + 1.5(hard).\nCombined result via matrix: soft=return+hard=win → half_win, soft=return+hard=loss → half_loss,\nsoft=win+hard=win → win, soft=loss+hard=loss → loss.\nExample: handicap=+0.25 splits to 0.0 and +0.5. Score 1:1 → soft(0.0)=return, hard(+0.5)=win → half_win.\nScore 0:1 → soft(0.0)=loss, hard(+0.5)=loss → loss.
      \n
    \n
    Possible results: win, loss, half_win, half_loss, return.
    \n
  - marketParameters: from (example: 1), to (example: 10), team (example: p1), handicap (example: 2.75)
    \n
  - outcomeParameters:
    \n
    - kind=id, outcome=p1
    - kind=id, outcome=p2
    \n
  \n
- ou
  - description: Total over/under
  - marketParameters: total (example: 2.5)
  - outcomeParameters:
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- ou_team
  - description: Total over/under for team.
  - marketParameters: total (example: 3.5), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- interval_ou
  - description: Total over/under. Score selected from time range.
  - marketParameters: from (example: 1), to (example: 10), total (example: 2.5)
  - outcomeParameters:
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- interval_ou_team
  - description: Total over/under for team. Score selected from time range.
  - marketParameters: from (example: 1), to (example: 10), total (example: 3.5), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- cs
  - description: Correct score in scope for both teams.
  - marketParameters: none
  - outcomeParameters:
    - kind=key_id, p1=0, p2=0
    - kind=key_id, p1=1, p2=0
    - kind=key_id, p1=2, p2=0
    - kind=key_id, p1=2, p2=1
    - kind=key_id, p1=2, p2=2
    - kind=key_id, p1=0, p2=1
    \n
  \n
- aft_scp
  - description: score after first 2 maps played
  - marketParameters: scope (example: map), number (example: 2)
  - outcomeParameters:
    - kind=key_id, p1=2, p2=0
    - kind=key_id, p1=1, p2=1
    - kind=key_id, p1=0, p2=2
    \n
  \n
- fin_num_yn
  - description: The number in the final score
  - marketParameters: number (example: 1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- both_hlvs_yn
  - description: Goals in Both Halves
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- both_frst_one_scnd_yn
  - description: Both teams to score in 1st half and at least one not to score in 2nd
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- both_either_half_yn
  - description: Both teams to score at least in one half
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- draw_either_half_yn
  - description: Draw in either half
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- each_win_one_half_yn
  - description: Each team to win one half
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- one_half_only_ynt
  - description: Team To score in only one of halves
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- first_n_win_ynt
  - description: Team will score first goal and win
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- first_n_lose_ynt
  - description: Team will score first goal and lose
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- first_n_draw_ynt
  - description: Team will score first goal and draw
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- first_n_no_win_ynt
  - description: Team will score first goal and not win
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- dur_match
  - description: During match score is
  - marketParameters: none
  - outcomeParameters:
    - kind=key_id, p1=1, p2=1
    - kind=key_id, p1=2, p2=0
    - kind=key_id, p1=0, p2=2
    \n
  \n
- x_in_row_yn
  - description: Either Team to Score {{number}} Goals In A Row
  - marketParameters: number (example: 2)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- x_in_row_ynt
  - description: To Score {{number}} Goals In A Row, {{teamName}}
  - marketParameters: team (example: p1), number (example: 2)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- either_to_score_x_more_yn
  - description: Either Team to Score {{number}} or More Goals
  - marketParameters: number (example: 2)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- to_score_yn
  - description: Substitution to score
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- custom
  - description: Custom market
  - marketParameters: id (example: UUID)
  - outcomeParameters:
    - kind=custom, id=UUID
    - kind=custom, id=UUID
    \n
  \n
- odd_even
  - description: Outcome win when total score for both teams of the scope is odd or even.
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=odd
    - kind=enum, outcome=even
    \n
  \n
- odd_even_high_low
  - description: Combination of odd even and over under for tennis
  - marketParameters: total (example: 10.5)
  - outcomeParameters:
    - kind=enum, outcome=odd_low
    - kind=enum, outcome=odd_high
    - kind=enum, outcome=even_low
    - kind=enum, outcome=even_high
    \n
  \n
- odd_even_team
  - description: Outcome win when total score for team of the scope is odd or even.
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=odd
    - kind=enum, outcome=even
    \n
  \n
- u_win_draw_team
  - description: Team total under x and team win or draw.
  - marketParameters: team (example: p1), total (example: 2.5)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- u_win_team
  - description: Team total under x and team win.
  - marketParameters: team (example: p1), total (example: 2.5)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- o_win_team
  - description: Team total over and team win.
  - marketParameters: team (example: p1), total (example: 2.5)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- o_win_draw_team
  - description: Team total over x and team win or draw.
  - marketParameters: team (example: p1), total (example: 2.5)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- u_draw
  - description: Score in scope will be draw AND over x
  - marketParameters: total (example: 2)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- o_draw
  - description: Score in scope will be draw AND over x
  - marketParameters: total (example: 2)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- win_to_nil_team
  - description: Outcome yes win when team win scope and enemy don't score.
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- range_number
  - description: Score of the match: range number
  - marketParameters: none
  - outcomeParameters:
    - kind=range, from=1, to=2
    - kind=value, outcome=3, predicate=gte
    \n
  \n
- range_number_team
  - description: Score of the match: range number.
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=range, from=1, to=2
    - kind=value, outcome=3, predicate=gte
    \n
  \n
- range_number_yes_no
  - description: Range number of goals: yes / no
  - marketParameters: from (example: 5), to (example: 7)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- range_number_yes_no_team
  - description: Range number of goals: yes / no Chelsea
  - marketParameters: from (example: 5), to (example: 7), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- exact_number
  - description: Exact number of goals/sets: 0, 1, 2, 3, 4, 5, 6 and more
  - marketParameters: none
  - outcomeParameters:
    - kind=value, outcome=1, predicate=eq
    - kind=value, outcome=2, predicate=eq
    - kind=value, outcome=3, predicate=gte
    \n
  \n
- exact_number_team
  - description: Exact number of goals: Arsenal
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=value, outcome=1, predicate=eq
    - kind=value, outcome=2, predicate=eq
    - kind=value, outcome=3, predicate=gte
    \n
  \n
- exact_number_yes_no
  - description: Exact number of goals: yes/no
  - marketParameters: score (example: 1), predicate (example: eq)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- exact_number_yes_no_team
  - description: Exact number of goals: yes/no Team
  - marketParameters: score (example: 1), predicate (example: eq), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- ht_ft
  - description: Half-time - full time score of the match: 1 / 1 - team1 won the 1st half & match; X/X - draw in 1st half & full time
  - marketParameters: none
  - outcomeParameters:
    - kind=htft, ht=draw, ft=draw
    - kind=htft, ht=p1, ft=draw
    - kind=htft, ht=p1, ft=p1
    - kind=htft, ht=draw, ft=p1
    - kind=htft, ht=p2, ft=p1
    - kind=htft, ht=p1, ft=p2
    - kind=htft, ht=p2, ft=draw
    - kind=htft, ht=p2, ft=p2
    - kind=htft, ht=draw, ft=p2
    \n
  \n
- both_to_score_yes_no
  - description: Both teams to score
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- both_to_score_and_win_team_yes_no
  - description: Both team to score in scope and team x win
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- team_to_score_in_both_halves_yes_no_team
  - description: Team score in first and second half
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- team_to_win_both_halves_yes_no_team
  - description: Team win both halves.
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- team_to_win_either_half_yes_no_team
  - description: Team win first or second half.
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- team_win_first_half_and_not_to_lose_yes_no_team
  - description: Team to win first half and win match or draw
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- team_to_win_by_exact_number_yes_no_team
  - description: Team to win when score x gte|lte|eq then score of other team and this team win the match.
  - marketParameters: score (example: 1), predicate (example: eq), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- team_to_win_by_exact_number_or_draw_yes_no_team
  - description: Team to win when score x gte|lte|eq then score of other team and this team win the match. Or draw.
  - marketParameters: score (example: 1), predicate (example: eq), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- team_to_score_yes_no_team
  - description: Team to score in a scope
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- draw
  - description: Score draw: yes / no
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- draw_yes_no
  - description: Will the match end in a draw: yes/no.
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- both_to_score_and_o_yes_no
  - description: Both team to score and over
  - marketParameters: total (example: 2)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- both_to_score_and_u_yes_no
  - description: Both team to score and under
  - marketParameters: total (example: 2)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- to_score_first
  - description: Which team open score in scope.
  - marketParameters: none
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=enum, outcome=no
    - kind=id, outcome=p2
    \n
  \n
- to_score_x
  - description: Which team to score x goal.
  - marketParameters: number (example: 1)
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=enum, outcome=no
    - kind=id, outcome=p2
    \n
  \n
- before_goal_yes_no
  - description: Event will be before goal is scored : yes / no
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- before_corner_yes_no
  - description: Incident will be before corner
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- before_sub_yn
  - description: Incident will be before substitution
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- to_score_last
  - description: Which team score last goal.
  - marketParameters: none
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=enum, outcome=no
    - kind=id, outcome=p2
    \n
  \n
- to_score_x_in_range
  - description: When will be scored x goal.
  - marketParameters: number (example: 1)
  - outcomeParameters:
    - kind=range, from=10, to=15
    - kind=range, from=16, to=20
    - kind=range, from=21, to=30
    - kind=enum, outcome=no
    \n
  \n
- to_score_in_range
  - description: When will be scored goal.
  - marketParameters: from (example: 1), to (example: 15)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- to_score_in_range_team
  - description: When will be scored goal by team
  - marketParameters: from (example: 1), to (example: 15), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- extra_inning_yes_no
  - description: Extra inning in baseball: yes/no
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- some_lose_first_set_and_win_match_yes_no
  - description: Some lose first set and win match
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- highest_scopes_score
  - description: The highest scoring scopes. Sets 1>2, 2>1, 1=2
  - marketParameters: scope (example: set)
  - outcomeParameters:
    - kind=multi_value, value1=1, value2=2, predicate=gt
    - kind=multi_value, value1=1, value2=2, predicate=eq
    - kind=multi_value, value1=2, value2=1, predicate=gt
    \n
  \n
- highest_scope_score
  - description: The highest scoring scope. Quarter 1, 2, 3, 4
  - marketParameters: scope (example: quarter)
  - outcomeParameters:
    - kind=value, outcome=1, predicate=eq
    - kind=value, outcome=2, predicate=eq
    - kind=value, outcome=3, predicate=eq
    - kind=value, outcome=4, predicate=eq
    \n
  \n
- some_set_clean_win_in_match_yes_no
  - description: Some set will be won cleanly in the match. Tennis (6:0/0:6)
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- to_win_all_scopes_team_yes_no
  - description: Team win all scopes.
  - marketParameters: scope (example: quarter), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- team_win_first_quarter_and_match_yes_no_team
  - description: Team win first quarter and match.
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- team_win_first_half_and_match_yes_no_team
  - description: Team win first half and match.
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- win_first_half_n_not_win_ynt
  - description: Wins In First Half And Does Not Win A Match, {{teamName}}
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- overtime_yes_no
  - description: Will be overtime
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- runout_yes_no
  - description: Will be run-out in cricket match
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- review_var_yes_no
  - description: Will be video review VAR in soccer match
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- race_winner
  - description: Race winner
  - marketParameters: none
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=id, outcome=p2
    - kind=id, outcome=p3
    - kind=id, outcome=p4
    - kind=id, outcome=p5
    - kind=id, outcome=p6
    \n
  \n
- race_place
  - description: Selected horse finishes in the first two
  - marketParameters: none
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=id, outcome=p2
    - kind=id, outcome=p3
    - kind=id, outcome=p4
    - kind=id, outcome=p5
    - kind=id, outcome=p6
    \n
  \n
- race_show
  - description: Selected horse finishes in the first three
  - marketParameters: none
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=id, outcome=p2
    - kind=id, outcome=p3
    - kind=id, outcome=p4
    - kind=id, outcome=p5
    - kind=id, outcome=p6
    \n
  \n
- race_forecast
  - description: Two selected horses must get to the finish first in specified order
  - marketParameters: none
  - outcomeParameters:
    - kind=id_sequence, outcome=p1,p2
    - kind=id_sequence, outcome=p1,p3
    - kind=id_sequence, outcome=p2,p3
    - kind=id_sequence, outcome=p2,p1
    - kind=id_sequence, outcome=p3,p2
    - kind=id_sequence, outcome=p3,p1
    \n
  \n
- race_reverse_forecast
  - description: Two selected horses must get to the finish first in any order
  - marketParameters: none
  - outcomeParameters:
    - kind=id_sequence, outcome=p1,p3
    - kind=id_sequence, outcome=p2,p3
    - kind=id_sequence, outcome=p2,p1
    \n
  \n
- race_tricast
  - description: Three selected horses must get to the finish first in specified order
  - marketParameters: none
  - outcomeParameters:
    - kind=id_sequence, outcome=p1,p2,p3
    - kind=id_sequence, outcome=p1,p3,p2
    - kind=id_sequence, outcome=p2,p3,p1
    - kind=id_sequence, outcome=p2,p1,p3
    - kind=id_sequence, outcome=p3,p2,p1
    - kind=id_sequence, outcome=p3,p1,p2
    \n
  \n
- race_reverse_tricast
  - description: Three selected horses must get to the finish first in any order
  - marketParameters: none
  - outcomeParameters:
    - kind=id_sequence, outcome=p1,p2,p3
    - kind=id_sequence, outcome=p1,p2,p4
    - kind=id_sequence, outcome=p1,p2,p5
    - kind=id_sequence, outcome=p1,p2,p6
    \n
  \n
- race_quarter
  - description: Four selected horses must get to the finish first in specified order
  - marketParameters: none
  - outcomeParameters:
    - kind=id_sequence, outcome=p1,p2,p3,p4
    - kind=id_sequence, outcome=p2,p1,p3,p4
    - kind=id_sequence, outcome=p2,p1,p4,p3
    - kind=id_sequence, outcome=p3,p1,p4,p2
    - kind=id_sequence, outcome=p3,p1,p2,p4
    \n
  \n
- race_swinger
  - description: Both your horses finish in the first three in any order
  - marketParameters: none
  - outcomeParameters:
    - kind=id_sequence, outcome=p1,p2
    - kind=id_sequence, outcome=p1,p3
    - kind=id_sequence, outcome=p2,p3
    \n
  \n
- race_high_low
  - description: Race winner lane over/under (1,2,3|4,5,6). If participant number is odd then middle lane relates to over (1,2,3|4,5,6,7).
  - marketParameters: total (example: 3.5)
  - outcomeParameters:
    - kind=enum, outcome=low
    - kind=enum, outcome=high
    \n
  \n
- race_odd_even
  - description: Race winner lane odd/even
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=odd
    - kind=enum, outcome=even
    \n
  \n
- race_odd_even_high_low
  - description: Combination of odd even and over under for racing
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=odd_low
    - kind=enum, outcome=odd_high
    - kind=enum, outcome=even_low
    - kind=enum, outcome=even_high
    \n
  \n
- race_pairs
  - description: Not supported yet
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- roulette_odd_even
  - description: Like a regular odd_even but if zero then loss
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=odd
    - kind=enum, outcome=even
    \n
  \n
- roulette_numbers
  - description: Roulette numbers
  - marketParameters: none
  - outcomeParameters:
    - kind=value_sequence, outcome=32
    - kind=value_sequence, outcome=25,17,34,6,27,13
    \n
  \n
- roulette_red_black
  - description: Red or black
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=red
    - kind=enum, outcome=black
    \n
  \n
- racing_roulette_first
  - description: Race winner
  - marketParameters: none
  - outcomeParameters:
    - kind=id_sequence, outcome=p13
    - kind=id_sequence, outcome=p12
    - kind=id_sequence, outcome=p1,p2,p3
    - kind=id_sequence, outcome=p4,p5,p6
    - kind=id_sequence, outcome=p7,p8,p9
    - kind=id_sequence, outcome=p10,p11,p12
    - kind=id_sequence, outcome=p1,p3,p5,p7,p9,p11
    - kind=id_sequence, outcome=p2,p4,p6,p8,p10,p12
    \n
  \n
- racing_roulette_first_second
  - description: First and second in order
  - marketParameters: none
  - outcomeParameters:
    - kind=id_sequence_double, first=p1, second=p2
    - kind=id_sequence_double, first=p1,p2,p3, second=p4,p5,p6
    - kind=id_sequence_double, first=p1,p3,p5,p7,p9,p11, second=p2,p4,p6,p8,p10,p12
    \n
  \n
- racing_roulette_first_second_third
  - description: First, second and third in order
  - marketParameters: none
  - outcomeParameters:
    - kind=id_sequence_triple, first=p1, second=p2, third=p3
    - kind=id_sequence_triple, first=p1,p2,p3, second=p4,p5,p6, third=p7,p8,p9
    - kind=id_sequence_triple, first=p1,p3,p5,p7,p9,p11, second=p2,p4,p6,p8,p10,p12, third=p2,p4,p6,p8,p10,p12
    \n
  \n
- racing_roulette_in_first_three
  - description: Finish if first three
  - marketParameters: none
  - outcomeParameters:
    - kind=id_sequence, outcome=p1
    - kind=id_sequence, outcome=p2,p4
    - kind=id_sequence, outcome=p1,p2,p4
    \n
  \n
- racing_roulette_two_from_three
  - description: First three in order
  - marketParameters: none
  - outcomeParameters:
    - kind=id_sequence, outcome=p1,p2,p3
    - kind=id_sequence, outcome=p3,p2,p1
    \n
  \n
- keno_subset_in_set
  - description: Keno
  - marketParameters: none
  - outcomeParameters:
    - kind=value_sequence, outcome=32,15,19,4,21,2
    \n
  \n
- keno_heads_tails
  - description: Keno heads tails
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=heads
    - kind=enum, outcome=evens
    - kind=enum, outcome=tails
    \n
  \n
- lucky_loot_first_balls
  - description: Player chooses first n balls from m drawn
  - marketParameters: none
  - outcomeParameters:
    - kind=value_sequence, outcome=8
    - kind=value_sequence, outcome=1,2
    - kind=value_sequence, outcome=1,2,3
    - kind=value_sequence, outcome=1,2,3,4
    - kind=value_sequence, outcome=1,2,3,4,5
    - kind=value_sequence, outcome=1,2,3,4,5,6
    \n
  \n
- lucky_loot_first_color
  - description: First color
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=green
    \n
  \n
- lucky_loot_colors_count
  - description: Drawn colors count
  - marketParameters: color (example: red)
  - outcomeParameters:
    - kind=value, outcome=0, predicate=eq
    - kind=value, outcome=2, predicate=gte
    \n
  \n
- lucky_loot_subset_in_set_strict
  - description: n Or More From 6
  - marketParameters: number (example: 5)
  - outcomeParameters:
    - kind=value_sequence, outcome=32,15,19,4,21,2
    \n
  \n
- lucky_loot_sum_odd_even
  - description: Sum of draw odd or even
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=odd
    - kind=enum, outcome=even
    \n
  \n
- lucky_loot_sum_high_low
  - description: Sum of draw higher than 75.5 or lower
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=low
    \n
  \n
- to_win_toss
  - description: Market with 2 outcomes. 1st outcome: win home_team, 2nd win away_team
  - marketParameters: none
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=id, outcome=p2
    \n
  \n
- to_win_toss_and_match_yes_no_team
  - description: Team wins the coin toss and wins the match: yes/no.
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- to_win_toss_and_score_first_ball_yes_no_team
  - description: Team wins the toss and scores off the first ball: yes/no.
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- first_wicket_method
  - description: How the first wicket falls: caught, bowled, lbw, run-out, stumped, or other.
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=caught
    - kind=enum, outcome=bowled
    - kind=enum, outcome=lbw
    - kind=enum, outcome=runout
    - kind=enum, outcome=stumped
    - kind=enum, outcome=other
    \n
  \n
- first_wicket_method_2_way
  - description: First wicket method simplified: caught or other.
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=caught
    - kind=enum, outcome=other
    \n
  \n
- x_wicket_method_team
  - description: How the Nth wicket falls for a team: caught, bowled, lbw, run-out, stumped, or other.
  - marketParameters: team (example: p1), number (example: 3)
  - outcomeParameters:
    - kind=enum, outcome=caught
    - kind=enum, outcome=bowled
    - kind=enum, outcome=lbw
    - kind=enum, outcome=runout
    - kind=enum, outcome=stumped
    - kind=enum, outcome=other
    \n
  \n
- x_wicket_method_2_way_team
  - description: Nth wicket method for the team simplified: caught or other.
  - marketParameters: team (example: p1), number (example: 3)
  - outcomeParameters:
    - kind=enum, outcome=caught
    - kind=enum, outcome=other
    \n
  \n
- score_at_fall_of_x_wicket_ou
  - description: Total runs scored at the fall of the Nth wicket: over/under.
  - marketParameters: number (example: 2), total (example: 160)
  - outcomeParameters:
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- score_at_fall_of_x_wicket_ou_team
  - description: Team's runs at the fall of their Nth wicket: over/under.
  - marketParameters: team (example: p1), number (example: 2), total (example: 160)
  - outcomeParameters:
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- score_at_fall_of_x_wicket_odd_even_team
  - description: Team's runs at the fall of the Nth wicket: odd or even.
  - marketParameters: team (example: p1), number (example: 2)
  - outcomeParameters:
    - kind=enum, outcome=odd
    - kind=enum, outcome=even
    \n
  \n
- x_wicket_golden_duck_yes_no_team
  - description: Nth wicket for the team is a golden duck (out on first ball): yes/no.
  - marketParameters: team (example: p1), number (example: 3)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- odd_even_player
  - description:
    \n
    Player's individual score is odd or even.\n If the player is not present in the starting lineups, the pick must be settled as return. Players substituted in are not count and must be settled as return.
    \n
  - marketParameters: player (example: peter_dendocker)
    \n
  - outcomeParameters:
    \n
    - kind=enum, outcome=odd
    - kind=enum, outcome=even
    \n
  \n
- player_out_method
  - description: How a specific player gets out: caught or other.
  - marketParameters: player (example: peter_dendocker)
  - outcomeParameters:
    - kind=enum, outcome=caught
    - kind=enum, outcome=other
    \n
  \n
- player_bingo_yes
  - description: player_bingo_yes
  - marketParameters: player (example: peter_dendocker)
  - outcomeParameters:
    - kind=enum, outcome=yes
    \n
  \n
- player_bullseye_yes
  - description: player_bullseye_yes
  - marketParameters: player (example: peter_dendocker)
  - outcomeParameters:
    - kind=enum, outcome=yes
    \n
  \n
- ou_player
  - description:
    \n
    Player's individual score over/under a specified score type. \n If the player is not present in the starting lineups, the pick must be settled as return. Players substituted in are not count and must be settled as return.
    \n
  - marketParameters: player (example: peter_dendocker)
    \n
  - outcomeParameters:
    \n
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- oupt
  - description:
    \n
    Player's individual score over/under a specified score type. \n If the player is not present in the starting lineups, the pick must be settled as return. Players substituted in are not count and must be settled as return.
    \n
  - marketParameters: player (example: peter_dendocker), team (example: p1), total (example: 0.5)
    \n
  - outcomeParameters:
    \n
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- first_ynpt
  - description:
    \n
    Player on a specific team scores first: yes/no.\n If the player is not present in the starting lineups, the pick must be settled as return. Players substituted in are not count and must be settled as return.
    \n
  - marketParameters: player (example: peter_dendocker), team (example: p1)
    \n
  - outcomeParameters:
    \n
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- last_ynpt
  - description:
    \n
    Player on a specific team scores last: yes/no.\n If the player is not present in the starting lineups, the pick must be settled as return. Players substituted in are not count and must be settled as return.
    \n
  - marketParameters: player (example: peter_dendocker), team (example: p1)
    \n
  - outcomeParameters:
    \n
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- assist_oupt
  - description:
    \n
    Player's individual score by assists over/under. \n If the player is not present in the starting lineups, the pick must be settled as return. Players substituted in are not count and must be settled as return.
    \n
  - marketParameters: player (example: peter_dendocker), team (example: p1), total (example: 0.5)
    \n
  - outcomeParameters:
    \n
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- or_ast_ynpt
  - description:
    \n
    Player on a specific team to score or assist: yes/no.\n If the player is not present in the starting lineups, the pick must be settled as return. Players substituted in are not count and must be settled as return.
    \n
  - marketParameters: player (example: peter_dendocker), team (example: p1)
    \n
  - outcomeParameters:
    \n
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- pre_live_ou_player
  - description: pre_live_ou_player
  - marketParameters: player (example: peter_dendocker)
  - outcomeParameters:
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- x_scored_player_yes_no
  - description: Player reaches X runs/points: yes/no.
  - marketParameters: score (example: 100), player (example: peterparker)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- fifty_scored_player_and_team_win_yes
  - description: Player scores 50+ and their team wins: yes.
  - marketParameters: player (example: peter_dendocker), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    \n
  \n
- x_player_out_yes_no_team
  - description: Specific player from the team is out by the Nth wicket: yes/no.
  - marketParameters: number (example: 2), player (example: peter_dendocker), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- top_player_team
  - description: Which player from a specific team scores the most.
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=_name, name=peter_dendocker
    - kind=_name, name=bob_benksy
    \n
  \n
- top_player
  - description: Which player scores the most in the match.
  - marketParameters: none
  - outcomeParameters:
    - kind=_name, name=peter_dendocker
    - kind=_name, name=bob_benksy
    \n
  \n
- matchbets
  - description: Head-to-head: which of two named players scores more.
  - marketParameters: player (example: peter_dendocker__bob_benksy)
  - outcomeParameters:
    - kind=_name, name=peter_dendocker
    - kind=_name, name=bob_benksy
    \n
  \n
- x_individual_score_yes_no
  - description: Any individual player reaches X runs/points: yes/no.
  - marketParameters: score (example: 100)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- x_individual_score_yes_no_team
  - description: Any player from the team reaches X runs/points: yes/no.
  - marketParameters: score (example: 100), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- highest_individual_score_ou
  - description: Total highest_individual_score_ou.
  - marketParameters: total (example: 3.5)
  - outcomeParameters:
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- highest_opening_partnership
  - description: Market with 3 outcomes. 1st outcome: win home_team, 2nd draw, 3rd win away_team
  - marketParameters: none
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=enum, outcome=draw
    - kind=id, outcome=p2
    \n
  \n
- opening_partnership_ou_team
  - description: Total opening_partnership_ou_team.
  - marketParameters: total (example: 3.5), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- x_scored_partnership_yes
  - description: Named batting partnership reaches X runs: yes.
  - marketParameters: player (example: peter_dendocker__bob_benksy), number (example: 25)
  - outcomeParameters:
    - kind=enum, outcome=yes
    \n
  \n
- incident_yes_no_team
  - description: Specified incident occurs for the team: yes/no.
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- x_scored_yes_no_team
  - description: Team reaches X runs/points in the scope: yes/no.
  - marketParameters: score (example: 100), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- first_scoring_team
  - description: How the first scoring play occurs for a team (e.g. 3-pointer, other).
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=value, outcome=3, predicate=eq
    - kind=enum, outcome=other
    \n
  \n
- x_boundary_team
  - description: Type of the Nth boundary for the team: four (s4) or six (s6).
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=s4
    - kind=enum, outcome=s6
    \n
  \n
- captain_fantastic_team_yes
  - description: captain_fantastic_team_yes
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    \n
  \n
- clean_sweep_team_yes
  - description: clean_sweep_team_yes
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    \n
  \n
- highest_runscorer
  - description: Which team has the highest individual run scorer, or tie.
  - marketParameters: none
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=enum, outcome=draw
    - kind=id, outcome=p2
    \n
  \n
- highest_wicket_taker
  - description: Which team has the highest individual wicket taker, or tie.
  - marketParameters: none
  - outcomeParameters:
    - kind=id, outcome=p1
    - kind=enum, outcome=draw
    - kind=id, outcome=p2
    \n
  \n
- both_to_score_o_yes_no
  - description: Both teams score at least X runs/points (over): yes/no.
  - marketParameters: total (example: 160)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- both_to_score_u_yes_no
  - description: Both teams score under X runs/points: yes/no.
  - marketParameters: total (example: 160)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- winning_over
  - description: In which over range the winning run is scored (cricket).
  - marketParameters: none
  - outcomeParameters:
    - kind=range, from=10, to=20
    - kind=value, outcome=20, predicate=eq
    - kind=value, outcome=19, predicate=eq
    - kind=value, outcome=19, predicate=lte
    \n
  \n
- first_boundary
  - description: First boundary type: four (s4) or six (s6).
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=s4
    - kind=enum, outcome=s6
    \n
  \n
- last_action
  - description: Type of the last delivery/action: single, four, six, wicket, or other (cricket).
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=single
    - kind=enum, outcome=s4
    - kind=enum, outcome=s6
    - kind=enum, outcome=wicket
    - kind=enum, outcome=other
    \n
  \n
- scope_result
  - description: Scope result: specific score value or other.
  - marketParameters: none
  - outcomeParameters:
    - kind=value, outcome=3, predicate=eq
    - kind=enum, outcome=other
    \n
  \n
- super_over_yes_no
  - description: Will there be a super over (cricket tiebreaker): yes/no.
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- highest_over_ou
  - description: Highest-scoring over total over/under a specified line (cricket).
  - marketParameters: total (example: 16.5)
  - outcomeParameters:
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- ahead_of_time_yes_no
  - description: Ahead of time win
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- ahead_of_time_yes_no_team
  - description: Team to win ahead of time
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- by_point_yes_no_team
  - description: Win by points
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- win_round
  - description: In which round the fight is won.
  - marketParameters: none
  - outcomeParameters:
    - kind=value, outcome=1, predicate=eq
    - kind=value, outcome=2, predicate=eq
    \n
  \n
- incident_yes_no
  - description: Some incident(wicket in cricket) to have place during the scope
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- lost_for_ou_team
  - description: Cricket market. Wicket lost for x runs for team
  - marketParameters: score (example: 200), total (example: 3.5), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- x_player_out_team
  - description: Which player from the team is out at the Nth wicket.
  - marketParameters: number (example: 2), team (example: p1)
  - outcomeParameters:
    - kind=_name, name=peter_dendocker
    - kind=_name, name=bob_benksy
    \n
  \n
- first_scoring
  - description: Type of the first scoring play (e.g. exact value or other).
  - marketParameters: none
  - outcomeParameters:
    - kind=value, outcome=3, predicate=eq
    - kind=enum, outcome=other
    \n
  \n
- win_margin_ou_team
  - description: Team's winning margin over/under a specified line.
  - marketParameters: total (example: 2.5), team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=over
    - kind=enum, outcome=under
    \n
  \n
- kd_incident_yes_no
  - description: Will there be a knock-down in the match: yes/no.
  - marketParameters: none
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
- kd_incident_yes_no_team
  - description: Team will knock the opponent down: yes/no.
  - marketParameters: team (example: p1)
  - outcomeParameters:
    - kind=enum, outcome=yes
    - kind=enum, outcome=no
    \n
  \n
\n

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"4fc4f1bf-536d-4a60-b8e2-91457dd07286"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"1c04e22b-9729-4544-a980-0e95d7eb3036"}}],"_postman_id":"82926e1c-fd81-43d2-989d-c165c3b99fdb"},{"name":"Sportsbook Tree","item":[{"name":"Sports","item":[],"id":"0756419a-d3e5-4a52-ac40-06fe8e74b0b3","description":"

Sports

Known sportId → code mapping. New sports may be added over time. Integrators MUST NOT declare a closed enum / fixed set of UUIDs on their side; treat the field as an open string and handle unknown ids gracefully so the integration does not break when a new sport is introduced.

Same table applies to both Event Pick and Outright Pick sportId fields.

sportId	code
`decc47a0-43f8-4f15-b6a3-6beb9368c649`	decimal-cricket
`1da0f5f1-daf2-4c69-baf5-4ae2f266e5f4`	kiron-badminton
`cf0cb942-1ee0-4526-9b48-d4eb54a7720a`	kiron-archery
`d69396a4-cf1d-11e9-90ca-0242ac13000a`	canoe
`d691f9fc-cf1d-11e9-b13b-0242ac13000a`	athletics
`d6931db4-cf1d-11e9-af54-0242ac13000a`	rugby
`d6944ef0-cf1d-11e9-b474-0242ac13000a`	sepak-takraw
`d6929204-cf1d-11e9-aed5-0242ac13000a`	cricket
`6c7d15b9-1c79-4ba4-8a40-9b5e55c5a8da`	e-tennis
`d81efba4-608f-4b4e-be63-d93732f5cb96`	e-ice-hockey
`d692a4ec-cf1d-11e9-91b2-0242ac13000a`	cycling
`d693aac2-cf1d-11e9-89ff-0242ac13000a`	equestrian
`f07966d8-1922-467d-96fb-727929358052`	curling
`d69430be-cf1d-11e9-85f7-0242ac13000a`	rallying
`d69267de-cf1d-11e9-b8ad-0242ac13000a`	beach-volleyball
`fb6d3b06-0c0d-4a9e-b612-2c41bf08807f`	e-basketball
`d15083fa-81ac-4395-be69-54ff56a3ef59`	overwatch
`d69477e0-cf1d-11e9-8a21-0242ac13000a`	surfing
`4e8d5ce3-97e2-4035-a4ed-3b81eab2c31b`	e-volleyball
`4dc3ac2f-c8ab-4aef-a369-6700a72ea63d`	lol
`d69426b4-cf1d-11e9-85be-0242ac13000a`	racketlon
`5da5ed87-b43e-4918-be12-e567a02028ca`	kiron-keno
`c0bd7cd7-2f15-4e10-bbec-fd699be5d296`	kiron-harness-racing
`8e0f34e5-7b4f-4319-9288-2a568259c668`	kiron-cricket
`27d667e3-8260-4afb-9ee3-d520c825940d`	kiron-racing-roulette
`d6922ab2-cf1d-11e9-9ad4-0242ac13000a`	badminton
`d693df60-cf1d-11e9-9269-0242ac13000a`	hurling
`d69481ea-cf1d-11e9-80a0-0242ac13000a`	triathlon
`d6936e72-cf1d-11e9-bfab-0242ac13000a`	volleyball
`d693b5bc-cf1d-11e9-9d1e-0242ac13000a`	fencing
`d691ecc8-cf1d-11e9-a78c-0242ac13000a`	american-football
`ac3afc6b-4cc5-44f7-9742-5722942bd651`	rainbow6
`5b926879-bb7d-4c28-b0bd-742107ec02ba`	hearthstone
`d6938c90-cf1d-11e9-b350-0242ac13000a`	bowls
`27cbd9ad-fd35-420d-9ccd-ea2c04eb50cf`	warcraft3
`d6946dd6-cf1d-11e9-a550-0242ac13000a`	speedway
`d693fe32-cf1d-11e9-9774-0242ac13000a`	kayak
`d693cab6-cf1d-11e9-8f30-0242ac13000a`	gaelic-football
`d6945936-cf1d-11e9-9307-0242ac13000a`	shooting
`4be04662-eba6-4a45-8ff9-4866869215da`	rocket-league
`43f82846-eed2-485b-87b6-bfc8de5b9854`	kiron-motor-racing
`14282c50-32ea-4ae5-aecf-15b907ce751e`	kiron-steeple-chase
`520ab8f7-87b4-41bd-b004-3667e46d1789`	kiron-ice-hockey
`d3c5e46d-072c-404c-af61-30e5418023af`	kiron-lucky-loot
`bbe839ec-3e55-4746-9de4-56bf367dd3c9`	starcraft2
`444481ae-9bea-4a5f-9b6c-4a4feb424444`	politics
`d692af28-cf1d-11e9-9790-0242ac13000a`	darts
`2009e404-f67f-11e9-a05a-f01898ec59ee`	esports
`d69444dc-cf1d-11e9-9192-0242ac13000a`	sailing
`d692e16e-cf1d-11e9-bfdf-0242ac13000a`	golf
`d69463a4-cf1d-11e9-b57b-0242ac13000a`	softball
`87f9bcca-56b8-4d5f-a73a-7fd3988a7647`	unknown
`d6934640-cf1d-11e9-864b-0242ac13000a`	soccer
`d6941296-cf1d-11e9-9be5-0242ac13000a`	pelota
`d6933c2c-cf1d-11e9-9e86-0242ac13000a`	snooker
`d69309a0-cf1d-11e9-bfa6-0242ac13000a`	motorcycling
`d693a0b8-cf1d-11e9-8886-0242ac13000a`	diving
`9f4b280e-d19d-43df-bfaa-ff500b221294`	e-soccer
`d693d4e8-cf1d-11e9-b511-0242ac13000a`	greyhounds-racing
`d6925dc0-cf1d-11e9-b60e-0242ac13000a`	beach-soccer
`e1e78fb9-0e4e-4f70-9f56-f2495516e513`	kiron-table-tennis
`befda60a-c8d7-4dc4-94e9-23ad059d164c`	kiron-hounds-racing
`4a8f699c-296e-4ff0-8aeb-a3f67c1bb91f`	kiron-roulette
`d69239b2-cf1d-11e9-90e6-0242ac13000a`	bandy
`d6928606-cf1d-11e9-878b-0242ac13000a`	chess
`d693787c-cf1d-11e9-9c02-0242ac13000a`	water-polo
`d6921df6-cf1d-11e9-8d12-0242ac13000a`	auto-racing
`d6929b82-cf1d-11e9-a89e-0242ac13000a`	cross-country-skiing
`d69250c8-cf1d-11e9-b1d7-0242ac13000a`	basketball
`d6948c08-cf1d-11e9-880f-0242ac13000a`	trotting
`d692eb78-cf1d-11e9-b183-0242ac13000a`	handball
`d6949612-cf1d-11e9-a369-0242ac13000a`	yachting
`d6943ad2-cf1d-11e9-b058-0242ac13000a`	rowing
`d6935a54-cf1d-11e9-978e-0242ac13000a`	table-tennis
`d693ea0a-cf1d-11e9-af98-0242ac13000a`	indycar-racing
`d692f582-cf1d-11e9-a815-0242ac13000a`	ice-hockey
`60b9e9c2-8952-4663-8cc1-121c6828b61e`	kiron-soccer
`8db46e9b-b252-423b-a07f-b8379c9799eb`	csgo
`52f52608-f67f-11e9-9a01-f01898ec59ee`	horse-racing
`d69313aa-cf1d-11e9-adb0-0242ac13000a`	netball
`200a0d94-f67f-11e9-a10f-f01898ec59ee`	winter-sports
`d693504a-cf1d-11e9-b002-0242ac13000a`	squash
`d6924664-cf1d-11e9-848a-0242ac13000a`	baseball
`82c462f6-5e53-4b43-ae41-c53865311439`	starcraft
`d69204f6-cf1d-11e9-9123-0242ac13000a`	aussie-rules
`d69271f2-cf1d-11e9-84d6-0242ac13000a`	biathlon
`d692ff96-cf1d-11e9-a3f3-0242ac13000a`	mma
`d693645e-cf1d-11e9-82b4-0242ac13000a`	tennis
`29d699ca-38ef-4ec6-8ddd-08a890ec13ba`	kiron-horse-racing
`2b39989c-5f4e-476d-8365-4fe5ec4e256c`	valorant
`d6941ca0-cf1d-11e9-a9a1-0242ac13000a`	pesapallo
`d6938286-cf1d-11e9-9e37-0242ac13000a`	wrestling
`52f52572-f67f-11e9-9a01-f01898ec59ee`	motorsport
`d692cd5a-cf1d-11e9-b9d7-0242ac13000a`	formula-1
`d6940882-cf1d-11e9-9415-0242ac13000a`	lotto
`4a2c3ff7-cf0c-4438-bc3a-01ab75b6d4ec`	dota2
`d691b7ee-cf1d-11e9-a00f-0242ac13000a`	alpine-skiing
`d692c346-cf1d-11e9-b5fb-0242ac13000a`	floorball
`d6933222-cf1d-11e9-890c-0242ac13000a`	ski-jumping
`d692b93c-cf1d-11e9-a996-0242ac13000a`	field-hockey
`d693c048-cf1d-11e9-8032-0242ac13000a`	fishing
`d6927b52-cf1d-11e9-a4a2-0242ac13000a`	boxing
`d692d764-cf1d-11e9-90f1-0242ac13000a`	futsal
`d693f428-cf1d-11e9-a2d1-0242ac13000a`	kabaddi

","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"7d9a542c-0a5e-425c-8248-5b69540f9f28"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"05c56e29-0653-492a-9ad3-d51c6697e350"}}],"_postman_id":"0756419a-d3e5-4a52-ac40-06fe8e74b0b3"},{"name":"Pagination","item":[],"id":"07a5c9c7-4731-43c7-beb1-bb203a92f7f8","description":"

Pagination

All sportsbook list endpoints (Find Categories, Find Tournaments, Find Events) share the same cursor-based pagination scheme. The request body accepts three optional objects: cursor, where, order. All three are independent and can be combined.

`cursor` (object, optional)

Relay-style cursor pagination. Pick one direction per call: forward (first + optional after) or backward (last + optional before). If cursor is omitted entirely a server-side default page size is used.

first (int, optional) - Page size when paging forward. Take the first N items after after.
\n
after (string, optional) - Opaque cursor returned by a previous response (pageInfo.endCursor). Page starts strictly after this position. Omit for the first page.
\n
last (int, optional) - Page size when paging backward. Take the last N items before before.
\n
before (string, optional) - Opaque cursor returned by a previous response (pageInfo.startCursor). Page ends strictly before this position.
\n

Rules:

Use first/after together for forward paging, last/before together for backward paging. Do not mix forward and backward fields in a single request.
Cursors are opaque base64 tokens. They are not parseable identifiers - do not construct them on the client side; always echo back what the server returned.
Cursors are stable across the same where + order combination. If you change filtering or sorting between calls, start the iteration from scratch (omit after/before).

`where` (object, optional)

Generic predicate tree used to filter the result set. A where node is either a leaf (a single condition on one field) or a branch (a logical combination of nested nodes).

Object:

predicate (enum, required) - The operator applied at this node. See predicate list below.
\n
fieldPath (string, leaf only) - Name of the field this leaf filters on. Allowed values are listed per endpoint under whereFieldPaths in the request description.
\n
value (string, leaf only) - Right-hand side value of the predicate, serialised as a string. For in / not_in pass a comma-separated list (e.g. \"uuid1,uuid2\"). For timestamps pass epoch milliseconds as a string (e.g. \"1779753600000\" for 2026-05-26T00:00:00Z) or a relative date token (see Timestamp values below). ISO-8601 strings are NOT accepted.
\n
operands (array, branch only) - Nested where nodes combined by the branch predicate (and / or). Branch nodes must not set fieldPath or value.
\n

Predicates:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

predicate	shape	meaning
`and`	branch	All operands must match
`or`	branch	At least one operand must match
`eq`	leaf	`fieldPath` equals `value`
`not_eq`	leaf	`fieldPath` differs from `value`
`in`	leaf	`fieldPath` is in the comma-separated list `value`
`not_in`	leaf	`fieldPath` is not in the comma-separated list `value`
`gt` / `gte` / `lt` / `lte`	leaf	Numeric/temporal comparisons
`like` / `starts_with` / `ends_with`	leaf	String matching (SQL `LIKE`-style)
`unaccent_like` / `unaccent_eq` / `unaccent_starts_with` / `unaccent_ends_with`	leaf	Accent-insensitive variants
`is_null` / `is_not_null`	leaf	Nullability check (omit `value`)
`is_true` / `is_false`	leaf	Boolean check (omit `value`)
`is_empty` / `is_not_empty`	leaf	Collection / string emptiness
`contains` / `contained_by` / `contains_key`	leaf	JSON/array containment

Timestamp values:

Timestamp where values are parsed by parseDate:

Epoch milliseconds (string): \"1779753600000\". Recommended for absolute time bounds.
Relative period: ISO-8601 period prefixed with P (future) or -P (past), relative to now. Examples: \"P1D\" = +1 day, \"-P1H\" = -1 hour, \"P7D\" = +7 days.
Calendar modifier: MD = start of current day (UTC), MW = start of current week (Sunday), MM = start of current month, MY = start of current year. Example: \"MD\".
Combined: <period>_<modifier> — apply period offset to the modifier anchor. Example: \"P1D_MD\" = start of tomorrow.
Time zone (optional suffix): append _TZ<zoneId>. Example: \"MD_TZEurope/Berlin\" = start of today in Berlin time.

ISO-8601 instant strings like \"2026-05-26T00:00:00Z\" are not accepted and will fail with Duration '<value>' not parsed.

Example - simple leaf:

{\n  \"predicate\": \"eq\",\n  \"fieldPath\": \"category__sportId\",\n  \"value\": \"d6934640-cf1d-11e9-864b-0242ac13000a\"\n}\n

Example - composite (events starting in a time window and not finished):

{\n  \"predicate\": \"and\",\n  \"operands\": [\n    { \"predicate\": \"gte\", \"fieldPath\": \"event__startTime\", \"value\": \"1779753600000\" },\n    { \"predicate\": \"lt\",  \"fieldPath\": \"event__startTime\", \"value\": \"1779840000000\" },\n    { \"predicate\": \"is_null\", \"fieldPath\": \"event__finishedAt\" }\n  ]\n}\n

`order` (array, optional)

Ordered list of sort keys applied left-to-right. Each entry:

fieldPath (string, required) - One of the allowed orderByFieldPaths listed per endpoint.
\n
direction (enum, optional) - ASC (default) or DESC.
\n

If order is omitted the endpoint applies its default sort (see each endpoint description).

Example:

[\n  { \"fieldPath\": \"event__startTime\", \"direction\": \"ASC\" },\n  { \"fieldPath\": \"event__id\",        \"direction\": \"ASC\" }\n]\n

`page` (response object)

Every sportsbook list endpoint returns a Page<T> envelope under a domain-specific key (categories, tournaments, events).

Object:

edges (array, required) - Items of the current page.
\n
- cursor (string, required) - Opaque cursor pointing at this specific edge. Pass it back as after / before to anchor subsequent calls at this position.
- node (object, required) - The actual entity. Shape depends on the endpoint (Category, Tournament, Event).
\n
pageInfo (object, required) - Navigation metadata for the current slice.
\n
- hasPreviousPage (boolean, required) - True if a page exists before this slice.
- hasNextPage (boolean, required) - True if a page exists after this slice.
- startCursor (string, optional) - Cursor of the first edge; null when edges is empty.
- endCursor (string, optional) - Cursor of the last edge; null when edges is empty.
- total (long, required) - Total number of items matching where across all pages. 0 if totals are not requested / not available.
\n

Example response envelope:

{\n  \"categories\": {\n    \"edges\": [\n      {\n        \"cursor\": \"eyJpZCI6IjExMTExMTExLTExMTEtMTExMS0xMTExLTExMTExMTExMTExMSJ9\",\n        \"node\": {\n          \"categoryId\": \"11111111-1111-1111-1111-111111111111\",\n          \"categoryName\": \"International Clubs\",\n          \"sportId\": \"d6934640-cf1d-11e9-864b-0242ac13000a\"\n        }\n      }\n    ],\n    \"pageInfo\": {\n      \"hasPreviousPage\": false,\n      \"hasNextPage\": true,\n      \"startCursor\": \"eyJpZCI6IjExMTExMTExLTExMTEtMTExMS0xMTExLTExMTExMTExMTExMSJ9\",\n      \"endCursor\": \"eyJpZCI6IjExMTExMTExLTExMTEtMTExMS0xMTExLTExMTExMTExMTExMSJ9\",\n      \"total\": 42\n    }\n  }\n}\n

Iterating forward

Issue the first call with cursor omitted (or {\"first\": 50}), plus your where / order.
Read pageInfo.hasNextPage. If true, take pageInfo.endCursor and resend the same where / order with cursor = { \"first\": 50, \"after\": <endCursor> }.
Repeat until hasNextPage is false.

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"928ae063-6e52-4968-b38b-972f03f39928"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"c2a2b22f-9e61-43f3-b5a0-b3a94c483dd1"}}],"_postman_id":"07a5c9c7-4731-43c7-beb1-bb203a92f7f8"},{"name":"Find Categories","id":"0e3b9c20-6aa3-4459-9452-b48797de7e4b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"brand\": null,\n \"cursor\": {\n \"first\": 50,\n \"after\": null\n },\n \"where\": {\n \"predicate\": \"eq\",\n \"fieldPath\": \"category__sportId\",\n \"value\": \"d6934640-cf1d-11e9-864b-0242ac13000a\"\n },\n \"order\": [\n { \"fieldPath\": \"category__priority\", \"direction\": \"ASC\" },\n { \"fieldPath\": \"category__name\", \"direction\": \"ASC\" }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/sportsbook/categories","description":"

Returns a page of sportsbook categories for the given brand.

Uses the shared cursor-based pagination described in the Pagination section of this folder (request fields: cursor, where, order; response envelope: page).

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider.
\n
brand (string, optional) - Brand code, when applicable.
\n
cursor (object, optional) - Pagination cursor. See Pagination.
\n
where (object, optional) - Filter tree over whereFieldPaths (see below). See Pagination.
\n
order (array, optional) - Sort over orderByFieldPaths (see below). Default: category__name ASC, category__id ASC.
\n

`whereFieldPaths`

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

fieldPath	type	description
`category__id`	UUID	Category id.
`category__name`	string	Category name.
`category__sportId`	UUID	Parent sport id. See Sports for the id → code mapping.
`category__eventStartTime`	timestamp	Filters categories that have at least one event whose `startTime` matches the leaf condition. Value is epoch milliseconds as a string (or relative date token, see Pagination → Timestamp values). Useful with `gte` / `lt` to fetch categories that have upcoming events in a window.

`orderByFieldPaths`

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

fieldPath	type	notes
`category__name`	string	Case-insensitive. Default key.
`category__id`	UUID	Stable tie-breaker. Default key.
`category__priority`	int	Editorial sort priority (lower = higher up).

Response Body Description:

Object:

categories (object, required) - Page<Category> envelope (see Pagination → page).

Category (categories.edges[].node):

categoryId (string, required) - Category id (UUID).
\n
categoryName (string, required) - Category display name.
\n
sportId (string, required) - Parent sport id (UUID). See Sports.
\n

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"a104990e-b123-43bf-9db7-f03dbb389c4c","id":"a104990e-b123-43bf-9db7-f03dbb389c4c","name":"Sportsbook Tree","type":"folder"}},"urlObject":{"path":["external-casino-client","v1","sportsbook","categories"],"host":["{apiUrl}"],"query":[],"variable":[]}},"response":[{"id":"5bd5645d-f628-459d-b01b-2c7f2c110323","name":"success","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Basic e3VzZXJuYW1lfTp7cGFzc3dvcmR9","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"brand\": null,\n \"cursor\": { \"first\": 2 },\n \"where\": {\n \"predicate\": \"eq\",\n \"fieldPath\": \"category__sportId\",\n \"value\": \"d6934640-cf1d-11e9-864b-0242ac13000a\"\n },\n \"order\": [\n { \"fieldPath\": \"category__priority\", \"direction\": \"ASC\" }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/sportsbook/categories"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"categories\": {\n \"edges\": [\n {\n \"cursor\": \"eyJpZCI6IjIyMjIyMjIyLTIyMjItMjIyMi0yMjIyLTIyMjIyMjIyMjIyMiJ9\",\n \"node\": {\n \"categoryId\": \"22222222-2222-2222-2222-222222222222\",\n \"categoryName\": \"International Clubs\",\n \"sportId\": \"d6934640-cf1d-11e9-864b-0242ac13000a\"\n }\n },\n {\n \"cursor\": \"eyJpZCI6IjIyMjIyMjIyLTIyMjItMjIyMi0yMjIyLTIyMjIyMjIyMjIyMyJ9\",\n \"node\": {\n \"categoryId\": \"22222222-2222-2222-2222-222222222223\",\n \"categoryName\": \"England\",\n \"sportId\": \"d6934640-cf1d-11e9-864b-0242ac13000a\"\n }\n }\n ],\n \"pageInfo\": {\n \"hasPreviousPage\": false,\n \"hasNextPage\": true,\n \"startCursor\": \"eyJpZCI6IjIyMjIyMjIyLTIyMjItMjIyMi0yMjIyLTIyMjIyMjIyMjIyMiJ9\",\n \"endCursor\": \"eyJpZCI6IjIyMjIyMjIyLTIyMjItMjIyMi0yMjIyLTIyMjIyMjIyMjIyMyJ9\",\n \"total\": 57\n }\n }\n}"}],"_postman_id":"0e3b9c20-6aa3-4459-9452-b48797de7e4b"},{"name":"Find Tournaments","id":"275ca586-1d21-4790-91c0-3ea142269a5a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"brand\": null,\n \"cursor\": {\n \"first\": 50,\n \"after\": null\n },\n \"where\": {\n \"predicate\": \"eq\",\n \"fieldPath\": \"tournament__categoryId\",\n \"value\": \"22222222-2222-2222-2222-222222222222\"\n },\n \"order\": [\n { \"fieldPath\": \"tournament__priority\", \"direction\": \"ASC\" },\n { \"fieldPath\": \"tournament__name\", \"direction\": \"ASC\" }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/sportsbook/tournaments","description":"

Returns a page of sportsbook tournaments for the given brand.

Uses the shared cursor-based pagination described in the Pagination section of this folder (request fields: cursor, where, order; response envelope: page).

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider.
\n
brand (string, optional) - Brand code, when applicable.
\n
cursor (object, optional) - Pagination cursor. See Pagination.
\n
where (object, optional) - Filter tree over whereFieldPaths (see below). See Pagination.
\n
order (array, optional) - Sort over orderByFieldPaths (see below). Default: tournament__name ASC, tournament__id ASC.
\n

`whereFieldPaths`

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

fieldPath	type	description
`tournament__id`	UUID	Tournament id.
`tournament__name`	string	Tournament name.
`tournament__sportId`	UUID	Parent sport id. See Sports.
`tournament__categoryId`	UUID	Parent category id.
`tournament__eventStartTime`	timestamp	Filters tournaments that have at least one event whose `startTime` matches the leaf condition. Value is epoch milliseconds as a string (or relative date token, see Pagination → Timestamp values). Useful with `gte` / `lt` to fetch tournaments that have upcoming events in a window.

`orderByFieldPaths`

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

fieldPath	type	notes
`tournament__name`	string	Case-insensitive. Default key.
`tournament__id`	UUID	Stable tie-breaker. Default key.
`tournament__priority`	int	Editorial sort priority (lower = higher up).

Response Body Description:

Object:

tournaments (object, required) - Page<Tournament> envelope (see Pagination → page).

Tournament (tournaments.edges[].node):

tournamentId (string, required) - Tournament id (UUID).
\n
tournamentName (string, required) - Tournament display name.
\n
categoryId (string, required) - Parent category id (UUID).
\n
sportId (string, required) - Parent sport id (UUID). See Sports.
\n

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"a104990e-b123-43bf-9db7-f03dbb389c4c","id":"a104990e-b123-43bf-9db7-f03dbb389c4c","name":"Sportsbook Tree","type":"folder"}},"urlObject":{"path":["external-casino-client","v1","sportsbook","tournaments"],"host":["{apiUrl}"],"query":[],"variable":[]}},"response":[{"id":"d8beabf2-6127-4c27-b94b-ed43b5f570ea","name":"success","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Basic e3VzZXJuYW1lfTp7cGFzc3dvcmR9","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"brand\": null,\n \"cursor\": { \"first\": 2 },\n \"where\": {\n \"predicate\": \"eq\",\n \"fieldPath\": \"tournament__categoryId\",\n \"value\": \"22222222-2222-2222-2222-222222222222\"\n },\n \"order\": [\n { \"fieldPath\": \"tournament__priority\", \"direction\": \"ASC\" }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/sportsbook/tournaments"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"tournaments\": {\n \"edges\": [\n {\n \"cursor\": \"eyJpZCI6IjMzMzMzMzMzLTMzMzMtMzMzMy0zMzMzLTMzMzMzMzMzMzMzMyJ9\",\n \"node\": {\n \"tournamentId\": \"33333333-3333-3333-3333-333333333333\",\n \"tournamentName\": \"UEFA Champions League\",\n \"categoryId\": \"22222222-2222-2222-2222-222222222222\",\n \"sportId\": \"d6934640-cf1d-11e9-864b-0242ac13000a\"\n }\n },\n {\n \"cursor\": \"eyJpZCI6IjMzMzMzMzMzLTMzMzMtMzMzMy0zMzMzLTMzMzMzMzMzMzMzNCJ9\",\n \"node\": {\n \"tournamentId\": \"33333333-3333-3333-3333-333333333334\",\n \"tournamentName\": \"UEFA Europa League\",\n \"categoryId\": \"22222222-2222-2222-2222-222222222222\",\n \"sportId\": \"d6934640-cf1d-11e9-864b-0242ac13000a\"\n }\n }\n ],\n \"pageInfo\": {\n \"hasPreviousPage\": false,\n \"hasNextPage\": true,\n \"startCursor\": \"eyJpZCI6IjMzMzMzMzMzLTMzMzMtMzMzMy0zMzMzLTMzMzMzMzMzMzMzMyJ9\",\n \"endCursor\": \"eyJpZCI6IjMzMzMzMzMzLTMzMzMtMzMzMy0zMzMzLTMzMzMzMzMzMzMzNCJ9\",\n \"total\": 12\n }\n }\n}"}],"_postman_id":"275ca586-1d21-4790-91c0-3ea142269a5a"},{"name":"Find Events","id":"4217be49-9308-4995-8c36-18a7da8482b8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"brand\": null,\n \"cursor\": {\n \"first\": 50,\n \"after\": null\n },\n \"where\": {\n \"predicate\": \"and\",\n \"operands\": [\n { \"predicate\": \"eq\", \"fieldPath\": \"event__tournamentId\", \"value\": \"33333333-3333-3333-3333-333333333333\" },\n { \"predicate\": \"gte\", \"fieldPath\": \"event__startTime\", \"value\": \"1779753600000\" },\n { \"predicate\": \"lt\", \"fieldPath\": \"event__startTime\", \"value\": \"1780358400000\" },\n { \"predicate\": \"is_null\", \"fieldPath\": \"event__finishedAt\" }\n ]\n },\n \"order\": [\n { \"fieldPath\": \"event__startTime\", \"direction\": \"ASC\" },\n { \"fieldPath\": \"event__id\", \"direction\": \"ASC\" }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/sportsbook/events","description":"

Returns a page of sportsbook events for the given brand.

Uses the shared cursor-based pagination described in the Pagination section of this folder (request fields: cursor, where, order; response envelope: page).

Request Body Description:

Object:

brandId (int, required) - Brand id provided by aggregator provider.
\n
brand (string, optional) - Brand code, when applicable.
\n
cursor (object, optional) - Pagination cursor. See Pagination.
\n
where (object, optional) - Filter tree over whereFieldPaths (see below). See Pagination.
\n
order (array, optional) - Sort over orderByFieldPaths (see below). Default: event__createdAt DESC, event__id ASC.
\n

`whereFieldPaths`

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

fieldPath	type	description
`event__id`	UUID	Event id.
`event__name`	string	Event name. Also matches participant names (so a leaf with `like` / `unaccent_like` on `event__name` will surface events containing the substring in either the event title or one of its team names).
`event__status`	enum	Event lifecycle status. Use `eq` / `in` / `not_in` with the open string values listed under Transaction Details → `eventStatus` (`not_started`, `in_progress`, `finished`, `cancelled`, `interrupted`, `postponed`, `retired`, `corrupted`).
`event__sportId`	UUID	Sport id. See Sports for the id → code mapping.
`event__categoryId`	UUID	Category id.
`event__tournamentId`	UUID	Tournament id.
`event__startTime`	timestamp	Scheduled kick-off / start time. Value is epoch milliseconds as a string (e.g. `\"1779753600000\"`) or a relative date token (`P1D`, `MD`, `-P1H`, `MD_TZEurope/Berlin`, ...). See Pagination → Timestamp values. Use with `gt` / `gte` / `lt` / `lte`.
`betting__status`	enum	Betting status (open / suspended / closed). Use `eq` / `in`.
`event__finishedAt`	timestamp	Time when the event was marked finished. Same value format as `event__startTime` (epoch millis / relative). Use `is_null` to fetch upcoming/live events, `is_not_null` for settled events, or `gte` / `lte` for time windows.

`orderByFieldPaths`

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

fieldPath	type	notes
`event__createdAt`	timestamp	Default key, default direction `DESC`.
`event__id`	UUID	Default key. Stable tie-breaker.
`event__startTime`	timestamp	Sort by scheduled start.
`event__name`	string	Sort by event name.
`event__status`	enum	Sort by event status.
`betting__status`	enum	Sort by betting status.
`event__betsCount`	int	Sort by number of bets placed on the event.

Response Body Description:

Object:

events (object, required) - Page<Event> envelope (see Pagination → page).

Event (events.edges[].node):

eventId (string, required) - Event id (UUID).
\n
eventName (string, required) - Event display name.
\n
eventStartTime (string, required) - Scheduled start time as ISO-8601 instant.
\n
tournamentId (string, required) - Parent tournament id (UUID).
\n
categoryId (string, required) - Parent category id (UUID).
\n
sportId (string, required) - Parent sport id (UUID). See Sports.
\n

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"a104990e-b123-43bf-9db7-f03dbb389c4c","id":"a104990e-b123-43bf-9db7-f03dbb389c4c","name":"Sportsbook Tree","type":"folder"}},"urlObject":{"path":["external-casino-client","v1","sportsbook","events"],"host":["{apiUrl}"],"query":[],"variable":[]}},"response":[{"id":"6546a008-434d-4796-8295-ad779c3531f7","name":"success","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Basic e3VzZXJuYW1lfTp7cGFzc3dvcmR9","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"brand\": null,\n \"cursor\": { \"first\": 2 },\n \"where\": {\n \"predicate\": \"and\",\n \"operands\": [\n { \"predicate\": \"eq\", \"fieldPath\": \"event__tournamentId\", \"value\": \"33333333-3333-3333-3333-333333333333\" },\n { \"predicate\": \"is_null\", \"fieldPath\": \"event__finishedAt\" }\n ]\n },\n \"order\": [\n { \"fieldPath\": \"event__startTime\", \"direction\": \"ASC\" }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/sportsbook/events"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"events\": {\n \"edges\": [\n {\n \"cursor\": \"eyJpZCI6IjQ0NDQ0NDQ0LTQ0NDQtNDQ0NC00NDQ0LTQ0NDQ0NDQ0NDQ0NCJ9\",\n \"node\": {\n \"eventId\": \"44444444-4444-4444-4444-444444444444\",\n \"eventName\": \"Real Madrid vs Manchester City\",\n \"eventStartTime\": \"2026-05-28T20:00:00Z\",\n \"tournamentId\": \"33333333-3333-3333-3333-333333333333\",\n \"categoryId\": \"22222222-2222-2222-2222-222222222222\",\n \"sportId\": \"d6934640-cf1d-11e9-864b-0242ac13000a\"\n }\n },\n {\n \"cursor\": \"eyJpZCI6IjQ0NDQ0NDQ0LTQ0NDQtNDQ0NC00NDQ0LTQ0NDQ0NDQ0NDQ0NSJ9\",\n \"node\": {\n \"eventId\": \"44444444-4444-4444-4444-444444444445\",\n \"eventName\": \"Bayern Munich vs Paris Saint-Germain\",\n \"eventStartTime\": \"2026-05-29T20:00:00Z\",\n \"tournamentId\": \"33333333-3333-3333-3333-333333333333\",\n \"categoryId\": \"22222222-2222-2222-2222-222222222222\",\n \"sportId\": \"d6934640-cf1d-11e9-864b-0242ac13000a\"\n }\n }\n ],\n \"pageInfo\": {\n \"hasPreviousPage\": false,\n \"hasNextPage\": true,\n \"startCursor\": \"eyJpZCI6IjQ0NDQ0NDQ0LTQ0NDQtNDQ0NC00NDQ0LTQ0NDQ0NDQ0NDQ0NCJ9\",\n \"endCursor\": \"eyJpZCI6IjQ0NDQ0NDQ0LTQ0NDQtNDQ0NC00NDQ0LTQ0NDQ0NDQ0NDQ0NSJ9\",\n \"total\": 8\n }\n }\n}"}],"_postman_id":"4217be49-9308-4995-8c36-18a7da8482b8"}],"id":"a104990e-b123-43bf-9db7-f03dbb389c4c","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"5e856d92-aecd-4db4-95b6-b7e4d447ea31"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"e6db0630-203c-49ef-a194-fc7008c6490d"}}],"_postman_id":"a104990e-b123-43bf-9db7-f03dbb389c4c","description":""}],"id":"bec549e2-3937-4f1e-ba97-2fa3cc787b72","description":"

Reference structures for the sportsbook-specific payloads attached to Casino API callbacks (Transaction, End Round).

When the originating transaction comes from a sportsbook bet, the request body carries an extra details object alongside the regular casino fields. Casino game transactions leave it null.

This folder documents:

Transaction Details - the full details object schema and an example payload.
\n
Sports - shared reference table mapping sportId (UUID) to its sport code; used by both Event Pick and Outright Pick.
\n
Bet Structure - structural summary of the bet (single / parlay / system, banker count) exposed at details.bet.betStructure.
\n
Outcome - the outcome object on an Event Pick: scopeName, scopeNumber, scoreType, marketGroup, marketParameters map and outcomeParameters map. Enumerates all possible values per field.
\n

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"0806bc3d-67f2-42f5-8b4d-e965aa4186a1"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"0dbb0f20-9301-4e84-b0e9-9194de5021f0"}}],"_postman_id":"bec549e2-3937-4f1e-ba97-2fa3cc787b72"},{"name":"Affiliate API","item":[{"name":"Aggregator API","item":[{"name":"Register User","id":"9101e116-25ac-4536-9c8a-d83a824b9f75","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"username\": \"mehmet.demir\",\n \"name\": \"Mehmet\",\n \"surname\": \"Demir\",\n \"honorific\": \"Mr\",\n \"locale\": \"tr_TR\",\n \"currency\": \"TRY\",\n \"tracker\": {\n \"type\": \"TRACKING_CODE\",\n \"value\": \"ABHoQxDbREpLTHMp18gbAL6wZw\"\n },\n \"promoCode\": \"WELCOME\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/affiliate/users/register","description":"

Endpoint for Customer Registration

Endpoint

POST /external-casino-client/v1/affiliate/users/register

Description

This endpoint allows external casino systems to register affiliate users. The system supports idempotent operations - if a user with the same externalUserId and brandId already exists, the stored user data is returned instead of creating a duplicate.

Request Body Description

Object:

brandId (Int, required) - Brand id provided by aggregator provider. Must be a valid brand identifier.
\n
externalUserId (string, required) - Unique identifier of the user in the casino system. Must be unique among all users for the same brand. Cannot be blank.
\n
username (string, required) - Username for the user. Cannot be blank.
\n
name (string, optional) - First name of the user. Can be null.
\n
surname (string, optional) - Last name of the user. Can be null.
\n
honorific (enum, optional) - Honorific title for the user. Please refer to the common API documentation for honorific enum values. Can be null.
\n
locale (enum, required) - Locale code for the user. Please refer to the common API documentation for locale enum values. Must be a valid locale enum value.
\n
currency (string, required) - Currency code. Must be a valid currency code and cannot be blank. Please refer to the common API documentation for currency code rules.
\n
tracker (object, optional) - Tracking information for affiliate attribution. Can be null if the user registration should not be attributed to any affiliate. If provided, must be a valid tracker object. The tracker object has the following structure:
\n
- type (enum, required) - Tracker type. Valid values:
  \n
  - TRACKING_CODE - Tracking code type
    \n
  - LINK_CODE - Link code type
    \n
  \n
- value (string, required) - Tracker value. The value must be non-empty and cannot be blank. This validation applies to both TRACKING_CODE and LINK_CODE tracker types.
  \n
\n
promoCode (string, optional) - Promotional code associated with the registration. Can be null.
\n

Response Body Description

Object:

internalUserId (string, required) - Internal user identifier in the aggregator provider system. This is a unique identifier generated by the system and can be used for future reference or queries.
\n
externalUserId (string, required) - User identifier from the request. If a user with this externalUserId and brandId already exists, the stored value is returned (idempotent behavior).
\n
brandId (integer, required) - Brand id from the request. If the user already exists, the stored value is returned.
\n
createdAt (long, required) - Created at timestamp when the user was registered. If the user already exists, the stored value is returned. Please refer to the common API documentation for timestamp format rules.
\n
referrer (object, optional) - Referrer information if the user was referred by an affiliate. Can be null if no referrer is associated with the user. The referrer object has the following structure:
\n
- type (enum, required) - Referrer type. Valid values:
  \n
  - AFFILIATE - User was referred by an affiliate
  \n
- id (string, required) - Referrer identifier (UUID format). Unique identifier of the referrer.
  \n
\n

**When** **`referrer`** **is null:**\n- No `tracker` was provided in the request (user registered without attribution)\n- The `tracker` value provided in the request could not be resolved to a valid referrer (affiliate)\n- The tracker value does not exist in the system or is invalid\n- No referrer was associated with the user during registration\n**When** **`referrer`** **is not null:**\n- The `tracker` value provided in the request was successfully resolved to a valid referrer\n- The system identified an affiliate associated with the tracker value\n- The referrer information is returned to indicate successful attribution\n**Idempotent behavior:**\n- If a user with the same `externalUserId` and `brandId` already exists, the stored referrer value from the original registration is returned\n- This means the referrer value (null or not null) will be the same as it was during the initial registration, regardless of the tracker value in subsequent requests\n\n

username (string, optional) - Username from the request. If the user already exists, the stored value is returned. Can be null.
\n
name (string, optional) - First name from the request. If the user already exists, the stored value is returned. Can be null.
\n
surname (string, optional) - Last name from the request. If the user already exists, the stored value is returned. Can be null.
\n
honorific (enum, optional) - Honorific from the request. If the user already exists, the stored value is returned. Please refer to the common API documentation for honorific enum values. Can be null.
\n
locale (enum, required) - Locale from the request. If the user already exists, the stored value is returned. Please refer to the common API documentation for locale enum values.
\n
currency (string, optional) - Currency code from the request. If the user already exists, the stored value is returned. Please refer to the common API documentation for currency code rules. Can be null.
\n

Request Example

Registration with Tracking Code

{\n  \"brandId\": 1,\n  \"externalUserId\": \"user-abc-123\",\n  \"username\": \"johndoe\",\n  \"name\": \"John\",\n  \"surname\": \"Doe\",\n  \"honorific\": \"MR\",\n  \"locale\": \"en_US\",\n  \"currency\": \"USD\",\n  \"tracker\": {\n    \"type\": \"TRACKING_CODE\",\n    \"value\": \"tracking-code-12345\"\n  },\n  \"promoCode\": \"WELCOME2024\"\n}\n\n

Registration with Link Code

{\n  \"brandId\": 1,\n  \"externalUserId\": \"user-xyz-789\",\n  \"username\": \"janedoe\",\n  \"name\": \"Jane\",\n  \"surname\": \"Doe\",\n  \"locale\": \"en_GB\",\n  \"currency\": \"GBP\",\n  \"tracker\": {\n    \"type\": \"LINK_CODE\",\n    \"value\": \"link-code-67890\"\n  }\n}\n\n

Minimal Registration

{\n  \"brandId\": 1,\n  \"externalUserId\": \"user-minimal-456\",\n  \"username\": \"minimaluser\",\n  \"locale\": \"tr_TR\",\n  \"currency\": \"TRY\",\n  \"tracker\": {\n    \"type\": \"TRACKING_CODE\",\n    \"value\": \"tracking-code-11111\"\n  }\n}\n\n

Registration without Attribution

{\n  \"brandId\": 1,\n  \"externalUserId\": \"user-no-attribution-789\",\n  \"username\": \"directuser\",\n  \"locale\": \"en_US\",\n  \"currency\": \"USD\"\n}\n\n

Response Example

Successful Response (200 OK)

{\n  \"internalUserId\": \"internal-user-uuid-12345\",\n  \"externalUserId\": \"user-abc-123\",\n  \"brandId\": 1,\n  \"createdAt\": 1704067200000,\n  \"referrer\": null,\n  \"username\": \"johndoe\",\n  \"name\": \"John\",\n  \"surname\": \"Doe\",\n  \"honorific\": \"MR\",\n  \"locale\": \"en_US\",\n  \"currency\": \"USD\"\n}\n\n

Successful Response with Referrer (200 OK)

{\n  \"internalUserId\": \"internal-user-uuid-12345\",\n  \"externalUserId\": \"user-abc-123\",\n  \"brandId\": 1,\n  \"createdAt\": 1704067200000,\n  \"referrer\": {\n    \"type\": \"AFFILIATE\",\n    \"id\": \"550e8400-e29b-41d4-a716-446655440000\"\n  },\n  \"username\": \"johndoe\",\n  \"name\": \"John\",\n  \"surname\": \"Doe\",\n  \"honorific\": \"MR\",\n  \"locale\": \"en_US\",\n  \"currency\": \"USD\"\n}\n\n

Error Responses

400 Bad Request - Request Validation Error

Occurs when request validation fails. Common causes:

Missing required fields
\n
Invalid field formats (e.g., invalid currency code, invalid enum value)
\n
Blank values for required string fields
\n
Invalid tracker format or value (if tracker is provided)
\n
Invalid tracker type (if tracker is provided)
\n

Example Error Response:

{\n  \"error\": \"Request validation failed\",\n  \"message\": \"Field 'currency' must be a valid currency code\"\n}\n\n

400 Bad Request - Invalid Tracker

Occurs when a tracker is provided but the format or value is invalid. Common causes:

Missing type or value field in tracker object
\n
Invalid tracker type (must be TRACKING_CODE or LINK_CODE)
\n
Blank or empty tracker value
\n

Note: This error only occurs when a tracker object is provided. If no tracker is provided, the registration will succeed without attribution.

Example Error Response:

{\n  \"error\": \"Request validation failed\",\n  \"message\": \"Tracker value should be valid tracking code\"\n}\n\n

500 Internal Server Error - Unknown Error

Occurs when an unexpected server error happens.

Example Error Response:

{\n  \"error\": \"Unknown error\",\n  \"message\": \"An unexpected error occurred\"\n}\n\n

Important Notes

Idempotency: The endpoint is idempotent. If you send the same request (same externalUserId and brandId) multiple times, you will receive the same response with the stored user data. This prevents duplicate user registrations.
\n
User Uniqueness: The combination of externalUserId and brandId must be unique. Attempting to register a user with the same externalUserId and brandId but different data will return the existing user.
\n
Tracker and Attribution:
\n
- The tracker field is optional. If not provided, the user will be created without attribution (the referrer field in the response will be null)
  \n
- If tracker is provided, it must contain a valid tracker object
  \n
- The tracker type must be either TRACKING_CODE or LINK_CODE
  \n
- The tracker value must be non-empty and cannot be blank for both tracker types
  \n
- If a valid tracker is provided and can be resolved, the referrer field in the response will contain the referrer information
  \n
\n
Currency Codes: Please refer to the common API documentation for currency code rules.
\n
Locale Values: Please refer to the common API documentation for locale enum values.
\n
Honorific Values: Please refer to the common API documentation for honorific enum values.
\n
Timestamp Format: Please refer to the common API documentation for timestamp format rules.
\n

Authentication

This endpoint requires authentication. Please refer to the authentication documentation for details on how to include authentication headers in your requests.

\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{username}"},{"key":"password","value":"{password}"}]},"isInherited":true,"source":{"_postman_id":"33842f32-77e6-4695-b800-7331205900bf","id":"33842f32-77e6-4695-b800-7331205900bf","name":"Affiliate API","type":"folder"}},"urlObject":{"path":["external-casino-client","v1","affiliate","users","register"],"host":["{apiUrl}"],"query":[],"variable":[]}},"response":[{"id":"b4828a0e-4640-4cf4-8504-e3e42eaf1d79","name":"success","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Basic e3VzZXJuYW1lfTp7cGFzc3dvcmR9","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"username\": \"mehmet.demir\",\n \"name\": \"Mehmet\",\n \"surname\": \"Demir\",\n \"honorific\": \"Mr\",\n \"locale\": \"tr_TR\",\n \"currency\": \"TRY\",\n \"tracker\": {\n \"type\": \"TRACKING_CODE\",\n \"value\": \"ABHoQxDbREpLTHMp18gbAL6wZw\"\n },\n \"promoCode\": \"WELCOME\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/affiliate/users/register"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"internalUserId\": \"019a3409-eace-739e-ae71-83b41d323375\",\n \"externalUserId\": \"ext_987654321\",\n \"brandId\": 0,\n \"createdAt\": 1761721205143,\n \"referrer\": {\n \"id\": \"019a33fe-a05d-71bc-91fc-2ee9ca31ae1b\",\n \"type\": \"AFFILIATE\"\n },\n \"username\": \"mehmet.demir\",\n \"name\": \"Mehmet\",\n \"surname\": \"Demir\",\n \"honorific\": \"Mr\",\n \"locale\": \"tr_TR\",\n \"currency\": \"TRY\"\n}"},{"id":"7068e523-d97f-4dd1-82d9-7ffce5cbf039","name":"fail","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Basic e3VzZXJuYW1lfTp7cGFzc3dvcmR9","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"username\": \"mehmet.demir\",\n \"name\": \"Mehmet\",\n \"surname\": \"Demir\",\n \"honorific\": \"Mr\",\n \"locale\": \"tr_TR\",\n \"currency\": \"TRY\",\n \"tracker\": {\n \"type\": \"TRACKING_CODE\",\n \"value\": \"ABHoQxDbREpLTHMp18gbAL6wZw\"\n },\n \"promoCode\": \"WELCOME\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/affiliate/users/register"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 107,\n \"errorMessage\": \"User creation failed\"\n}"}],"_postman_id":"9101e116-25ac-4536-9c8a-d83a824b9f75"},{"name":"Create User Financial Transaction","id":"c765f93b-0157-4935-8179-fcd7ac23b083","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"externalTxId\": \"ext_787654324\",\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"txType\": \"DEPOSIT\",\n \"amount\": 100,\n \"currency\": \"TRY\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/affiliate/users/transactions/financial/create","description":"

Endpoint for Creating Affiliate User Financial Transaction

Endpoint

POST /external-casino-client/v1/affiliate/users/transactions/financial/create

Description

This endpoint allows external casino systems to create financial transactions for affiliate users. The system supports idempotent operations - if a transaction with the same externalTxId and brandId already exists, the stored transaction data is returned instead of creating a duplicate.

Request Body Description

Object:

brandId (integer, required) - Brand id provided by aggregator provider. Must be a valid brand identifier.
\n
externalTxId (string, required) - Unique identifier of the transaction in the casino system. Must be unique among all transactions for the same brand. Cannot be blank.
\n
externalUserId (string, required) - User identifier in the casino system. Must match a previously registered affiliate user. Cannot be blank.
\n
createdAt (long, required) - Timestamp when the transaction was created. Must be a valid long integer. Please refer to the common API documentation for timestamp format rules.
\n
txType (enum, required) - Type of financial transaction. Valid values:
\n
- DEPOSIT - Funds deposited to the user account
  \n
- WITHDRAWAL - Funds withdrawn from the user account
  \n
- ROLLBACK - Transaction rollback (requires rolledBackExternalTxId)
  \n
\n
amount (integer, required) - Transaction amount. Must be a valid integer. Please refer to the common API documentation for amount format rules.
\n
currency (string, required) - Currency code. Must be a valid currency code and cannot be blank. Please refer to the common API documentation for currency code rules.
\n
rolledBackExternalTxId (string, optional) - Identifier of the transaction being rolled back. Required when txType is ROLLBACK. Must reference an existing transaction that was previously created. Can be null for DEPOSIT and WITHDRAWAL transaction types.
\n

Response Body Description

Object:

txId (string, required) - Internal transaction identifier in the aggregator provider system. This is a unique identifier generated by the system and can be used for future reference or queries.
\n
externalTxId (string, required) - Transaction identifier from the request. If a transaction with this externalTxId and brandId already exists, the stored value is returned (idempotent behavior).
\n
brandId (integer, required) - Brand id from the request. If the transaction already exists, the stored value is returned.
\n
externalUserId (string, required) - User identifier in the casino system from the request. If the transaction already exists, the stored value is returned.
\n
createdAt (long, required) - Created at timestamp from the request. If the transaction already exists, the stored value is returned. Please refer to the common API documentation for timestamp format rules.
\n
txType (enum, required) - Transaction type from the request. Valid values: DEPOSIT, WITHDRAWAL, ROLLBACK. If the transaction already exists, the stored value is returned.
\n
amount (integer, required) - Transaction amount from the request. If the transaction already exists, the stored value is returned. Please refer to the common API documentation for amount format rules.
\n
currency (string, required) - Currency code from the request. If the transaction already exists, the stored value is returned. Please refer to the common API documentation for currency code rules.
\n
rolledBackExternalTxId (string, optional) - Identifier of the rolled back transaction from the request. Required for rollback transactions. If the transaction already exists, the stored value is returned. Can be null for DEPOSIT and WITHDRAWAL transaction types.
\n

Request Example

Deposit Transaction

{\n  \"brandId\": 1,\n  \"externalTxId\": \"tx-deposit-12345\",\n  \"externalUserId\": \"user-abc-123\",\n  \"createdAt\": 1704067200000,\n  \"txType\": \"DEPOSIT\",\n  \"amount\": 10000,\n  \"currency\": \"USD\"\n}\n\n

Withdrawal Transaction

{\n  \"brandId\": 1,\n  \"externalTxId\": \"tx-withdrawal-67890\",\n  \"externalUserId\": \"user-abc-123\",\n  \"createdAt\": 1704067300000,\n  \"txType\": \"WITHDRAWAL\",\n  \"amount\": 5000,\n  \"currency\": \"EUR\"\n}\n\n

Rollback Transaction

{\n  \"brandId\": 1,\n  \"externalTxId\": \"tx-rollback-11111\",\n  \"externalUserId\": \"user-abc-123\",\n  \"createdAt\": 1704067400000,\n  \"txType\": \"ROLLBACK\",\n  \"amount\": 10000,\n  \"currency\": \"USD\",\n  \"rolledBackExternalTxId\": \"tx-deposit-12345\"\n}\n\n

Response Example

Successful Response (200 OK)

{\n  \"txId\": \"internal-tx-uuid-12345\",\n  \"externalTxId\": \"tx-deposit-12345\",\n  \"brandId\": 1,\n  \"externalUserId\": \"user-abc-123\",\n  \"createdAt\": 1704067200000,\n  \"txType\": \"DEPOSIT\",\n  \"amount\": 10000,\n  \"currency\": \"USD\",\n  \"rolledBackExternalTxId\": null\n}\n\n

Error Responses

400 Bad Request - Request Validation Error

Occurs when request validation fails. Common causes:

Missing required fields
\n
Invalid field formats (e.g., invalid currency code, invalid enum value)
\n
Blank values for required string fields
\n
Invalid integer or long values
\n

Example Error Response:

{\n  \"error\": \"Request validation failed\",\n  \"message\": \"Field 'currency' must be a valid currency code\"\n}\n\n

400 Bad Request - Invalid User

Occurs when the externalUserId does not exist in the system (user not registered).

Example Error Response:

{\n  \"error\": \"Invalid user\",\n  \"message\": \"User with externalUserId 'user-abc-123' not found\"\n}\n\n

400 Bad Request - Rolled Back Transaction Not Found

Occurs when txType is ROLLBACK but the rolledBackExternalTxId references a transaction that does not exist.

Example Error Response:

{\n  \"error\": \"Rolled back transaction not found\",\n  \"message\": \"Transaction with externalTxId 'tx-deposit-12345' not found\"\n}\n\n

400 Bad Request - Missing Rolled Back Transaction ID

Occurs when txType is ROLLBACK but rolledBackExternalTxId is not provided.

Example Error Response:

{\n  \"error\": \"Missing rolled back transaction ID\",\n  \"message\": \"rolledBackExternalTxId is required for ROLLBACK transactions\"\n}\n\n

500 Internal Server Error - Unknown Error

Occurs when an unexpected server error happens.

Example Error Response:

{\n  \"error\": \"Unknown error\",\n  \"message\": \"An unexpected error occurred\"\n}\n\n

Important Notes

Idempotency: The endpoint is idempotent. If you send the same request (same externalTxId and brandId) multiple times, you will receive the same response with the stored transaction data. This prevents duplicate transactions.
\n
Transaction Uniqueness: The combination of externalTxId and brandId must be unique. Attempting to create a transaction with the same externalTxId and brandId but different data will return the existing transaction.
\n
User Registration: The externalUserId must reference a user that was previously registered through the affiliate user registration endpoint.
\n
Rollback Transactions:
\n
- When txType is ROLLBACK, the rolledBackExternalTxId field is required
  \n
- The rolledBackExternalTxId must reference an existing transaction (DEPOSIT or WITHDRAWAL)
  \n
- The amount in a rollback transaction should typically match the amount of the original transaction
  \n
\n
Amount Format: Please refer to the common API documentation for amount format rules.
\n
Currency Codes: Please refer to the common API documentation for currency code rules.
\n
Timestamp Format: Please refer to the common API documentation for timestamp format rules.
\n

Authentication

This endpoint requires authentication. Please refer to the authentication documentation for details on how to include authentication headers in your requests.

\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{username}"},{"key":"password","value":"{password}"}]},"isInherited":true,"source":{"_postman_id":"33842f32-77e6-4695-b800-7331205900bf","id":"33842f32-77e6-4695-b800-7331205900bf","name":"Affiliate API","type":"folder"}},"urlObject":{"path":["external-casino-client","v1","affiliate","users","transactions","financial","create"],"host":["{apiUrl}"],"query":[],"variable":[]}},"response":[{"id":"b5afda67-41cc-4de3-8754-d09a99a60cd6","name":"success","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"externalTxId\": \"ext_787654324\",\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"txType\": \"DEPOSIT\",\n \"amount\": 100,\n \"currency\": \"TRY\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/affiliate/users/transactions/financial/create"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"txId\": \"019a3404-b7f5-7b9e-abc3-1a3318c0b245\",\n \"externalTxId\": \"ext_787654324\",\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"txType\": \"DEPOSIT\",\n \"amount\": 100,\n \"currency\": \"TRY\"\n}"},{"id":"ebbd70a6-e005-4785-be0c-726397bc864e","name":"success rollback","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"externalTxId\": \"ext_787654324\",\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"txType\": \"ROLLBACK\",\n \"amount\": 100,\n \"currency\": \"TRY\",\n \"rolledBackExternalTxId\": \"ext_787654323\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/affiliate/users/transactions/financial/create"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"txId\": \"019a3404-b7f5-7b9e-abc3-1a3318c0b245\",\n \"externalTxId\": \"ext_787654324\",\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"txType\": \"ROLLBACK\",\n \"amount\": 100,\n \"currency\": \"TRY\",\n \"rolledBackExternalTxId\": \"ext_787654323\"\n}"},{"id":"7f4441a8-ac71-443e-becd-92145af5c951","name":"fail","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"externalTxId\": \"ext_787654324\",\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"txType\": \"DEPOSIT\",\n \"amount\": 100,\n \"currency\": \"TRY\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/affiliate/users/transactions/financial/create"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"errorCode\": 109,\n \"errorMessage\": \"Invalid User\"\n}"}],"_postman_id":"c765f93b-0157-4935-8179-fcd7ac23b083"},{"name":"Get Affiliate Profile","id":"3f2a340c-95f4-4f10-8f3d-77c29050bc95","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"resolver\": {\n \"type\": \"TRACKER\",\n \"tracker\": {\n \"type\": \"TRACKING_CODE\",\n \"value\": \"AAJpzQHEQm5wU2wvSSizCB1ZwRzSeB\"\n }\n }\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/external-casino-client/v1/affiliate/profile/get","description":"

Endpoint for Fetching Affiliate Profile

Endpoint

POST /external-casino-client/v1/affiliate/profile/get

Description

This endpoint allows external casino systems to retrieve affiliate profile information. The affiliate can be resolved either by direct ID or by a tracker (link code or tracking code).

Request Body Description

Object:

brandId (integer, required) - Brand id provided by aggregator provider. Must be a valid brand identifier.
\n
resolver (object, required) - Defines how to resolve the affiliate. Uses polymorphic deserialization based on the type discriminator field. The resolver object has the following structure:
\n
- type (enum, required) - Resolution strategy type. Valid values:
  \n
  - ID - Resolve affiliate directly by identifier
    \n
  - TRACKER - Resolve affiliate by tracker (link code or tracking code)
    \n
  \n
\n

When type is ID:

id (string, required) - Affiliate identifier in UUID format. Cannot be blank. Maximum length: 36 characters. Must reference an existing affiliate in the system.

When type is TRACKER:

tracker (object, required) - Tracking information used to resolve the affiliate. The tracker object has the following structure:
\n
- type (enum, required) - Tracker type. Valid values:
  \n
  - TRACKING_CODE - Tracking code type
    \n
  - LINK_CODE - Link code type
    \n
  \n
- value (string, required) - Tracker value. The value must be non-empty and cannot be blank. This validation applies to both TRACKING_CODE and LINK_CODE tracker types.
  When tracker type is TRACKING_CODE:
  \n
  - The value must be a valid, non-expired tracking code token
    \n
  - The tracking code must resolve to an existing affiliate link in the system
    \n
  \n
\n

When tracker type is LINK_CODE:

The value must be a valid link short code
\n
The short code must reference an existing, non-deleted affiliate link in the system
\n
If the link is not found, error code 204 (Affiliate link not found) is returned
\n

Response Body Description

Object:

id (string, required) - Affiliate identifier in the aggregator provider system. UUID format.
\n
username (string, optional) - Affiliate login username. Can be null if the affiliate has no login assigned.
\n
profile (object, required) - Affiliate personal profile information. Contains personal details of the affiliate. The profile object has the following structure:
\n
- name (string, optional) - Affiliate first name. Can be null.
  \n
- surname (string, optional) - Affiliate surname. Can be null.
  \n
- country (string, required) - Country ISO 3166-1 alpha-3 code (e.g., FRA, TUR, USA).
  \n
- locale (string, required) - Affiliate locale code (e.g., tr_TR, en_US).
  \n
\n
status (string, required) - Affiliate account status. Possible values: ACTIVE, SUSPENDED, CLOSED.
\n
approveStatus (string, required) - Affiliate approval status. Possible values: APPROVED, REJECTED, PENDING.
\n
companyName (string, optional) - Affiliate company name. Can be null.
\n

Request Examples

Resolve by ID

{\n  \"brandId\": 0,\n  \"resolver\": {\n    \"type\": \"ID\",\n    \"id\": \"019d495b-bd90-7887-9403-b253b853f460\"\n  }\n}\n\n

Resolve by Link Code

{\n  \"brandId\": 1,\n  \"resolver\": {\n    \"type\": \"TRACKER\",\n    \"tracker\": {\n      \"type\": \"LINK_CODE\",\n      \"value\": \"abc123\"\n    }\n  }\n}\n\n

Resolve by Tracking Code

{\n  \"brandId\": 1,\n  \"resolver\": {\n    \"type\": \"TRACKER\",\n    \"tracker\": {\n      \"type\": \"TRACKING_CODE\",\n      \"value\": \"AAJpzQHEQm5wU2wvSSizCB1ZwRzSeB\"\n    }\n  }\n}\n\n

Response Example

Successful Response (200 OK)

{\n    \"id\": \"019d495b-bd90-7887-9403-b253b853f460\",\n    \"username\": \"mehmet.demir\",\n    \"name\": \"Mehmet\",\n    \"surname\": \"Demir\",\n    \"country\": \"TUR\",\n    \"locale\": \"en_US\",\n    \"status\": \"ACTIVE\",\n    \"approveStatus\": \"APPROVED\",\n    \"companyName\": \"Mehmet Soft\"\n}\n\n

Error Responses

404 Not Found - Affiliate Not Found

Occurs when the resolver.type is ID and the provided affiliate identifier does not exist in the system.

Example Error Response:

{\n  \"errorCode\": 203,\n  \"errorMessage\": \"Affiliate not found\"\n}\n\n

404 Not Found - Affiliate Link Not Found

Occurs when the resolver.type is TRACKER and the tracker value (link code or tracking code) does not resolve to an existing affiliate link.

Example Error Response:

{\n  \"errorCode\": 204,\n  \"errorMessage\": \"Affiliate link not found\"\n}\n\n

400 Bad Request - Request Validation Error

Occurs when request validation fails. Common causes:

Missing required fields
\n
Invalid field formats (e.g., invalid resolver type, invalid tracker type)
\n
Blank values for required string fields
\n
id exceeds maximum length of 36 characters
\n

Example Error Response:

{\n  \"errorCode\": 3,\n  \"errorMessage\": \"Request validation failed: '...'\"\n}\n\n

500 Internal Server Error - Unknown Error

Occurs when an unexpected server error happens.

Example Error Response:

{\n  \"errorCode\": 1,\n  \"errorMessage\": \"Unknown error\"\n}\n\n

Important Notes

Resolution Strategies: The endpoint supports two resolution strategies via the resolver object:
\n
- ID - Direct lookup by affiliate identifier. Fastest resolution path.
  \n
- TRACKER - Resolution through the affiliate tracking system. Supports both link codes and tracking codes.
  \n
\n
Link Code Resolution: Link codes are short codes associated with affiliate links. The link must exist and not be deleted in the system.
\n
Affiliate Status: The response includes both status and approveStatus fields. An affiliate is considered generally active when status is ACTIVE and approveStatus is APPROVED.
\n

Authentication

This endpoint requires authentication. Please refer to the authentication documentation for details on how to include authentication headers in your requests.

\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{username}"},{"key":"password","value":"{password}"}]},"isInherited":true,"source":{"_postman_id":"33842f32-77e6-4695-b800-7331205900bf","id":"33842f32-77e6-4695-b800-7331205900bf","name":"Affiliate API","type":"folder"}},"urlObject":{"path":["external-casino-client","external-casino-client","v1","affiliate","profile","get"],"host":["{apiUrl}"],"query":[],"variable":[]}},"response":[{"id":"61d1b136-fdcf-424d-9aa8-713f9c5bb966","name":"success by tracker","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"resolver\": {\n \"type\": \"TRACKER\",\n \"tracker\": {\n \"type\": \"TRACKING_CODE\",\n \"value\": \"AAJpzQHEQm5wU2wvSSizCB1ZwRzSeB\"\n }\n }\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/affiliate/profile/get"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"id\": \"019d495b-bd90-7887-9403-b253b853f460\",\n \"username\": \"mehmet.demir\",\n \"profile\": {\n \"name\": \"Mehmet\",\n \"surname\": \"Demir\",\n \"country\": \"TUR\",\n \"locale\": \"en_US\"\n },\n \"status\": \"ACTIVE\",\n \"approveStatus\": \"APPROVED\",\n \"companyName\": \"Mehmet Soft\"\n}"},{"id":"7b48e6b3-accb-4396-b4d7-4b5a58da3e46","name":"success by id","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"resolver\": {\n \"type\": \"ID\",\n \"id\": \"019d495b-bd90-7887-9403-b253b853f460\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/affiliate/profile/get"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"id\": \"019d495b-bd90-7887-9403-b253b853f460\",\n \"username\": \"mehmet.demir\",\n \"profile\": {\n \"name\": \"Mehmet\",\n \"surname\": \"Demir\",\n \"country\": \"TUR\",\n \"locale\": \"en_US\"\n },\n \"status\": \"ACTIVE\",\n \"approveStatus\": \"APPROVED\",\n \"companyName\": \"Mehmet Soft\"\n}"},{"id":"aaf2b926-aeb1-434a-a4e7-0dccb97656ce","name":"fail","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"resolver\": {\n \"type\": \"ID\",\n \"id\": \"019d495b-bd90-7887-9403-b253b853f460\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/affiliate/profile/get"},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"errorCode\": 203,\n \"errorMessage\": \"Affiliate not found\"\n}"}],"_postman_id":"3f2a340c-95f4-4f10-8f3d-77c29050bc95"}],"id":"ebd8ed68-4667-49ff-b277-fc4aedb21205","description":"

Requests sent from Casino to Aggregator Provider

\n","_postman_id":"ebd8ed68-4667-49ff-b277-fc4aedb21205","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{username}"},{"key":"password","value":"{password}"}]},"isInherited":true,"source":{"_postman_id":"33842f32-77e6-4695-b800-7331205900bf","id":"33842f32-77e6-4695-b800-7331205900bf","name":"Affiliate API","type":"folder"}}}],"id":"33842f32-77e6-4695-b800-7331205900bf","description":"

Step-by-Step Integration Guide

Getting Started

Prerequisites

Before starting the integration, ensure you have:

Access to the aggregator provider API
\n
Your brandId assigned by the aggregator provider
\n
Authentication credentials (API keys, tokens, etc.)
\n
Understanding of your casino system's user registration flow
\n

Initial Setup

Contact the aggregator provider to:
\n
- Obtain your brandId
  \n
- Get API credentials and authentication details
  \n
- Receive API endpoint URLs
  \n
- Understand any brand-specific requirements
  \n
\n
Review API Documentation:
\n
- Read the Customer Registration API documentation
  \n
- Read the Financial Transaction API documentation
  \n
- Understand request/response format
  \n
\n

Understanding Tracking Methods

The system supports two types of tracking for affiliate attribution:

1. Tracking Codes (`TRACKING_CODE`)

What it is: A unique link transaction code that attributes each redirect from an affiliate tracking link
\n
How it works:
\n
- Generated automatically by the aggregator system for each click/redirect (unique per click)
  \n
- Uses a special encrypted format that contains attribution information
  \n
- Requires a tracking domain to function
  \n
- Clicks are counted when users click the tracking link
  \n
\n
Use case: When you need to track individual clicks and count redirects from affiliate links
\n
Format: Encrypted format generated automatically by the system
\n
Requirement: Requires tracking domain setup
\n

2. Link Codes (`LINK_CODE`)

What it is: A static code assigned to a link that can be used to attribute users
\n
How it works:
\n
- Generated randomly when creating a link in the Back Office
  \n
- Static code per link (doesn't change per click)
  \n
- Can be used with Cuttly links to survive domain blocks
  \n
- Does not count clicks
  \n
\n
Use case: When you need static attribution that works with short links (Cuttly) and can survive domain blocks
\n
Format: Randomly generated code created in Back Office
\n
Note: Cannot be used for postbacks (server-to-server callbacks)
\n

Tracking Codes

What are Tracking Codes?

Tracking codes are unique link transaction codes that are automatically generated by the aggregator system for each click/redirect from an affiliate tracking link. Each tracking code:

Is unique per click (not static)
\n
Contains encrypted attribution information
\n
Enables click counting
\n
Requires a tracking domain to function
\n

How Tracking Codes Work

Link Creation: An affiliate link is created with a link code in the Back Office
\n
User Clicks: When a user clicks the tracking link, the system automatically generates a unique tracking code
\n
Redirect: User is redirected to your casino with the tracking code in the tid query parameter
\n
Registration: Extract the tid parameter and include it in the registration request
\n
Attribution: The system decrypts the tracking code and attributes the user to the affiliate
\n
Click Counting: The click is counted when the tracking link is clicked
\n

Tracking Domain URL Structure

Tracking codes work with tracking domains using the following structure:

Initial Link Format:

https://tracking.com/{link-code}\n\n

After Click (Redirect):
When a user clicks the tracking link, they are redirected to your casino with a tid parameter:

https://yourcasino.com/register?tid={tracking-code}\n\n

The tid parameter contains the automatically generated tracking code (encrypted format).

How to Use Tracking Codes

Step 1: Extract Tracking Code from URL

When a user arrives at your registration page from a tracking domain, extract the tid parameter:

// Example JavaScript\nconst urlParams = new URLSearchParams(window.location.search);\nconst trackingCode = urlParams.get('tid');\n\n

Step 2: Include in Registration Request

{\n  \"brandId\": 1,\n  \"externalUserId\": \"user-abc-123\",\n  \"username\": \"johndoe\",\n  \"locale\": \"en_US\",\n  \"currency\": \"USD\",\n  \"tracker\": {\n    \"type\": \"TRACKING_CODE\",\n    \"value\": trackingCode\n  }\n}\n\n

Important Notes

Automatic Generation: Tracking codes are generated automatically - you don't create them manually
\n
Unique Per Click: Each click generates a new tracking code
\n
Encrypted Format: The tracking code uses a special encrypted format - don't try to decode or modify it
\n
Requires Tracking Domain: Tracking codes only work with properly configured tracking domains
\n
Click Counting: Clicks are counted automatically when users click the tracking link
\n

Link Codes

What are Link Codes?

Link codes are static codes assigned to affiliate links that can be used to attribute users. Unlike tracking codes:

Static: The same code is used for all clicks on a specific link
\n
No Click Counting: Clicks are not counted with link codes
\n
Cuttly Compatible: Typically used with URL shorteners like Cuttly
\n
Domain Block Survival: Can survive domain blocks through Cuttly link updates
\n
Query Parameter: Passed in the p query parameter
\n

How Link Codes Work

Link Creation: When creating an affiliate link in the Back Office, a link code is randomly generated
\n
Link Distribution: The link code is embedded in the affiliate link (typically in a Cuttly short link)
\n
User Clicks Cuttly Link: When a user clicks the Cuttly link, they are redirected to your casino page
\n
Redirect with Parameter: The redirect includes the p query parameter containing the link code
\n
Extract Link Code: Extract the p parameter value from the URL
\n
User Registration: Include the link code in the registration request to the aggregator
\n
Attribution: The system uses the link code to attribute the user to the affiliate
\n

How to Generate Link Codes

Link codes are generated randomly when you create a link in the Back Office:

Access the Back Office
\n
Create a new affiliate link
\n
The system automatically generates a random link code for that link
\n
The link code is static and remains the same for that specific link
\n

Using Link Codes with Cuttly Links

Creating Cuttly Links

Create Link in Back Office: Generate a link code through the Back Office
\n
Create Cuttly Short Link: Use the Back Office to create a Cuttly short link
\n
Link Format: The Cuttly link will redirect to your casino with the p query parameter containing the link code
\n

Cuttly Link Flow

User Clicks Cuttly Link: User clicks a Cuttly short link (e.g., https://cutt.ly/xyz123)
\n
Redirect to Casino: Cuttly redirects the user to your casino page
\n
URL with Parameter: The redirect URL includes the p query parameter: https://yourcasino.com/register?p={link-code}
\n
Extract Parameter: Extract the p parameter value from the URL
\n
Report to Aggregator: Include the link code in the registration request to the aggregator API
\n

Example Cuttly Link Flow

User clicks: https://cutt.ly/abc123\n↓\nCuttly redirects to: https://yourcasino.com/register?p=link-code-67890\n↓\nExtract p parameter: \"link-code-67890\"\n↓\nInclude in registration API:\n{\n  \"tracker\": {\n    \"type\": \"LINK_CODE\",\n    \"value\": \"link-code-67890\"\n  }\n}\n\n

Domain Block Survival

If your casino's main domain gets blocked:

Domain Rotation: Your external system should notify the aggregator provider about the domain rotation
\n
Automatic Update: The aggregator provider updates all Cuttly short links with your new domain
\n
Link Continuity: All existing Cuttly links continue to work with the new domain
\n
No Link Recreation: You don't need to recreate or redistribute links
\n
Parameter Preservation: The p parameter is preserved through the domain update
\n

Example Link Code Usage

{\n  \"tracker\": {\n    \"type\": \"LINK_CODE\",\n    \"value\": \"abc123xyz789\"\n  }\n}\n\n

Link Code Extraction

Link codes are always passed in the p query parameter. Extract the p parameter value from the URL:

// Example JavaScript - Extract p parameter\nconst urlParams = new URLSearchParams(window.location.search);\nconst linkCode = urlParams.get('p');\n\n

From Cuttly Link Redirect

When a user clicks a Cuttly link, they are redirected to your casino page with the p parameter:

Example URL after Cuttly redirect:

https://yourcasino.com/register?p=link-code-67890\n\n

Extract and use:

const urlParams = new URLSearchParams(window.location.search);\nconst linkCode = urlParams.get('p'); // Returns \"link-code-67890\"\n\n

From Tracking Domain URL

If using link codes with tracking domains, the URL format is:

https://track.example.com/?p=abc123xyz789\n\n

Extract the p parameter value the same way:

const urlParams = new URLSearchParams(window.location.search);\nconst linkCode = urlParams.get('p');\n\n

Important: Report Link Code to Aggregator

After extracting the p parameter value, you must report it back to the aggregator in the registration API request. The link code should be included in the tracker field:

{\n  \"brandId\": 1,\n  \"externalUserId\": \"user-abc-123\",\n  \"username\": \"johndoe\",\n  \"locale\": \"en_US\",\n  \"currency\": \"USD\",\n  \"tracker\": {\n    \"type\": \"LINK_CODE\",\n    \"value\": \"link-code-67890\"\n  }\n}\n\n

Important Notes

Static Codes: Link codes don't change per click - same code for all users clicking the same link
\n
No Click Counting: Link codes do not enable click counting
\n
Cuttly Compatible: Can be used with Cuttly short links
\n
Not for Postbacks: Link codes cannot be used for server-to-server postbacks (use tracking domains instead)
\n
Domain Block Protection: Cuttly links with link codes can be updated when domains are blocked
\n

Tracking Domains

What are Tracking Domains?

Tracking domains are custom domains (e.g., track.yourbrand.com) that redirect users to your casino registration page while preserving affiliate tracking information through URL parameters. Tracking domains are required for:

Tracking Codes: Enable click counting and automatic tracking code generation
\n
Postbacks: Required for server-to-server postback callbacks
\n

How to Create a Tracking Domain

Tracking domains can be easily created via the Back Office. The process is simplified and handled through the aggregator provider's interface.

Step 1: Access Back Office

Log in to the Back Office
\n
Navigate to the tracking domains section
\n
Select the option to create a new tracking domain
\n

Step 2: Provide Domain Information

Enter your domain: Provide the domain name you want to use (e.g., trackingyourbrand.com)
\n
Domain ownership: Ensure you have ownership rights to the domain
\n
Submit request: Submit the domain creation request through the Back Office
\n

Back Office Benefits

Creating tracking domains via Back Office provides:

✅ Simplified process: Easy-to-use interface for domain management
\n
✅ Automatic configuration: Many settings are configured automatically
\n
✅ Centralized management: Manage all tracking domains in one place
\n
✅ Status monitoring: Track domain status and configuration in real-time
\n

Tracking Domain URL Structure

For Tracking Codes (with Click Counting)

Initial Link: https://tracking.com/{link-code}\nAfter Click: https://yourcasino.com/register?tid={tracking-code}\n\n

{link-code}: The link code created in Back Office
\n
tid: Automatically generated tracking code (encrypted format) passed in redirect
\n

For Link Codes (Static Attribution)

https://tracking.com/?p={link-code}&campaign={campaign-id}&source={source}\n\n

p (required): Link code identifying the affiliate
\n
campaign (optional): Campaign identifier
\n
source (optional): Traffic source identifier
\n

Tracking Domains vs Cuttly Links

Recommendation

Use Tracking Domains for:
\n
- Production environments requiring click counting
  \n
- Server-to-server postbacks
  \n
\n
Use Cuttly Links for:
\n
- When domain block survival is important
  \n
- When click counting is not required
  \n
- Server-to-server postbacks are not needed
  \n
\n

Integration Steps

Step 1: Implement User Registration Endpoint

Step 2: Implement Financial Transaction Endpoint

Step 3: Implement Domain Rotation Notification

Support and Resources

API Documentation: See Customer Registration API and Financial Transaction API
\n
Contact: Reach out to the aggregator provider for:
\n
- Tracking code generation
  \n
- Tracking domain setup assistance
  \n
- API credentials and access
  \n
- Technical support
  \n
\n

Frequently Asked Questions

Q: How do I know if a tracking code is valid?

A: When you register a user with a tracking code, check the referrer field in the response. If it's not null, the tracking code was successfully resolved to an affiliate.

Q: Can I use both tracking codes and link codes?

A: Yes, but not in the same request. Choose one tracking method per registration. You can use different methods for different affiliates or campaigns.

Q: What happens if I send an invalid tracking code?

A: The user will be registered successfully, but the referrer field in the response will be null, indicating no affiliate attribution.

Q: How long does it take to set up a tracking domain?

A: The Back Office setup is quick, but DNS propagation in worst cases may take up to 24-48 hours. SSL certificates are usually handled automatically by the aggregator provider.

Q: Can I create tracking domains myself?

A: Yes, tracking domains can be easily created via the Back Office. Simply log in, navigate to the tracking domains section, and follow the creation process.

Q: Do I need technical knowledge to create a tracking domain?

A: No

Q: What's the difference between tracking codes and link codes?

Tracking Codes: Automatically generated unique codes per click, encrypted format, enable click counting, require tracking domains
\n
Link Codes: Static codes generated randomly in Back Office, can be used with Cuttly links, don't count clicks, can survive domain blocks
\n

Q: Can I use Cuttly links for postbacks?

A: No, Cuttly links cannot be used for server-to-server postbacks because they don't pass tracking parameters. You must use tracking domains for postbacks.

Q: How do I handle domain blocks with Cuttly links?

A: When your casino domain is blocked, notify the aggregator provider about the domain rotation via API.

Q: Do tracking codes count clicks?

A: Yes, tracking codes enable click counting. Clicks are counted automatically when users click the tracking link.

Q: Do link codes count clicks?

A: No, link codes do not count clicks. They only provide static attribution for user registration.

Postbacks

What are Postbacks?

Postbacks are server-to-server callbacks used for:

Registration tracking: Notifying external systems when a user successfully registers
\n
Transaction tracking: Notifying external systems about financial transactions (first deposits, redeposits)
\n

Postback Requirements

Must use Tracking Domains: Postbacks require tracking domains because they need to pass tracking parameters in server-to-server communication
\n
Cannot use Cuttly Links: Cuttly links do not work for postbacks because they don't pass tracking parameters through server-to-server calls
\n

Contact the aggregator provider for specific postback implementation details and requirements.

\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{username}"},{"key":"password","value":"{password}"}]},"isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"249e4541-76ab-46be-9cc8-79461da04dfe"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"requests":{},"exec":[""],"id":"2c8e3708-b46f-478b-aeb4-07f8deaa604c"}}],"_postman_id":"33842f32-77e6-4695-b800-7331205900bf"},{"name":"Bonus API","item":[{"name":"Aggregator API","item":[{"name":"Find Available Bonuses","id":"ff735f49-0e6f-44aa-9cbd-5de8c0a13051","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"available\": true,\n \"externalUserId\": \"ext_987654321\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/find-available-bonuses","description":"

Endpoint for Finding Available Bonuses

Endpoint

POST /external-casino-client/v1/bonus/find-available-bonuses

Description

This endpoint returns the internal sportsbook free-bet bonuses currently offered\nby the operator. Three usage modes are selected via the request body fields:

Mode 1 — All available bonuses (catalogue). available: true, externalUserId\nomitted. Returns all enabled, in-activity-window bonuses. The operator-side\n\"Show For Players\" visibility flag is ignored in this mode — the full catalogue\nis exposed so the partner can plan campaigns.
Mode 2 — Available bonuses for a specific player. available: true,\nexternalUserId set. Returns only the bonuses available for that player: per-player\nlimits, claim eligibility rules and the operator-side visibility flag are honoured,\nand bonuses already claimed/active for the player are excluded. If the external\nplayer is unknown to Sumstats, the system attempts to register them automatically\nbefore evaluating eligibility.
Mode 3 — Registration bonuses only. tag: \"REGISTRATION\" (with or without\navailable). Returns the subset of bonuses tagged for new-player registration flows.

The response is not paginated — the operator catalogue is bounded (typically tens to\nlow hundreds of enabled bonuses). Each bonus carries a polymorphic free-bet payload\n(bonusSize.__payloadKind = \"FreeBetSize\") describing the substantive offer; the\npartner is expected to discriminate on __payloadKind for nested polymorphic objects\n(criteria, freeBetUseType, bonusSize.amount).

\n
Scope. This integration is purpose-built for INTERNAL_FREE_BET bonuses on the\nsportsbook product (InternalFreeBetSportsbookCriteria payload). Other bonus types\n(CUSTOM, FIRST_DEPOSIT, EXTERNAL_FREE_BET, EXTERNAL_FREE_SPINS_WITH_WAGERING,\nINTERNAL_FREE_SPINS_WITH_WAGERING, CASHBACK) and non-sportsbook free-bet\ncriteria may exist in the operator catalogue but are out of scope for this contract — partners should filter the response to\nbonusType: \"INTERNAL_FREE_BET\" with\nbonusSize.rule.productRules[0].criteria.__payloadKind: \"InternalFreeBetSportsbookCriteria\"\nclient-side.
\n

Request Body Description

Object:

brandId (integer, required) - Brand id provided by Sumstats. Must match the brand\nencoded in the HTTP Basic credentials. Used together with Authorization for\ncredential lookup.
\n
brand (string, optional) - Deprecated alias for brandId. Accepted during the\nbrand migration window only — partners on the new contract must send brandId.
\n
available (boolean, optional) - When true activates Mode 1 or Mode 2 selection.\nWhen omitted, tag must be set, otherwise the request is rejected with\nBAD_REQUEST.
\n
externalUserId (string, optional) - External player id in the operator system.\nWhen set, switches the call to Mode 2 (per-player filtering). If the player is\nunknown to Sumstats, the system attempts to register them automatically.
\n
tag (string, optional) - When set, must be \"REGISTRATION\" (case-insensitive)\nand switches the call to Mode 3. Any other value is rejected with BAD_REQUEST.
\n

Response Body Description

Object:

bonuses (array of objects, required) - List of bonus objects matching the query.\nEmpty list when nothing matches. The partner-facing slim shape drops\ninternal/operational fields (descriptionTitle, descriptionBonusRules,\nfullTermsAndConditions, descriptionFiles, isShownForPlayers, bonusTags,\nshareLimitsId, eligibilityClaimRulesCompletionInfo, notSatisfiedMatchResults,\nsatisfiedMatchResults, operatorId, ruleIds, removedAt, updatedAt,\nplayerGroupIds, bonusOverridableFeatures).
\n
Each bonus object has the structure documented under Bonus Fields below.
\n

Bonus Fields

The slim partner-facing bonus shape. Field-by-field semantics:

id (string, required) - Bonus identifier in UUID v7 format. This is the\ncatalogue id of the bonus configuration, not a per-player id. Pass to\nclaim-bonus-for-player, activate-player-bonus, cancel-player-bonus. Stable\nacross partner calls — repeated find-available-bonuses requests return the same\nid for the same operator-configured bonus until the operator deletes the\nconfiguration.
\n
name (array of {locale, translate}, required) - Localised bonus names. Each\nentry binds a locale (BCP-47 / ICU locale code, e.g. en_US, de_DE) to\nthe human-readable bonus name in that locale. Partners should pick the entry\nmatching the player's locale; when no exact match exists, fall back to en_US or\nthe first entry. Bonuses are guaranteed to have at least one translation\n(typically en_US).
\n
bonusType (enum, required) - High-level bonus kind. For this integration's\ncontract, the relevant value is INTERNAL_FREE_BET. Drives which payload shapes\nappear inside bonusSize. Other types may appear in the catalogue but are out of\nscope — partners should filter the response to bonusType: \"INTERNAL_FREE_BET\"\nclient-side.
\n
status (enum, required) - Lifecycle status of the bonus on the operator side.\nPossible values:
\n
- NOT_STARTED - Created and saved but the activity window has not started yet.
- SCHEDULED - Inside the configured activity window but the bonus is scheduled to go active at a later point.
- ACTIVE - Enabled and inside the activity window. Only ACTIVE bonuses can be claimed.
- DISABLED - Operator switched the bonus off from the admin panel.
- EXPIRED - Activity window has passed.
- REMOVED - Operator deleted the bonus configuration. Catalogue audits only — not claimable.
\n
Only ACTIVE bonuses can be claimed — find-available-bonuses does not return\nnon-ACTIVE bonuses by default; the field is informational for catalogue audits.
\n
enabled (boolean, required) - false when the operator has explicitly disabled\nthe bonus from the admin panel. A bonus with status: ACTIVE and enabled: false\nis unavailable for new claims and will not appear in Mode 2 (per-player) responses.\nMode 1 (catalogue) responses include disabled bonuses for partner audit purposes.
\n
promotionCode (string, optional) - Operator-issued promotion code (e.g.\n\"500TRYFREEBET\", \"EPL100\"). When set, the bonus is gated by the code on the\nplayer-facing surface — players can only claim it through a promo-code flow.\nnull when the bonus is freely claimable. Partners using this integration claim\nby bonusId directly and bypass the promo-code gate, but the field is exposed\nso partners can mirror operator-side promo flows on their UI.
\n
activityTime (object, optional) - Activity window. null means always on\n(no time gate). The shape mirrors the internal ActivityTime record — at most\none of timePeriod / timeSchedule is populated:
\n
- timePeriod (object, optional) - Continuous activity window.
  \n
  - timeRange (object, required) - Half-open period.
    - from (long, optional) - Start of the window in epoch millis (UTC).\nnull means open-ended start.
    - to (long, optional) - End of the window in epoch millis (UTC).\nnull means open-ended end.
    \n
  - isShownBeforePeriod (boolean, required) - Whether the bonus is exposed\nto players before timeRange.from.
  - isShownAfterPeriod (boolean, required) - Whether the bonus is exposed\nafter timeRange.to.
  - shownBeforePeriodMinutes (long, optional) - How long before\ntimeRange.from the bonus becomes visible.
  - shownAfterPeriodMinutes (long, optional) - How long after\ntimeRange.to the bonus remains visible.
  \n
- timeSchedule (object, optional) - Recurring activity schedule.\nPolymorphic on __payloadKind:
  \n
  - HoursOfDayTimeSchedule — recurring hours-of-day periods (periods).
  - DaysOfWeekTimeSchedule — recurring per-day-of-week periods\n(periodsByDay).
  - DaysOfMonthTimeSchedule — recurring per-day-of-month periods\n(periodsByDay).
  \n
  null when activity is window-only.
  \n
\n
Outside the window the bonus is unclaimable (Sumstats responds with\nBONUS_NOT_AVAILABLE (303) on claim).
\n
timeForActivationInHours (integer, optional) - Hours after claim during which\nthe player must activate the bonus (i.e. how long the CLAIMED → IN_PROGRESS\ntransition is allowed). null = unlimited (the player bonus stays in CLAIMED\nuntil activation or manual cancel). Used by Sumstats to compute expiredOnClaimAt\non the resulting player bonus. Example: 168 means the player has seven days to\nactivate.
\n
currencies (array of strings, required) - Currencies the bonus supports\n(ISO 4217 codes — TRY, EUR, USD, …). The bonus can only be claimed by players\nwhose account currency is in this set. In Mode 2, only bonuses whose currencies\narray contains the player's currency are returned. Empty array indicates a\nmisconfiguration on the operator side.
\n
isAutoActivates (boolean, required) - When true, the bonus auto-activates on\nclaim — partners do not need to call activate-player-bonus. The\nclaim-bonus-for-player response carries status: \"IN_PROGRESS\" and a populated\nactivatedAt. When false, the partner must explicitly call activate-player-bonus\nwithin timeForActivationInHours hours, or the player bonus expires.
\n
bonusSize (object, required) - Substantive offer payload describing the\nfree-bet rule and amount. For INTERNAL_FREE_BET bonuses, bonusSize.__payloadKind\nis always \"FreeBetSize\". See FreeBetSize below.
\n
winSize (object, optional) - Cap on potential winnings. Always null for\nINTERNAL_FREE_BET bonuses — the substantive limits are encoded inside the\nfree-bet criteria (bonusSize.rule.productRules[].criteria.maxWinAllowed).
\n
wagering (object, optional) - Wagering rules. Always null for\nINTERNAL_FREE_BET bonuses — free bets do not have a turnover requirement; the\nfree bet either wins, loses, or expires per the criteria rules.
\n

`bonusSize` — FreeBetSize

For INTERNAL_FREE_BET bonuses, bonusSize.__payloadKind = \"FreeBetSize\". The\nFreeBetSize payload has two top-level fields:

rule (object, required) - The free-bet rule — defines per-product criteria,\nfree-bet use type, and validity. See FreeBetRule below.
\n
amount (object, optional) - Total monetary value handed to the player as a\nfree-bet balance when the bonus is activated. Polymorphic on __payloadKind. Two\npractical kinds for free bets:
\n
- MonetarySize - Fixed amount.
  \n
  - money (MoneyBag, required) - The free-bet balance. See MoneyBag below.
  \n
- PercentageSize - Percentage of a baseline (rare for free bets).
  \n
  - percentage (number, required) - Percentage value, e.g. 100.0 = 100%.
  - maxAmount (MoneyBag, optional) - Upper cap on the resulting balance.
  - minAmount (MoneyBag, optional) - Lower floor on the resulting balance.
  \n
\n

`bonusSize.rule` — FreeBetRule

Object:

productRules (array of FreeBetProductRule, required, length ≥ 1) - Per-product\nfree-bet criteria. For sportsbook free bets there is a single entry with\nproduct: \"SPORTS\".
\n
Each FreeBetProductRule has:
\n
- note (array of {locale, translate}, optional) - Operator-supplied note\ndescribing the rule, localised. null when no note was set.
- title (array of {locale, translate}, optional) - Operator-supplied title\nfor the rule, localised. null when no title was set.
- product (string, required) - For this integration's scope, always \"SPORTS\".
- criteria (object, required) - Per-product limit rules. Polymorphic on\n__payloadKind. For sportsbook free bets,\ncriteria.__payloadKind = \"InternalFreeBetSportsbookCriteria\". See\nInternalFreeBetSportsbookCriteria below.
\n
validityInHours (integer, required) - Lifetime of the activated bonus, in\nhours. 0 = unlimited (the bonus runs until the free-bet balance is exhausted,\nthe bet limit hits, or the operator cancels). Maximum supported value ≈ 1 month.\nUsed by Sumstats to compute expiredAt on the activated player bonus.
\n
note (array of {locale, translate}, optional) - Free-form operator note for\nthe rule as a whole, localised. null when no note was set.
\n
freeBetUseType (object, required) - How the free-bet money composes the\nplayer's stake. Polymorphic on __payloadKind. See FreeBetUseType union below.
\n

`criteria` — InternalFreeBetSportsbookCriteria

For sportsbook free bets, criteria.__payloadKind = \"InternalFreeBetSportsbookCriteria\".\nTop-level fields:

filters (array of InternalFreeBetSportsbookFilter, required) - Filter list\nnarrowing where the free bet may be staked. An empty filter list means \"no\nnarrowing\" (the free bet may be staked on any sportsbook event). Multiple filters\nare OR'd: a stake is allowed if at least one filter accepts it. See\nInternalFreeBetSportsbookFilter below.
\n
minValue (MoneyBag, optional) - Minimum bet stake required. null = no\nminimum. Stakes below this are rejected by the bet placement engine.
\n
maxValue (MoneyBag, optional) - Maximum bet stake allowed. null = no\nmaximum. Stakes above this are rejected.
\n
maxWinAllowed (MoneyBag, optional) - Per-bet win cap. When set, winnings on a\nsingle free-bet stake are capped at this amount. null = no cap (free bet pays\nout the full computed winnings).
\n
maxAmountOfBets (integer, optional) - Maximum number of bets the player may\nplace using the free-bet balance. null = unlimited (the bonus runs until the\nfree-bet balance is exhausted or expires). Once the limit is hit, the bonus\ntransitions to COMPLETED automatically.
\n

`filters[]` — InternalFreeBetSportsbookFilter

Narrows the events on which the free bet may be staked. All scalar fields are\nnullable; null means \"no restriction on this dimension\". The filter accepts a\nstake when every set field matches the stake's event metadata:

sportId (string, optional) - Restrict to a specific sport (UUID, operator-defined\n— e.g. football, basketball, tennis). null = any sport.
\n
categoryId (string, optional) - Restrict to a category — typically a country /\nregion inside a sport (UUID, operator-defined — e.g. England, Germany, ATP Tour).\nnull = any category.
\n
tournamentId (string, optional) - Restrict to a tournament inside a category\n(UUID, operator-defined — e.g. Premier League, Bundesliga, Wimbledon). null = any\ntournament.
\n
eventId (string, optional) - Restrict to a single event / match (UUID,\noperator-defined). null = any event.
\n
markets (array of MarketType, required) - Allow-listed market identifiers\nfrom the generated MarketType enum (lowercase enum names from the SportsbookSchema).\nExamples: score_1x2, score_ou, score_dc, score_both_to_score_yes_no,\nscore_ht_ft, score_winning_margin, score_exact_number, corner_1x2,\nyellow_card_1x2. Empty array means any market.
\n
betRule (object, optional) - Bet-shape restrictions. All betRule fields\nare nullable; null (or empty for set-typed fields) means \"no restriction on this\ndimension\". A stake is accepted when every set field matches.
\n
- betTypes (array of BetHashType, required) - Allowed bet types from the\nBetHashType enum. The JSON wire form is lowercase (set by Jackson\n@JsonProperty on the enum). Possible values:
  \n
  - single - A single selection bet.
  - parlay - Accumulator bet (multiple selections combined; all must win).\nThe accumulator* betRule fields below apply only to this bet type.
  - system - System bet (combinations of accumulators).
  \n
  Empty array means any bet type.
  \n
- live (boolean, optional) - true = live betting only, false = pre-match\nonly, null = both allowed.
  \n
- singleMinOdd (number, optional) - Minimum odd for single bets. Ignored\nfor non-single bet types. Applied to the bet's single odd at placement time.
  \n
- accumulatorTotalOdds (number, optional) - Minimum total odds for a parlay\n(the product of all selection odds). Ignored for non-parlay bet types.
  \n
- accumulatorAtLeastOdd (number, optional) - At least one selection in the\nparlay must have an odd ≥ this value. Combined with\naccumulatorMinOddPerSelection for fine-grained control.
  \n
- accumulatorMinNumberOfSelections (integer, optional) - Minimum number of\nlegs (selections) in the parlay.
  \n
- accumulatorMaxNumberOfSelections (integer, optional) - Maximum number of\nlegs in the parlay.
  \n
- accumulatorMinOddPerSelection (number, optional) - Minimum odd that\nevery selection in the parlay must meet.
  \n
\n

`freeBetUseType` — FreeBetUseType union

Discriminated by __payloadKind. Two concrete kinds:

FreeBetAllBalanceUseType - The stake must consist 100% of free-bet money. Real\nmoney cannot be mixed in.
\n
- isMustBeStakedAtOnce (boolean, required) - When true, the entire free-bet\nbalance must be wagered in a single bet (the player cannot split the\nbalance across multiple bets). When false, the player may place multiple bets\nuntil the balance is exhausted, subject to maxAmountOfBets.
\n
FreeBetPartialBalanceUseType - The stake may mix free-bet money with real\nmoney. Each bet's free-bet portion is bounded.
\n
- minValue (MoneyBag, optional) - Minimum free-bet amount per bet. null =\nno minimum.
- maxValue (MoneyBag, optional) - Maximum free-bet amount per bet. null =\nno maximum.
\n

`MoneyBag`

Shape — examples in this document use only the system amount in a single currency:

{\n  \"system\": { \"amount\": \"50000\", \"currency\": \"TRY\" },\n  \"additional\": []\n}\n

system ({amount, currency}, required) - The amount in the bonus's currency.\nThe amount is a string (decimal with no implied scaling — the bonus engine\nstores monetary values in raw integer minor-unit form, e.g. \"50000\" = 500.00 TRY).
additional (array, required) - Per-currency overrides for cross-currency\nbonuses. When the player's currency matches an entry's currency, the entry's\namount is used directly; otherwise the system amount is converted via the\noperator's currency-pair rates. Single-currency bonuses (the common case) emit\nan empty array, as in all examples in this document.

Request Examples

Mode 1 — Catalogue lookup

{\n  \"brandId\": 0,\n  \"available\": true\n}\n

Mode 2 — Available bonuses for a specific player

{\n  \"brandId\": 0,\n  \"available\": true,\n  \"externalUserId\": \"ext_987654321\"\n}\n

Mode 3 — Registration bonuses only

{\n  \"brandId\": 0,\n  \"tag\": \"REGISTRATION\"\n}\n

Response Examples

Successful Response (200 OK) — Internal Free Bet (minimal sportsbook)

The faithful \"500 TRY FREE BET\" bonus from the legacy Bonus API documentation.\nDemonstrates the unrestricted shape: filters[0] has every dimension null /\nempty (any sport, any category, any tournament, any event, any market, any bet type,\nany odds, no selection limits). freeBetUseType is FreeBetAllBalanceUseType with\nisMustBeStakedAtOnce: true, meaning the entire 500 TRY balance must be wagered in a\nsingle bet.

{\n    \"bonuses\": [\n        {\n            \"id\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n            \"name\": [\n                {\n                    \"locale\": \"en_US\",\n                    \"translate\": \"500 TRY FREE BET\"\n                }\n            ],\n            \"bonusType\": \"INTERNAL_FREE_BET\",\n            \"status\": \"ACTIVE\",\n            \"enabled\": true,\n            \"promotionCode\": \"500TRYFREEBET\",\n            \"activityTime\": {\n                \"timePeriod\": {\n                    \"timeRange\": {\n                        \"from\": 1761721205143,\n                        \"to\": 1764313205143\n                    },\n                    \"isShownBeforePeriod\": true,\n                    \"isShownAfterPeriod\": false,\n                    \"shownBeforePeriodMinutes\": null,\n                    \"shownAfterPeriodMinutes\": null\n                },\n                \"timeSchedule\": null\n            },\n            \"timeForActivationInHours\": 168,\n            \"currencies\": [\n                \"TRY\",\n                \"EUR\"\n            ],\n            \"isAutoActivates\": true,\n            \"bonusSize\": {\n                \"__payloadKind\": \"FreeBetSize\",\n                \"rule\": {\n                    \"productRules\": [\n                        {\n                            \"note\": null,\n                            \"title\": null,\n                            \"criteria\": {\n                                \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n                                \"filters\": [\n                                    {\n                                        \"sportId\": null,\n                                        \"categoryId\": null,\n                                        \"tournamentId\": null,\n                                        \"eventId\": null,\n                                        \"markets\": [],\n                                        \"betRule\": {\n                                            \"betTypes\": [],\n                                            \"live\": null,\n                                            \"singleMinOdd\": null,\n                                            \"accumulatorTotalOdds\": null,\n                                            \"accumulatorAtLeastOdd\": null,\n                                            \"accumulatorMinNumberOfSelections\": null,\n                                            \"accumulatorMinOddPerSelection\": null,\n                                            \"accumulatorMaxNumberOfSelections\": null\n                                        }\n                                    }\n                                ],\n                                \"minValue\": {\n                                    \"system\": {\n                                        \"amount\": \"50000\",\n                                        \"currency\": \"TRY\"\n                                    },\n                                    \"additional\": []\n                                },\n                                \"maxValue\": {\n                                    \"system\": {\n                                        \"amount\": \"50000\",\n                                        \"currency\": \"TRY\"\n                                    },\n                                    \"additional\": []\n                                },\n                                \"maxWinAllowed\": null,\n                                \"maxAmountOfBets\": null\n                            },\n                            \"product\": \"SPORTS\"\n                        }\n                    ],\n                    \"validityInHours\": 168,\n                    \"note\": null,\n                    \"freeBetUseType\": {\n                        \"__payloadKind\": \"FreeBetAllBalanceUseType\",\n                        \"isMustBeStakedAtOnce\": true\n                    }\n                },\n                \"amount\": {\n                    \"__payloadKind\": \"MonetarySize\",\n                    \"money\": {\n                        \"system\": {\n                            \"amount\": \"50000\",\n                            \"currency\": \"TRY\"\n                        },\n                        \"additional\": []\n                    }\n                }\n            },\n            \"winSize\": null,\n            \"wagering\": null\n        }\n    ]\n}\n

Successful Response (200 OK) — Internal Free Bet (populated sportsbook)

A 100 TRY free bet for Premier League pre-match singles and parlays.\nDemonstrates every populated dimension using real SportsbookSchema values:

Sport / category / tournament gating: sportId (Football),\ncategoryId (England), tournamentId (Premier League).
Three real MarketType values allow-listed:\n[\"score_1x2\", \"score_ou\", \"score_both_to_score_yes_no\"].
betTypes: [\"single\", \"parlay\"] — uses real BetHashType JSON values\n(lowercase via Jackson @JsonProperty).
live: false — pre-match only.
single bets must have an odd ≥ 1.5.
parlay bets must have total odds ≥ 3.0, between 3 and 10 selections, every\nselection at min odd 1.2, with at least one selection at min odd 1.3.
Stake band 25 TRY ≤ stake ≤ 100 TRY, max win 1000 TRY, max 5 bets.
72-hour validity once activated.
freeBetUseType is FreeBetPartialBalanceUseType with the same 25-100 TRY bounds\nper bet — meaning the player may combine free-bet money with real money on the\nsame stake.
isAutoActivates: false — the partner must call activate-player-bonus after\nclaim.

{\n    \"bonuses\": [\n        {\n            \"id\": \"0192bbb0-1234-7aef-9688-aabbccdd0011\",\n            \"name\": [\n                {\n                    \"locale\": \"en_US\",\n                    \"translate\": \"Premier League Free Bet \\u2014 100 TRY\"\n                }\n            ],\n            \"bonusType\": \"INTERNAL_FREE_BET\",\n            \"status\": \"ACTIVE\",\n            \"enabled\": true,\n            \"promotionCode\": \"EPL100\",\n            \"activityTime\": {\n                \"timePeriod\": {\n                    \"timeRange\": {\n                        \"from\": 1761721205143,\n                        \"to\": 1764313205143\n                    },\n                    \"isShownBeforePeriod\": true,\n                    \"isShownAfterPeriod\": false,\n                    \"shownBeforePeriodMinutes\": null,\n                    \"shownAfterPeriodMinutes\": null\n                },\n                \"timeSchedule\": null\n            },\n            \"timeForActivationInHours\": 72,\n            \"currencies\": [\n                \"TRY\"\n            ],\n            \"isAutoActivates\": false,\n            \"bonusSize\": {\n                \"__payloadKind\": \"FreeBetSize\",\n                \"rule\": {\n                    \"productRules\": [\n                        {\n                            \"note\": [\n                                {\n                                    \"locale\": \"en_US\",\n                                    \"translate\": \"Premier League pre-match singles and parlays only.\"\n                                }\n                            ],\n                            \"title\": [\n                                {\n                                    \"locale\": \"en_US\",\n                                    \"translate\": \"Premier League Free Bet\"\n                                }\n                            ],\n                            \"criteria\": {\n                                \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n                                \"filters\": [\n                                    {\n                                        \"sportId\": \"0192aaaa-1111-7000-9000-000000000001\",\n                                        \"categoryId\": \"0192aaaa-1111-7000-9000-000000000002\",\n                                        \"tournamentId\": \"0192aaaa-1111-7000-9000-000000000003\",\n                                        \"eventId\": null,\n                                        \"markets\": [\n                                            \"score_1x2\",\n                                            \"score_ou\",\n                                            \"score_both_to_score_yes_no\"\n                                        ],\n                                        \"betRule\": {\n                                            \"betTypes\": [\n                                                \"single\",\n                                                \"parlay\"\n                                            ],\n                                            \"live\": false,\n                                            \"singleMinOdd\": 1.5,\n                                            \"accumulatorTotalOdds\": 3.0,\n                                            \"accumulatorAtLeastOdd\": 1.3,\n                                            \"accumulatorMinNumberOfSelections\": 3,\n                                            \"accumulatorMinOddPerSelection\": 1.2,\n                                            \"accumulatorMaxNumberOfSelections\": 10\n                                        }\n                                    }\n                                ],\n                                \"minValue\": {\n                                    \"system\": {\n                                        \"amount\": \"2500\",\n                                        \"currency\": \"TRY\"\n                                    },\n                                    \"additional\": []\n                                },\n                                \"maxValue\": {\n                                    \"system\": {\n                                        \"amount\": \"10000\",\n                                        \"currency\": \"TRY\"\n                                    },\n                                    \"additional\": []\n                                },\n                                \"maxWinAllowed\": {\n                                    \"system\": {\n                                        \"amount\": \"100000\",\n                                        \"currency\": \"TRY\"\n                                    },\n                                    \"additional\": []\n                                },\n                                \"maxAmountOfBets\": 5\n                            },\n                            \"product\": \"SPORTS\"\n                        }\n                    ],\n                    \"validityInHours\": 72,\n                    \"note\": [\n                        {\n                            \"locale\": \"en_US\",\n                            \"translate\": \"Pre-match Premier League free bet \\u2014 5 bets max within 72h.\"\n                        }\n                    ],\n                    \"freeBetUseType\": {\n                        \"__payloadKind\": \"FreeBetPartialBalanceUseType\",\n                        \"minValue\": {\n                            \"system\": {\n                                \"amount\": \"2500\",\n                                \"currency\": \"TRY\"\n                            },\n                            \"additional\": []\n                        },\n                        \"maxValue\": {\n                            \"system\": {\n                                \"amount\": \"10000\",\n                                \"currency\": \"TRY\"\n                            },\n                            \"additional\": []\n                        }\n                    }\n                },\n                \"amount\": {\n                    \"__payloadKind\": \"MonetarySize\",\n                    \"money\": {\n                        \"system\": {\n                            \"amount\": \"10000\",\n                            \"currency\": \"TRY\"\n                        },\n                        \"additional\": []\n                    }\n                }\n            },\n            \"winSize\": null,\n            \"wagering\": null\n        }\n    ]\n}\n

Successful Response (200 OK) — Empty result

{\n    \"bonuses\": []\n}\n

Error Responses

400 Bad Request - Request Validation Error

Occurs when request validation fails. Common causes:

Both available and tag omitted.
tag provided but not equal to \"REGISTRATION\" (case-insensitive).
Malformed brandId (non-integer) or missing Authorization.

Example Error Response:

{\n    \"errorCode\": 3,\n    \"errorMessage\": \"either 'available=true' or 'tag=REGISTRATION' must be supplied\"\n}\n

400 Bad Request - Deserialization Error

Occurs when the JSON body cannot be parsed (truncated, invalid escapes, etc.).

Example Error Response:

{\n    \"errorCode\": 4,\n    \"errorMessage\": \"Failed to deserialize request body\"\n}\n

400 Bad Request - Invalid User

Occurs in Mode 2 when the externalUserId cannot be resolved or registered\nautomatically.

Example Error Response:

{\n    \"errorCode\": 109,\n    \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n

401 Unauthorized - Invalid Credentials

Occurs when Authorization is missing, malformed, or does not match a known brand\ncredential.

Example Error Response:

{\n    \"errorCode\": 2,\n    \"errorMessage\": \"Invalid credentials\"\n}\n

403 Forbidden - IP not whitelisted

Occurs when the request originates from an IP not present in the per-brand allow\nlist. Returned by the gateway, before the application is hit.

Example Error Response (HTML body, status 403):

IP <client-ip> is not presented in white list\n

500 Internal Server Error - Unknown Error

Occurs when an unexpected server error happens.

Example Error Response:

{\n    \"errorCode\": 1,\n    \"errorMessage\": \"Unknown error\"\n}\n

Important Notes

Sportsbook free-bet only. This integration is purpose-built for\nINTERNAL_FREE_BET bonuses on the sportsbook product\n(InternalFreeBetSportsbookCriteria payload). winSize is always null,\nwagering is always null. All limits and rules are encoded inside\nbonusSize.rule.productRules[].criteria and bonusSize.rule.freeBetUseType. Other\nbonusType values and non-sportsbook free-bet criteria may appear in the catalogue\nand should be filtered out client-side.
\n
Real schema values. betRule.betTypes uses the BetHashType enum with\nlowercase JSON values (\"single\", \"parlay\", \"system\") — the parlay value is\nthe schema name for accumulator bets. markets uses the MarketType enum\nfrom the generated SportsbookSchema (lowercase names like score_1x2, score_ou,\nscore_both_to_score_yes_no).
\n
Visibility flag handling. In Mode 1 (catalogue) the operator-side\n\"Show For Players\" visibility flag is ignored — partners see the full enabled\ncatalogue. In Mode 2 (per-player) the flag is honoured: bonuses with\nisShownForPlayers: false are hidden.
\n
Mode 2 player registration side-effect. When externalUserId is unknown to\nSumstats, the system attempts to register the player automatically before\nevaluating eligibility. Subsequent calls for the same externalUserId skip\nthis step. If automatic registration fails, the request fails with\nINVALID_USER (109).
\n
Polymorphic __payloadKind discriminator. All polymorphic objects\n(bonusSize, criteria, freeBetUseType, bonusSize.amount) carry a\n__payloadKind field containing the concrete payload kind. Partners must\ndiscriminate on this field — adding new payload kinds in the future is the\nstandard evolution path.
\n
MoneyBag.system semantics. system carries the canonical amount in the\noperator's accounting currency. When the player's currency matches an entry in\nadditional, that override is used directly; otherwise the system entry is\nconverted via the operator's currency-pair rates. Partners should prefer the\nadditional entry matching the player's currency for display.
\n
Currencies and bonus selection. The currencies array on the bonus is the\nset of currencies the bonus supports. In Mode 2, only bonuses whose currencies\narray contains the player's currency are returned.
\n
Empty filter list semantics. criteria.filters is an array — an empty\narray means \"no narrowing\": the free bet may be staked on any sportsbook event.\nA non-empty filter list is OR'd: a stake is allowed when at least one filter\naccepts it.
\n
Empty-vs-null in betRule. betRule.betTypes: [] and betRule.markets: []\nmean \"any\" (no restriction); betRule.live: null means \"any live mode\"; numeric /\ninteger fields use null for \"no restriction\". The semantics differ — empty array\non betTypes / markets, null on the rest.
\n
isAutoActivates impact on the claim flow. When isAutoActivates: true,\ncalling claim-bonus-for-player immediately moves the player bonus to\nIN_PROGRESS. When false, the partner must call activate-player-bonus within\ntimeForActivationInHours hours.
\n

Authentication

This endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.

Authorization: Basic base64(username:password)\nContent-Type: application/json\n

Use the brandId body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request brandId matches.

\n","urlObject":{"path":["external-casino-client","v1","bonus","find-available-bonuses"],"host":["{apiUrl}"],"query":[],"variable":[]}},"response":[{"id":"317f74c6-9496-4ffd-90d1-8c8911bec77b","name":"success — Internal Free Bet (minimal sportsbook)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"available\": true,\n \"externalUserId\": \"ext_987654321\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/find-available-bonuses","description":"# Endpoint for Finding Available Bonuses\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/find-available-bonuses`\n\n## Description\n\nThis endpoint returns the **internal sportsbook free-bet bonuses** currently offered\nby the operator. Three usage modes are selected via the request body fields:\n\n- **Mode 1 — All available bonuses (catalogue).** `available: true`, `externalUserId`\n omitted. Returns all enabled, in-activity-window bonuses. The operator-side\n `\"Show For Players\"` visibility flag is **ignored** in this mode — the full catalogue\n is exposed so the partner can plan campaigns.\n- **Mode 2 — Available bonuses for a specific player.** `available: true`,\n `externalUserId` set. Returns only the bonuses available *for that player*: per-player\n limits, claim eligibility rules and the operator-side visibility flag are honoured,\n and bonuses already claimed/active for the player are excluded. If the external\n player is unknown to Sumstats, the system attempts to register them automatically\n before evaluating eligibility.\n- **Mode 3 — Registration bonuses only.** `tag: \"REGISTRATION\"` (with or without\n `available`). Returns the subset of bonuses tagged for new-player registration flows.\n\nThe response is **not paginated** — the operator catalogue is bounded (typically tens to\nlow hundreds of enabled bonuses). Each bonus carries a polymorphic free-bet payload\n(`bonusSize.__payloadKind = \"FreeBetSize\"`) describing the substantive offer; the\npartner is expected to discriminate on `__payloadKind` for nested polymorphic objects\n(`criteria`, `freeBetUseType`, `bonusSize.amount`).\n\n> **Scope.** This integration is purpose-built for `INTERNAL_FREE_BET` bonuses on the\n> sportsbook product (`InternalFreeBetSportsbookCriteria` payload). Other bonus types\n> (`CUSTOM`, `FIRST_DEPOSIT`, `EXTERNAL_FREE_BET`, `EXTERNAL_FREE_SPINS_WITH_WAGERING`,\n> `INTERNAL_FREE_SPINS_WITH_WAGERING`, `CASHBACK`) and non-sportsbook free-bet\n> criteria may exist in the operator catalogue but are out of scope for this contract — partners should filter the response to\n> `bonusType: \"INTERNAL_FREE_BET\"` with\n> `bonusSize.rule.productRules[0].criteria.__payloadKind: \"InternalFreeBetSportsbookCriteria\"`\n> client-side.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the brand\n encoded in the HTTP Basic credentials. Used together with `Authorization` for\n credential lookup.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only — partners on the new contract must send `brandId`.\n\n- **available** (boolean, optional) - When `true` activates Mode 1 or Mode 2 selection.\n When omitted, `tag` must be set, otherwise the request is rejected with\n `BAD_REQUEST`.\n\n- **externalUserId** (string, optional) - External player id in the operator system.\n When set, switches the call to Mode 2 (per-player filtering). If the player is\n unknown to Sumstats, the system attempts to register them automatically.\n\n- **tag** (string, optional) - When set, must be `\"REGISTRATION\"` (case-insensitive)\n and switches the call to Mode 3. Any other value is rejected with `BAD_REQUEST`.\n\n## Response Body Description\n\n**Object:**\n\n- **bonuses** (array of objects, required) - List of bonus objects matching the query.\n Empty list when nothing matches. The partner-facing slim shape drops\n internal/operational fields (`descriptionTitle`, `descriptionBonusRules`,\n `fullTermsAndConditions`, `descriptionFiles`, `isShownForPlayers`, `bonusTags`,\n `shareLimitsId`, `eligibilityClaimRulesCompletionInfo`, `notSatisfiedMatchResults`,\n `satisfiedMatchResults`, `operatorId`, `ruleIds`, `removedAt`, `updatedAt`,\n `playerGroupIds`, `bonusOverridableFeatures`).\n\n Each bonus object has the structure documented under **Bonus Fields** below.\n\n### Bonus Fields\n\nThe slim partner-facing bonus shape. Field-by-field semantics:\n\n- **id** (string, required) - Bonus identifier in **UUID v7** format. This is the\n *catalogue* id of the bonus configuration, not a per-player id. Pass to\n `claim-bonus-for-player`, `activate-player-bonus`, `cancel-player-bonus`. Stable\n across partner calls — repeated `find-available-bonuses` requests return the same\n `id` for the same operator-configured bonus until the operator deletes the\n configuration.\n\n- **name** (array of `{locale, translate}`, required) - Localised bonus names. Each\n entry binds a `locale` (BCP-47 / ICU locale code, e.g. `en_US`, `de_DE`) to\n the human-readable bonus name in that locale. Partners should pick the entry\n matching the player's locale; when no exact match exists, fall back to `en_US` or\n the first entry. Bonuses are guaranteed to have **at least one** translation\n (typically `en_US`).\n\n- **bonusType** (enum, required) - High-level bonus kind. **For this integration's\n contract, the relevant value is `INTERNAL_FREE_BET`.** Drives which payload shapes\n appear inside `bonusSize`. Other types may appear in the catalogue but are out of\n scope — partners should filter the response to `bonusType: \"INTERNAL_FREE_BET\"`\n client-side.\n\n- **status** (enum, required) - Lifecycle status of the bonus on the operator side.\n Possible values:\n\n - `NOT_STARTED` - Created and saved but the activity window has not started yet.\n - `SCHEDULED` - Inside the configured activity window but the bonus is scheduled to go active at a later point.\n - `ACTIVE` - Enabled and inside the activity window. Only `ACTIVE` bonuses can be claimed.\n - `DISABLED` - Operator switched the bonus off from the admin panel.\n - `EXPIRED` - Activity window has passed.\n - `REMOVED` - Operator deleted the bonus configuration. Catalogue audits only — not claimable.\n\n Only `ACTIVE` bonuses can be claimed — `find-available-bonuses` does not return\n non-`ACTIVE` bonuses by default; the field is informational for catalogue audits.\n\n- **enabled** (boolean, required) - `false` when the operator has explicitly disabled\n the bonus from the admin panel. A bonus with `status: ACTIVE` and `enabled: false`\n is unavailable for new claims and will not appear in Mode 2 (per-player) responses.\n Mode 1 (catalogue) responses include disabled bonuses for partner audit purposes.\n\n- **promotionCode** (string, optional) - Operator-issued promotion code (e.g.\n `\"500TRYFREEBET\"`, `\"EPL100\"`). When set, the bonus is gated by the code on the\n player-facing surface — players can only claim it through a promo-code flow.\n `null` when the bonus is freely claimable. **Partners using this integration claim\n by `bonusId` directly and bypass the promo-code gate**, but the field is exposed\n so partners can mirror operator-side promo flows on their UI.\n\n- **activityTime** (object, optional) - Activity window. `null` means always on\n (no time gate). The shape mirrors the internal `ActivityTime` record — at most\n one of `timePeriod` / `timeSchedule` is populated:\n\n - **timePeriod** (object, optional) - Continuous activity window.\n - **timeRange** (object, required) - Half-open period.\n - **from** (long, optional) - Start of the window in **epoch millis (UTC)**.\n `null` means open-ended start.\n - **to** (long, optional) - End of the window in **epoch millis (UTC)**.\n `null` means open-ended end.\n - **isShownBeforePeriod** (boolean, required) - Whether the bonus is exposed\n to players before `timeRange.from`.\n - **isShownAfterPeriod** (boolean, required) - Whether the bonus is exposed\n after `timeRange.to`.\n - **shownBeforePeriodMinutes** (long, optional) - How long before\n `timeRange.from` the bonus becomes visible.\n - **shownAfterPeriodMinutes** (long, optional) - How long after\n `timeRange.to` the bonus remains visible.\n - **timeSchedule** (object, optional) - Recurring activity schedule.\n Polymorphic on `__payloadKind`:\n - `HoursOfDayTimeSchedule` — recurring hours-of-day periods (`periods`).\n - `DaysOfWeekTimeSchedule` — recurring per-day-of-week periods\n (`periodsByDay`).\n - `DaysOfMonthTimeSchedule` — recurring per-day-of-month periods\n (`periodsByDay`).\n\n `null` when activity is window-only.\n\n Outside the window the bonus is unclaimable (Sumstats responds with\n `BONUS_NOT_AVAILABLE` (303) on claim).\n\n- **timeForActivationInHours** (integer, optional) - Hours after claim during which\n the player must activate the bonus (i.e. how long the `CLAIMED → IN_PROGRESS`\n transition is allowed). `null` = unlimited (the player bonus stays in `CLAIMED`\n until activation or manual cancel). Used by Sumstats to compute `expiredOnClaimAt`\n on the resulting player bonus. Example: `168` means the player has seven days to\n activate.\n\n- **currencies** (array of strings, required) - Currencies the bonus supports\n (ISO 4217 codes — `TRY`, `EUR`, `USD`, …). The bonus can only be claimed by players\n whose account currency is in this set. In Mode 2, only bonuses whose `currencies`\n array contains the player's currency are returned. Empty array indicates a\n misconfiguration on the operator side.\n\n- **isAutoActivates** (boolean, required) - When `true`, the bonus auto-activates on\n claim — partners do **not** need to call `activate-player-bonus`. The\n `claim-bonus-for-player` response carries `status: \"IN_PROGRESS\"` and a populated\n `activatedAt`. When `false`, the partner must explicitly call `activate-player-bonus`\n within `timeForActivationInHours` hours, or the player bonus expires.\n\n- **bonusSize** (object, required) - Substantive offer payload describing the\n free-bet rule and amount. **For `INTERNAL_FREE_BET` bonuses, `bonusSize.__payloadKind`\n is always `\"FreeBetSize\"`.** See **FreeBetSize** below.\n\n- **winSize** (object, optional) - Cap on potential winnings. **Always `null` for\n `INTERNAL_FREE_BET` bonuses** — the substantive limits are encoded inside the\n free-bet criteria (`bonusSize.rule.productRules[].criteria.maxWinAllowed`).\n\n- **wagering** (object, optional) - Wagering rules. **Always `null` for\n `INTERNAL_FREE_BET` bonuses** — free bets do not have a turnover requirement; the\n free bet either wins, loses, or expires per the criteria rules.\n\n### `bonusSize` — FreeBetSize\n\nFor `INTERNAL_FREE_BET` bonuses, `bonusSize.__payloadKind = \"FreeBetSize\"`. The\n`FreeBetSize` payload has two top-level fields:\n\n- **rule** (object, required) - The free-bet rule — defines per-product criteria,\n free-bet use type, and validity. See **FreeBetRule** below.\n- **amount** (object, optional) - Total monetary value handed to the player as a\n free-bet balance when the bonus is activated. Polymorphic on `__payloadKind`. Two\n practical kinds for free bets:\n\n - **MonetarySize** - Fixed amount.\n\n - **money** (MoneyBag, required) - The free-bet balance. See **MoneyBag** below.\n\n - **PercentageSize** - Percentage of a baseline (rare for free bets).\n\n - **percentage** (number, required) - Percentage value, e.g. `100.0` = 100%.\n - **maxAmount** (MoneyBag, optional) - Upper cap on the resulting balance.\n - **minAmount** (MoneyBag, optional) - Lower floor on the resulting balance.\n\n### `bonusSize.rule` — FreeBetRule\n\n**Object:**\n\n- **productRules** (array of `FreeBetProductRule`, required, length ≥ 1) - Per-product\n free-bet criteria. **For sportsbook free bets there is a single entry with\n `product: \"SPORTS\"`.**\n\n Each `FreeBetProductRule` has:\n\n - **note** (array of `{locale, translate}`, optional) - Operator-supplied note\n describing the rule, localised. `null` when no note was set.\n - **title** (array of `{locale, translate}`, optional) - Operator-supplied title\n for the rule, localised. `null` when no title was set.\n - **product** (string, required) - For this integration's scope, always `\"SPORTS\"`.\n - **criteria** (object, required) - Per-product limit rules. Polymorphic on\n `__payloadKind`. **For sportsbook free bets,\n `criteria.__payloadKind = \"InternalFreeBetSportsbookCriteria\"`.** See\n **InternalFreeBetSportsbookCriteria** below.\n\n- **validityInHours** (integer, required) - Lifetime of the *activated* bonus, in\n hours. `0` = unlimited (the bonus runs until the free-bet balance is exhausted,\n the bet limit hits, or the operator cancels). Maximum supported value ≈ 1 month.\n Used by Sumstats to compute `expiredAt` on the activated player bonus.\n\n- **note** (array of `{locale, translate}`, optional) - Free-form operator note for\n the rule as a whole, localised. `null` when no note was set.\n\n- **freeBetUseType** (object, required) - How the free-bet money composes the\n player's stake. Polymorphic on `__payloadKind`. See **FreeBetUseType union** below.\n\n### `criteria` — InternalFreeBetSportsbookCriteria\n\nFor sportsbook free bets, `criteria.__payloadKind = \"InternalFreeBetSportsbookCriteria\"`.\nTop-level fields:\n\n- **filters** (array of `InternalFreeBetSportsbookFilter`, required) - Filter list\n narrowing where the free bet may be staked. **An empty filter list means \"no\n narrowing\"** (the free bet may be staked on any sportsbook event). Multiple filters\n are OR'd: a stake is allowed if **at least one** filter accepts it. See\n **InternalFreeBetSportsbookFilter** below.\n\n- **minValue** (MoneyBag, optional) - Minimum bet stake required. `null` = no\n minimum. Stakes below this are rejected by the bet placement engine.\n\n- **maxValue** (MoneyBag, optional) - Maximum bet stake allowed. `null` = no\n maximum. Stakes above this are rejected.\n\n- **maxWinAllowed** (MoneyBag, optional) - Per-bet win cap. When set, winnings on a\n single free-bet stake are capped at this amount. `null` = no cap (free bet pays\n out the full computed winnings).\n\n- **maxAmountOfBets** (integer, optional) - Maximum number of bets the player may\n place using the free-bet balance. `null` = unlimited (the bonus runs until the\n free-bet balance is exhausted or expires). Once the limit is hit, the bonus\n transitions to `COMPLETED` automatically.\n\n#### `filters[]` — InternalFreeBetSportsbookFilter\n\nNarrows the events on which the free bet may be staked. **All scalar fields are\nnullable; `null` means \"no restriction on this dimension\".** The filter accepts a\nstake when *every* set field matches the stake's event metadata:\n\n- **sportId** (string, optional) - Restrict to a specific sport (UUID, operator-defined\n — e.g. football, basketball, tennis). `null` = any sport.\n\n- **categoryId** (string, optional) - Restrict to a category — typically a country /\n region inside a sport (UUID, operator-defined — e.g. England, Germany, ATP Tour).\n `null` = any category.\n\n- **tournamentId** (string, optional) - Restrict to a tournament inside a category\n (UUID, operator-defined — e.g. Premier League, Bundesliga, Wimbledon). `null` = any\n tournament.\n\n- **eventId** (string, optional) - Restrict to a single event / match (UUID,\n operator-defined). `null` = any event.\n\n- **markets** (array of `MarketType`, required) - Allow-listed market identifiers\n from the generated `MarketType` enum (lowercase enum names from the SportsbookSchema).\n Examples: `score_1x2`, `score_ou`, `score_dc`, `score_both_to_score_yes_no`,\n `score_ht_ft`, `score_winning_margin`, `score_exact_number`, `corner_1x2`,\n `yellow_card_1x2`. **Empty array means any market.**\n\n- **betRule** (object, optional) - Bet-shape restrictions. **All `betRule` fields\n are nullable; `null` (or empty for set-typed fields) means \"no restriction on this\n dimension\".** A stake is accepted when every set field matches.\n\n - **betTypes** (array of `BetHashType`, required) - Allowed bet types from the\n `BetHashType` enum. The JSON wire form is **lowercase** (set by Jackson\n `@JsonProperty` on the enum). Possible values:\n\n - `single` - A single selection bet.\n - `parlay` - Accumulator bet (multiple selections combined; all must win).\n The `accumulator*` betRule fields below apply only to this bet type.\n - `system` - System bet (combinations of accumulators).\n\n **Empty array means any bet type.**\n\n - **live** (boolean, optional) - `true` = live betting only, `false` = pre-match\n only, `null` = both allowed.\n - **singleMinOdd** (number, optional) - Minimum odd for `single` bets. Ignored\n for non-single bet types. Applied to the bet's single odd at placement time.\n - **accumulatorTotalOdds** (number, optional) - Minimum total odds for a `parlay`\n (the product of all selection odds). Ignored for non-`parlay` bet types.\n - **accumulatorAtLeastOdd** (number, optional) - At least one selection in the\n `parlay` must have an odd ≥ this value. Combined with\n `accumulatorMinOddPerSelection` for fine-grained control.\n - **accumulatorMinNumberOfSelections** (integer, optional) - Minimum number of\n legs (selections) in the `parlay`.\n - **accumulatorMaxNumberOfSelections** (integer, optional) - Maximum number of\n legs in the `parlay`.\n - **accumulatorMinOddPerSelection** (number, optional) - Minimum odd that\n **every** selection in the `parlay` must meet.\n\n### `freeBetUseType` — FreeBetUseType union\n\nDiscriminated by `__payloadKind`. Two concrete kinds:\n\n- **`FreeBetAllBalanceUseType`** - The stake must consist 100% of free-bet money. Real\n money cannot be mixed in.\n\n - **isMustBeStakedAtOnce** (boolean, required) - When `true`, the entire free-bet\n balance must be wagered in a **single** bet (the player cannot split the\n balance across multiple bets). When `false`, the player may place multiple bets\n until the balance is exhausted, subject to `maxAmountOfBets`.\n\n- **`FreeBetPartialBalanceUseType`** - The stake may mix free-bet money with real\n money. Each bet's free-bet portion is bounded.\n\n - **minValue** (MoneyBag, optional) - Minimum free-bet amount per bet. `null` =\n no minimum.\n - **maxValue** (MoneyBag, optional) - Maximum free-bet amount per bet. `null` =\n no maximum.\n\n### `MoneyBag`\n\nShape — examples in this document use only the `system` amount in a single currency:\n\n```json\n{\n \"system\": { \"amount\": \"50000\", \"currency\": \"TRY\" },\n \"additional\": []\n}\n```\n\n- **system** (`{amount, currency}`, required) - The amount in the bonus's currency.\n The `amount` is a **string** (decimal with no implied scaling — the bonus engine\n stores monetary values in raw integer minor-unit form, e.g. `\"50000\"` = 500.00 TRY).\n- **additional** (array, required) - Per-currency overrides for cross-currency\n bonuses. When the player's currency matches an entry's `currency`, the entry's\n `amount` is used directly; otherwise the `system` amount is converted via the\n operator's currency-pair rates. Single-currency bonuses (the common case) emit\n an empty array, as in all examples in this document.\n\n## Request Examples\n\n### Mode 1 — Catalogue lookup\n\n```json\n{\n \"brandId\": 0,\n \"available\": true\n}\n```\n\n### Mode 2 — Available bonuses for a specific player\n\n```json\n{\n \"brandId\": 0,\n \"available\": true,\n \"externalUserId\": \"ext_987654321\"\n}\n```\n\n### Mode 3 — Registration bonuses only\n\n```json\n{\n \"brandId\": 0,\n \"tag\": \"REGISTRATION\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Internal Free Bet (minimal sportsbook)\n\nThe faithful \"500 TRY FREE BET\" bonus from the legacy Bonus API documentation.\n**Demonstrates the unrestricted shape:** `filters[0]` has every dimension `null` /\nempty (any sport, any category, any tournament, any event, any market, any bet type,\nany odds, no selection limits). `freeBetUseType` is `FreeBetAllBalanceUseType` with\n`isMustBeStakedAtOnce: true`, meaning the entire 500 TRY balance must be wagered in a\nsingle bet.\n\n```json\n{\n \"bonuses\": [\n {\n \"id\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"name\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"ACTIVE\",\n \"enabled\": true,\n \"promotionCode\": \"500TRYFREEBET\",\n \"activityTime\": {\n \"timePeriod\": {\n \"timeRange\": {\n \"from\": 1761721205143,\n \"to\": 1764313205143\n },\n \"isShownBeforePeriod\": true,\n \"isShownAfterPeriod\": false,\n \"shownBeforePeriodMinutes\": null,\n \"shownAfterPeriodMinutes\": null\n },\n \"timeSchedule\": null\n },\n \"timeForActivationInHours\": 168,\n \"currencies\": [\n \"TRY\",\n \"EUR\"\n ],\n \"isAutoActivates\": true,\n \"bonusSize\": {\n \"__payloadKind\": \"FreeBetSize\",\n \"rule\": {\n \"productRules\": [\n {\n \"note\": null,\n \"title\": null,\n \"criteria\": {\n \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n \"filters\": [\n {\n \"sportId\": null,\n \"categoryId\": null,\n \"tournamentId\": null,\n \"eventId\": null,\n \"markets\": [],\n \"betRule\": {\n \"betTypes\": [],\n \"live\": null,\n \"singleMinOdd\": null,\n \"accumulatorTotalOdds\": null,\n \"accumulatorAtLeastOdd\": null,\n \"accumulatorMinNumberOfSelections\": null,\n \"accumulatorMinOddPerSelection\": null,\n \"accumulatorMaxNumberOfSelections\": null\n }\n }\n ],\n \"minValue\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxWinAllowed\": null,\n \"maxAmountOfBets\": null\n },\n \"product\": \"SPORTS\"\n }\n ],\n \"validityInHours\": 168,\n \"note\": null,\n \"freeBetUseType\": {\n \"__payloadKind\": \"FreeBetAllBalanceUseType\",\n \"isMustBeStakedAtOnce\": true\n }\n },\n \"amount\": {\n \"__payloadKind\": \"MonetarySize\",\n \"money\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"winSize\": null,\n \"wagering\": null\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Internal Free Bet (populated sportsbook)\n\nA 100 TRY free bet for **Premier League pre-match singles and parlays**.\n**Demonstrates every populated dimension using real SportsbookSchema values:**\n\n- Sport / category / tournament gating: `sportId` (Football),\n `categoryId` (England), `tournamentId` (Premier League).\n- Three real `MarketType` values allow-listed:\n `[\"score_1x2\", \"score_ou\", \"score_both_to_score_yes_no\"]`.\n- `betTypes: [\"single\", \"parlay\"]` — uses real `BetHashType` JSON values\n (lowercase via Jackson `@JsonProperty`).\n- `live: false` — pre-match only.\n- `single` bets must have an odd ≥ `1.5`.\n- `parlay` bets must have total odds ≥ `3.0`, between `3` and `10` selections, every\n selection at min odd `1.2`, with at least one selection at min odd `1.3`.\n- Stake band `25 TRY ≤ stake ≤ 100 TRY`, max win `1000 TRY`, max `5` bets.\n- 72-hour validity once activated.\n- `freeBetUseType` is `FreeBetPartialBalanceUseType` with the same `25-100 TRY` bounds\n per bet — meaning the player may combine free-bet money with real money on the\n same stake.\n- `isAutoActivates: false` — the partner must call `activate-player-bonus` after\n claim.\n\n```json\n{\n \"bonuses\": [\n {\n \"id\": \"0192bbb0-1234-7aef-9688-aabbccdd0011\",\n \"name\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet \\u2014 100 TRY\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"ACTIVE\",\n \"enabled\": true,\n \"promotionCode\": \"EPL100\",\n \"activityTime\": {\n \"timePeriod\": {\n \"timeRange\": {\n \"from\": 1761721205143,\n \"to\": 1764313205143\n },\n \"isShownBeforePeriod\": true,\n \"isShownAfterPeriod\": false,\n \"shownBeforePeriodMinutes\": null,\n \"shownAfterPeriodMinutes\": null\n },\n \"timeSchedule\": null\n },\n \"timeForActivationInHours\": 72,\n \"currencies\": [\n \"TRY\"\n ],\n \"isAutoActivates\": false,\n \"bonusSize\": {\n \"__payloadKind\": \"FreeBetSize\",\n \"rule\": {\n \"productRules\": [\n {\n \"note\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League pre-match singles and parlays only.\"\n }\n ],\n \"title\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet\"\n }\n ],\n \"criteria\": {\n \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n \"filters\": [\n {\n \"sportId\": \"0192aaaa-1111-7000-9000-000000000001\",\n \"categoryId\": \"0192aaaa-1111-7000-9000-000000000002\",\n \"tournamentId\": \"0192aaaa-1111-7000-9000-000000000003\",\n \"eventId\": null,\n \"markets\": [\n \"score_1x2\",\n \"score_ou\",\n \"score_both_to_score_yes_no\"\n ],\n \"betRule\": {\n \"betTypes\": [\n \"single\",\n \"parlay\"\n ],\n \"live\": false,\n \"singleMinOdd\": 1.5,\n \"accumulatorTotalOdds\": 3.0,\n \"accumulatorAtLeastOdd\": 1.3,\n \"accumulatorMinNumberOfSelections\": 3,\n \"accumulatorMinOddPerSelection\": 1.2,\n \"accumulatorMaxNumberOfSelections\": 10\n }\n }\n ],\n \"minValue\": {\n \"system\": {\n \"amount\": \"2500\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxWinAllowed\": {\n \"system\": {\n \"amount\": \"100000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxAmountOfBets\": 5\n },\n \"product\": \"SPORTS\"\n }\n ],\n \"validityInHours\": 72,\n \"note\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Pre-match Premier League free bet \\u2014 5 bets max within 72h.\"\n }\n ],\n \"freeBetUseType\": {\n \"__payloadKind\": \"FreeBetPartialBalanceUseType\",\n \"minValue\": {\n \"system\": {\n \"amount\": \"2500\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"amount\": {\n \"__payloadKind\": \"MonetarySize\",\n \"money\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"winSize\": null,\n \"wagering\": null\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Empty result\n\n```json\n{\n \"bonuses\": []\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- Both `available` and `tag` omitted.\n- `tag` provided but not equal to `\"REGISTRATION\"` (case-insensitive).\n- Malformed `brandId` (non-integer) or missing `Authorization`.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"either 'available=true' or 'tag=REGISTRATION' must be supplied\"\n}\n```\n\n### 400 Bad Request - Deserialization Error\n\nOccurs when the JSON body cannot be parsed (truncated, invalid escapes, etc.).\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 4,\n \"errorMessage\": \"Failed to deserialize request body\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\nOccurs in Mode 2 when the `externalUserId` cannot be resolved or registered\nautomatically.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\nOccurs when `Authorization` is missing, malformed, or does not match a known brand\ncredential.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 403 Forbidden - IP not whitelisted\n\nOccurs when the request originates from an IP not present in the per-brand allow\nlist. Returned by the gateway, before the application is hit.\n\n**Example Error Response (HTML body, status 403):**\n\n```text\nIP is not presented in white list\n```\n\n### 500 Internal Server Error - Unknown Error\n\nOccurs when an unexpected server error happens.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Sportsbook free-bet only.** This integration is purpose-built for\n `INTERNAL_FREE_BET` bonuses on the sportsbook product\n (`InternalFreeBetSportsbookCriteria` payload). `winSize` is always `null`,\n `wagering` is always `null`. All limits and rules are encoded inside\n `bonusSize.rule.productRules[].criteria` and `bonusSize.rule.freeBetUseType`. Other\n `bonusType` values and non-sportsbook free-bet criteria may appear in the catalogue\n and should be filtered out client-side.\n\n2. **Real schema values.** `betRule.betTypes` uses the **`BetHashType`** enum with\n lowercase JSON values (`\"single\"`, `\"parlay\"`, `\"system\"`) — the `parlay` value is\n the schema name for accumulator bets. `markets` uses the **`MarketType`** enum\n from the generated SportsbookSchema (lowercase names like `score_1x2`, `score_ou`,\n `score_both_to_score_yes_no`).\n\n3. **Visibility flag handling.** In Mode 1 (catalogue) the operator-side\n `\"Show For Players\"` visibility flag is ignored — partners see the full enabled\n catalogue. In Mode 2 (per-player) the flag is honoured: bonuses with\n `isShownForPlayers: false` are hidden.\n\n4. **Mode 2 player registration side-effect.** When `externalUserId` is unknown to\n Sumstats, the system attempts to register the player automatically before\n evaluating eligibility. Subsequent calls for the same `externalUserId` skip\n this step. If automatic registration fails, the request fails with\n `INVALID_USER` (109).\n\n5. **Polymorphic `__payloadKind` discriminator.** All polymorphic objects\n (`bonusSize`, `criteria`, `freeBetUseType`, `bonusSize.amount`) carry a\n `__payloadKind` field containing the concrete payload kind. Partners must\n discriminate on this field — adding new payload kinds in the future is the\n standard evolution path.\n\n6. **`MoneyBag.system` semantics.** `system` carries the canonical amount in the\n operator's accounting currency. When the player's currency matches an entry in\n `additional`, that override is used directly; otherwise the system entry is\n converted via the operator's currency-pair rates. Partners should prefer the\n `additional` entry matching the player's currency for display.\n\n7. **Currencies and bonus selection.** The `currencies` array on the bonus is the\n set of currencies the bonus supports. In Mode 2, only bonuses whose `currencies`\n array contains the player's currency are returned.\n\n8. **Empty filter list semantics.** `criteria.filters` is an array — an **empty\n array** means \"no narrowing\": the free bet may be staked on any sportsbook event.\n **A non-empty filter list is OR'd:** a stake is allowed when at least one filter\n accepts it.\n\n9. **Empty-vs-null in `betRule`.** `betRule.betTypes: []` and `betRule.markets: []`\n mean \"any\" (no restriction); `betRule.live: null` means \"any live mode\"; numeric /\n integer fields use `null` for \"no restriction\". The semantics differ — empty array\n on `betTypes` / `markets`, `null` on the rest.\n\n10. **`isAutoActivates` impact on the claim flow.** When `isAutoActivates: true`,\n calling `claim-bonus-for-player` immediately moves the player bonus to\n `IN_PROGRESS`. When `false`, the partner must call `activate-player-bonus` within\n `timeForActivationInHours` hours.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"bonuses\": [\n {\n \"id\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"name\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"ACTIVE\",\n \"enabled\": true,\n \"promotionCode\": \"500TRYFREEBET\",\n \"activityTime\": {\n \"timePeriod\": {\n \"timeRange\": {\n \"from\": 1761721205143,\n \"to\": 1764313205143\n },\n \"isShownBeforePeriod\": true,\n \"isShownAfterPeriod\": false,\n \"shownBeforePeriodMinutes\": null,\n \"shownAfterPeriodMinutes\": null\n },\n \"timeSchedule\": null\n },\n \"timeForActivationInHours\": 168,\n \"currencies\": [\n \"TRY\",\n \"EUR\"\n ],\n \"isAutoActivates\": true,\n \"bonusSize\": {\n \"__payloadKind\": \"FreeBetSize\",\n \"rule\": {\n \"productRules\": [\n {\n \"note\": null,\n \"title\": null,\n \"criteria\": {\n \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n \"filters\": [\n {\n \"sportId\": null,\n \"categoryId\": null,\n \"tournamentId\": null,\n \"eventId\": null,\n \"markets\": [],\n \"betRule\": {\n \"betTypes\": [],\n \"live\": null,\n \"singleMinOdd\": null,\n \"accumulatorTotalOdds\": null,\n \"accumulatorAtLeastOdd\": null,\n \"accumulatorMinNumberOfSelections\": null,\n \"accumulatorMinOddPerSelection\": null,\n \"accumulatorMaxNumberOfSelections\": null\n }\n }\n ],\n \"minValue\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxWinAllowed\": null,\n \"maxAmountOfBets\": null\n },\n \"product\": \"SPORTS\"\n }\n ],\n \"validityInHours\": 168,\n \"note\": null,\n \"freeBetUseType\": {\n \"__payloadKind\": \"FreeBetAllBalanceUseType\",\n \"isMustBeStakedAtOnce\": true\n }\n },\n \"amount\": {\n \"__payloadKind\": \"MonetarySize\",\n \"money\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"winSize\": null,\n \"wagering\": null\n }\n ]\n}"},{"id":"a8875a64-a539-4ef9-975e-b0740cb0242e","name":"success — Internal Free Bet (populated sportsbook)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"available\": true,\n \"externalUserId\": \"ext_987654321\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/find-available-bonuses","description":"# Endpoint for Finding Available Bonuses\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/find-available-bonuses`\n\n## Description\n\nThis endpoint returns the **internal sportsbook free-bet bonuses** currently offered\nby the operator. Three usage modes are selected via the request body fields:\n\n- **Mode 1 — All available bonuses (catalogue).** `available: true`, `externalUserId`\n omitted. Returns all enabled, in-activity-window bonuses. The operator-side\n `\"Show For Players\"` visibility flag is **ignored** in this mode — the full catalogue\n is exposed so the partner can plan campaigns.\n- **Mode 2 — Available bonuses for a specific player.** `available: true`,\n `externalUserId` set. Returns only the bonuses available *for that player*: per-player\n limits, claim eligibility rules and the operator-side visibility flag are honoured,\n and bonuses already claimed/active for the player are excluded. If the external\n player is unknown to Sumstats, the system attempts to register them automatically\n before evaluating eligibility.\n- **Mode 3 — Registration bonuses only.** `tag: \"REGISTRATION\"` (with or without\n `available`). Returns the subset of bonuses tagged for new-player registration flows.\n\nThe response is **not paginated** — the operator catalogue is bounded (typically tens to\nlow hundreds of enabled bonuses). Each bonus carries a polymorphic free-bet payload\n(`bonusSize.__payloadKind = \"FreeBetSize\"`) describing the substantive offer; the\npartner is expected to discriminate on `__payloadKind` for nested polymorphic objects\n(`criteria`, `freeBetUseType`, `bonusSize.amount`).\n\n> **Scope.** This integration is purpose-built for `INTERNAL_FREE_BET` bonuses on the\n> sportsbook product (`InternalFreeBetSportsbookCriteria` payload). Other bonus types\n> (`CUSTOM`, `FIRST_DEPOSIT`, `EXTERNAL_FREE_BET`, `EXTERNAL_FREE_SPINS_WITH_WAGERING`,\n> `INTERNAL_FREE_SPINS_WITH_WAGERING`, `CASHBACK`) and non-sportsbook free-bet\n> criteria may exist in the operator catalogue but are out of scope for this contract — partners should filter the response to\n> `bonusType: \"INTERNAL_FREE_BET\"` with\n> `bonusSize.rule.productRules[0].criteria.__payloadKind: \"InternalFreeBetSportsbookCriteria\"`\n> client-side.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the brand\n encoded in the HTTP Basic credentials. Used together with `Authorization` for\n credential lookup.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only — partners on the new contract must send `brandId`.\n\n- **available** (boolean, optional) - When `true` activates Mode 1 or Mode 2 selection.\n When omitted, `tag` must be set, otherwise the request is rejected with\n `BAD_REQUEST`.\n\n- **externalUserId** (string, optional) - External player id in the operator system.\n When set, switches the call to Mode 2 (per-player filtering). If the player is\n unknown to Sumstats, the system attempts to register them automatically.\n\n- **tag** (string, optional) - When set, must be `\"REGISTRATION\"` (case-insensitive)\n and switches the call to Mode 3. Any other value is rejected with `BAD_REQUEST`.\n\n## Response Body Description\n\n**Object:**\n\n- **bonuses** (array of objects, required) - List of bonus objects matching the query.\n Empty list when nothing matches. The partner-facing slim shape drops\n internal/operational fields (`descriptionTitle`, `descriptionBonusRules`,\n `fullTermsAndConditions`, `descriptionFiles`, `isShownForPlayers`, `bonusTags`,\n `shareLimitsId`, `eligibilityClaimRulesCompletionInfo`, `notSatisfiedMatchResults`,\n `satisfiedMatchResults`, `operatorId`, `ruleIds`, `removedAt`, `updatedAt`,\n `playerGroupIds`, `bonusOverridableFeatures`).\n\n Each bonus object has the structure documented under **Bonus Fields** below.\n\n### Bonus Fields\n\nThe slim partner-facing bonus shape. Field-by-field semantics:\n\n- **id** (string, required) - Bonus identifier in **UUID v7** format. This is the\n *catalogue* id of the bonus configuration, not a per-player id. Pass to\n `claim-bonus-for-player`, `activate-player-bonus`, `cancel-player-bonus`. Stable\n across partner calls — repeated `find-available-bonuses` requests return the same\n `id` for the same operator-configured bonus until the operator deletes the\n configuration.\n\n- **name** (array of `{locale, translate}`, required) - Localised bonus names. Each\n entry binds a `locale` (BCP-47 / ICU locale code, e.g. `en_US`, `de_DE`) to\n the human-readable bonus name in that locale. Partners should pick the entry\n matching the player's locale; when no exact match exists, fall back to `en_US` or\n the first entry. Bonuses are guaranteed to have **at least one** translation\n (typically `en_US`).\n\n- **bonusType** (enum, required) - High-level bonus kind. **For this integration's\n contract, the relevant value is `INTERNAL_FREE_BET`.** Drives which payload shapes\n appear inside `bonusSize`. Other types may appear in the catalogue but are out of\n scope — partners should filter the response to `bonusType: \"INTERNAL_FREE_BET\"`\n client-side.\n\n- **status** (enum, required) - Lifecycle status of the bonus on the operator side.\n Possible values:\n\n - `NOT_STARTED` - Created and saved but the activity window has not started yet.\n - `SCHEDULED` - Inside the configured activity window but the bonus is scheduled to go active at a later point.\n - `ACTIVE` - Enabled and inside the activity window. Only `ACTIVE` bonuses can be claimed.\n - `DISABLED` - Operator switched the bonus off from the admin panel.\n - `EXPIRED` - Activity window has passed.\n - `REMOVED` - Operator deleted the bonus configuration. Catalogue audits only — not claimable.\n\n Only `ACTIVE` bonuses can be claimed — `find-available-bonuses` does not return\n non-`ACTIVE` bonuses by default; the field is informational for catalogue audits.\n\n- **enabled** (boolean, required) - `false` when the operator has explicitly disabled\n the bonus from the admin panel. A bonus with `status: ACTIVE` and `enabled: false`\n is unavailable for new claims and will not appear in Mode 2 (per-player) responses.\n Mode 1 (catalogue) responses include disabled bonuses for partner audit purposes.\n\n- **promotionCode** (string, optional) - Operator-issued promotion code (e.g.\n `\"500TRYFREEBET\"`, `\"EPL100\"`). When set, the bonus is gated by the code on the\n player-facing surface — players can only claim it through a promo-code flow.\n `null` when the bonus is freely claimable. **Partners using this integration claim\n by `bonusId` directly and bypass the promo-code gate**, but the field is exposed\n so partners can mirror operator-side promo flows on their UI.\n\n- **activityTime** (object, optional) - Activity window. `null` means always on\n (no time gate). The shape mirrors the internal `ActivityTime` record — at most\n one of `timePeriod` / `timeSchedule` is populated:\n\n - **timePeriod** (object, optional) - Continuous activity window.\n - **timeRange** (object, required) - Half-open period.\n - **from** (long, optional) - Start of the window in **epoch millis (UTC)**.\n `null` means open-ended start.\n - **to** (long, optional) - End of the window in **epoch millis (UTC)**.\n `null` means open-ended end.\n - **isShownBeforePeriod** (boolean, required) - Whether the bonus is exposed\n to players before `timeRange.from`.\n - **isShownAfterPeriod** (boolean, required) - Whether the bonus is exposed\n after `timeRange.to`.\n - **shownBeforePeriodMinutes** (long, optional) - How long before\n `timeRange.from` the bonus becomes visible.\n - **shownAfterPeriodMinutes** (long, optional) - How long after\n `timeRange.to` the bonus remains visible.\n - **timeSchedule** (object, optional) - Recurring activity schedule.\n Polymorphic on `__payloadKind`:\n - `HoursOfDayTimeSchedule` — recurring hours-of-day periods (`periods`).\n - `DaysOfWeekTimeSchedule` — recurring per-day-of-week periods\n (`periodsByDay`).\n - `DaysOfMonthTimeSchedule` — recurring per-day-of-month periods\n (`periodsByDay`).\n\n `null` when activity is window-only.\n\n Outside the window the bonus is unclaimable (Sumstats responds with\n `BONUS_NOT_AVAILABLE` (303) on claim).\n\n- **timeForActivationInHours** (integer, optional) - Hours after claim during which\n the player must activate the bonus (i.e. how long the `CLAIMED → IN_PROGRESS`\n transition is allowed). `null` = unlimited (the player bonus stays in `CLAIMED`\n until activation or manual cancel). Used by Sumstats to compute `expiredOnClaimAt`\n on the resulting player bonus. Example: `168` means the player has seven days to\n activate.\n\n- **currencies** (array of strings, required) - Currencies the bonus supports\n (ISO 4217 codes — `TRY`, `EUR`, `USD`, …). The bonus can only be claimed by players\n whose account currency is in this set. In Mode 2, only bonuses whose `currencies`\n array contains the player's currency are returned. Empty array indicates a\n misconfiguration on the operator side.\n\n- **isAutoActivates** (boolean, required) - When `true`, the bonus auto-activates on\n claim — partners do **not** need to call `activate-player-bonus`. The\n `claim-bonus-for-player` response carries `status: \"IN_PROGRESS\"` and a populated\n `activatedAt`. When `false`, the partner must explicitly call `activate-player-bonus`\n within `timeForActivationInHours` hours, or the player bonus expires.\n\n- **bonusSize** (object, required) - Substantive offer payload describing the\n free-bet rule and amount. **For `INTERNAL_FREE_BET` bonuses, `bonusSize.__payloadKind`\n is always `\"FreeBetSize\"`.** See **FreeBetSize** below.\n\n- **winSize** (object, optional) - Cap on potential winnings. **Always `null` for\n `INTERNAL_FREE_BET` bonuses** — the substantive limits are encoded inside the\n free-bet criteria (`bonusSize.rule.productRules[].criteria.maxWinAllowed`).\n\n- **wagering** (object, optional) - Wagering rules. **Always `null` for\n `INTERNAL_FREE_BET` bonuses** — free bets do not have a turnover requirement; the\n free bet either wins, loses, or expires per the criteria rules.\n\n### `bonusSize` — FreeBetSize\n\nFor `INTERNAL_FREE_BET` bonuses, `bonusSize.__payloadKind = \"FreeBetSize\"`. The\n`FreeBetSize` payload has two top-level fields:\n\n- **rule** (object, required) - The free-bet rule — defines per-product criteria,\n free-bet use type, and validity. See **FreeBetRule** below.\n- **amount** (object, optional) - Total monetary value handed to the player as a\n free-bet balance when the bonus is activated. Polymorphic on `__payloadKind`. Two\n practical kinds for free bets:\n\n - **MonetarySize** - Fixed amount.\n\n - **money** (MoneyBag, required) - The free-bet balance. See **MoneyBag** below.\n\n - **PercentageSize** - Percentage of a baseline (rare for free bets).\n\n - **percentage** (number, required) - Percentage value, e.g. `100.0` = 100%.\n - **maxAmount** (MoneyBag, optional) - Upper cap on the resulting balance.\n - **minAmount** (MoneyBag, optional) - Lower floor on the resulting balance.\n\n### `bonusSize.rule` — FreeBetRule\n\n**Object:**\n\n- **productRules** (array of `FreeBetProductRule`, required, length ≥ 1) - Per-product\n free-bet criteria. **For sportsbook free bets there is a single entry with\n `product: \"SPORTS\"`.**\n\n Each `FreeBetProductRule` has:\n\n - **note** (array of `{locale, translate}`, optional) - Operator-supplied note\n describing the rule, localised. `null` when no note was set.\n - **title** (array of `{locale, translate}`, optional) - Operator-supplied title\n for the rule, localised. `null` when no title was set.\n - **product** (string, required) - For this integration's scope, always `\"SPORTS\"`.\n - **criteria** (object, required) - Per-product limit rules. Polymorphic on\n `__payloadKind`. **For sportsbook free bets,\n `criteria.__payloadKind = \"InternalFreeBetSportsbookCriteria\"`.** See\n **InternalFreeBetSportsbookCriteria** below.\n\n- **validityInHours** (integer, required) - Lifetime of the *activated* bonus, in\n hours. `0` = unlimited (the bonus runs until the free-bet balance is exhausted,\n the bet limit hits, or the operator cancels). Maximum supported value ≈ 1 month.\n Used by Sumstats to compute `expiredAt` on the activated player bonus.\n\n- **note** (array of `{locale, translate}`, optional) - Free-form operator note for\n the rule as a whole, localised. `null` when no note was set.\n\n- **freeBetUseType** (object, required) - How the free-bet money composes the\n player's stake. Polymorphic on `__payloadKind`. See **FreeBetUseType union** below.\n\n### `criteria` — InternalFreeBetSportsbookCriteria\n\nFor sportsbook free bets, `criteria.__payloadKind = \"InternalFreeBetSportsbookCriteria\"`.\nTop-level fields:\n\n- **filters** (array of `InternalFreeBetSportsbookFilter`, required) - Filter list\n narrowing where the free bet may be staked. **An empty filter list means \"no\n narrowing\"** (the free bet may be staked on any sportsbook event). Multiple filters\n are OR'd: a stake is allowed if **at least one** filter accepts it. See\n **InternalFreeBetSportsbookFilter** below.\n\n- **minValue** (MoneyBag, optional) - Minimum bet stake required. `null` = no\n minimum. Stakes below this are rejected by the bet placement engine.\n\n- **maxValue** (MoneyBag, optional) - Maximum bet stake allowed. `null` = no\n maximum. Stakes above this are rejected.\n\n- **maxWinAllowed** (MoneyBag, optional) - Per-bet win cap. When set, winnings on a\n single free-bet stake are capped at this amount. `null` = no cap (free bet pays\n out the full computed winnings).\n\n- **maxAmountOfBets** (integer, optional) - Maximum number of bets the player may\n place using the free-bet balance. `null` = unlimited (the bonus runs until the\n free-bet balance is exhausted or expires). Once the limit is hit, the bonus\n transitions to `COMPLETED` automatically.\n\n#### `filters[]` — InternalFreeBetSportsbookFilter\n\nNarrows the events on which the free bet may be staked. **All scalar fields are\nnullable; `null` means \"no restriction on this dimension\".** The filter accepts a\nstake when *every* set field matches the stake's event metadata:\n\n- **sportId** (string, optional) - Restrict to a specific sport (UUID, operator-defined\n — e.g. football, basketball, tennis). `null` = any sport.\n\n- **categoryId** (string, optional) - Restrict to a category — typically a country /\n region inside a sport (UUID, operator-defined — e.g. England, Germany, ATP Tour).\n `null` = any category.\n\n- **tournamentId** (string, optional) - Restrict to a tournament inside a category\n (UUID, operator-defined — e.g. Premier League, Bundesliga, Wimbledon). `null` = any\n tournament.\n\n- **eventId** (string, optional) - Restrict to a single event / match (UUID,\n operator-defined). `null` = any event.\n\n- **markets** (array of `MarketType`, required) - Allow-listed market identifiers\n from the generated `MarketType` enum (lowercase enum names from the SportsbookSchema).\n Examples: `score_1x2`, `score_ou`, `score_dc`, `score_both_to_score_yes_no`,\n `score_ht_ft`, `score_winning_margin`, `score_exact_number`, `corner_1x2`,\n `yellow_card_1x2`. **Empty array means any market.**\n\n- **betRule** (object, optional) - Bet-shape restrictions. **All `betRule` fields\n are nullable; `null` (or empty for set-typed fields) means \"no restriction on this\n dimension\".** A stake is accepted when every set field matches.\n\n - **betTypes** (array of `BetHashType`, required) - Allowed bet types from the\n `BetHashType` enum. The JSON wire form is **lowercase** (set by Jackson\n `@JsonProperty` on the enum). Possible values:\n\n - `single` - A single selection bet.\n - `parlay` - Accumulator bet (multiple selections combined; all must win).\n The `accumulator*` betRule fields below apply only to this bet type.\n - `system` - System bet (combinations of accumulators).\n\n **Empty array means any bet type.**\n\n - **live** (boolean, optional) - `true` = live betting only, `false` = pre-match\n only, `null` = both allowed.\n - **singleMinOdd** (number, optional) - Minimum odd for `single` bets. Ignored\n for non-single bet types. Applied to the bet's single odd at placement time.\n - **accumulatorTotalOdds** (number, optional) - Minimum total odds for a `parlay`\n (the product of all selection odds). Ignored for non-`parlay` bet types.\n - **accumulatorAtLeastOdd** (number, optional) - At least one selection in the\n `parlay` must have an odd ≥ this value. Combined with\n `accumulatorMinOddPerSelection` for fine-grained control.\n - **accumulatorMinNumberOfSelections** (integer, optional) - Minimum number of\n legs (selections) in the `parlay`.\n - **accumulatorMaxNumberOfSelections** (integer, optional) - Maximum number of\n legs in the `parlay`.\n - **accumulatorMinOddPerSelection** (number, optional) - Minimum odd that\n **every** selection in the `parlay` must meet.\n\n### `freeBetUseType` — FreeBetUseType union\n\nDiscriminated by `__payloadKind`. Two concrete kinds:\n\n- **`FreeBetAllBalanceUseType`** - The stake must consist 100% of free-bet money. Real\n money cannot be mixed in.\n\n - **isMustBeStakedAtOnce** (boolean, required) - When `true`, the entire free-bet\n balance must be wagered in a **single** bet (the player cannot split the\n balance across multiple bets). When `false`, the player may place multiple bets\n until the balance is exhausted, subject to `maxAmountOfBets`.\n\n- **`FreeBetPartialBalanceUseType`** - The stake may mix free-bet money with real\n money. Each bet's free-bet portion is bounded.\n\n - **minValue** (MoneyBag, optional) - Minimum free-bet amount per bet. `null` =\n no minimum.\n - **maxValue** (MoneyBag, optional) - Maximum free-bet amount per bet. `null` =\n no maximum.\n\n### `MoneyBag`\n\nShape — examples in this document use only the `system` amount in a single currency:\n\n```json\n{\n \"system\": { \"amount\": \"50000\", \"currency\": \"TRY\" },\n \"additional\": []\n}\n```\n\n- **system** (`{amount, currency}`, required) - The amount in the bonus's currency.\n The `amount` is a **string** (decimal with no implied scaling — the bonus engine\n stores monetary values in raw integer minor-unit form, e.g. `\"50000\"` = 500.00 TRY).\n- **additional** (array, required) - Per-currency overrides for cross-currency\n bonuses. When the player's currency matches an entry's `currency`, the entry's\n `amount` is used directly; otherwise the `system` amount is converted via the\n operator's currency-pair rates. Single-currency bonuses (the common case) emit\n an empty array, as in all examples in this document.\n\n## Request Examples\n\n### Mode 1 — Catalogue lookup\n\n```json\n{\n \"brandId\": 0,\n \"available\": true\n}\n```\n\n### Mode 2 — Available bonuses for a specific player\n\n```json\n{\n \"brandId\": 0,\n \"available\": true,\n \"externalUserId\": \"ext_987654321\"\n}\n```\n\n### Mode 3 — Registration bonuses only\n\n```json\n{\n \"brandId\": 0,\n \"tag\": \"REGISTRATION\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Internal Free Bet (minimal sportsbook)\n\nThe faithful \"500 TRY FREE BET\" bonus from the legacy Bonus API documentation.\n**Demonstrates the unrestricted shape:** `filters[0]` has every dimension `null` /\nempty (any sport, any category, any tournament, any event, any market, any bet type,\nany odds, no selection limits). `freeBetUseType` is `FreeBetAllBalanceUseType` with\n`isMustBeStakedAtOnce: true`, meaning the entire 500 TRY balance must be wagered in a\nsingle bet.\n\n```json\n{\n \"bonuses\": [\n {\n \"id\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"name\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"ACTIVE\",\n \"enabled\": true,\n \"promotionCode\": \"500TRYFREEBET\",\n \"activityTime\": {\n \"timePeriod\": {\n \"timeRange\": {\n \"from\": 1761721205143,\n \"to\": 1764313205143\n },\n \"isShownBeforePeriod\": true,\n \"isShownAfterPeriod\": false,\n \"shownBeforePeriodMinutes\": null,\n \"shownAfterPeriodMinutes\": null\n },\n \"timeSchedule\": null\n },\n \"timeForActivationInHours\": 168,\n \"currencies\": [\n \"TRY\",\n \"EUR\"\n ],\n \"isAutoActivates\": true,\n \"bonusSize\": {\n \"__payloadKind\": \"FreeBetSize\",\n \"rule\": {\n \"productRules\": [\n {\n \"note\": null,\n \"title\": null,\n \"criteria\": {\n \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n \"filters\": [\n {\n \"sportId\": null,\n \"categoryId\": null,\n \"tournamentId\": null,\n \"eventId\": null,\n \"markets\": [],\n \"betRule\": {\n \"betTypes\": [],\n \"live\": null,\n \"singleMinOdd\": null,\n \"accumulatorTotalOdds\": null,\n \"accumulatorAtLeastOdd\": null,\n \"accumulatorMinNumberOfSelections\": null,\n \"accumulatorMinOddPerSelection\": null,\n \"accumulatorMaxNumberOfSelections\": null\n }\n }\n ],\n \"minValue\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxWinAllowed\": null,\n \"maxAmountOfBets\": null\n },\n \"product\": \"SPORTS\"\n }\n ],\n \"validityInHours\": 168,\n \"note\": null,\n \"freeBetUseType\": {\n \"__payloadKind\": \"FreeBetAllBalanceUseType\",\n \"isMustBeStakedAtOnce\": true\n }\n },\n \"amount\": {\n \"__payloadKind\": \"MonetarySize\",\n \"money\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"winSize\": null,\n \"wagering\": null\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Internal Free Bet (populated sportsbook)\n\nA 100 TRY free bet for **Premier League pre-match singles and parlays**.\n**Demonstrates every populated dimension using real SportsbookSchema values:**\n\n- Sport / category / tournament gating: `sportId` (Football),\n `categoryId` (England), `tournamentId` (Premier League).\n- Three real `MarketType` values allow-listed:\n `[\"score_1x2\", \"score_ou\", \"score_both_to_score_yes_no\"]`.\n- `betTypes: [\"single\", \"parlay\"]` — uses real `BetHashType` JSON values\n (lowercase via Jackson `@JsonProperty`).\n- `live: false` — pre-match only.\n- `single` bets must have an odd ≥ `1.5`.\n- `parlay` bets must have total odds ≥ `3.0`, between `3` and `10` selections, every\n selection at min odd `1.2`, with at least one selection at min odd `1.3`.\n- Stake band `25 TRY ≤ stake ≤ 100 TRY`, max win `1000 TRY`, max `5` bets.\n- 72-hour validity once activated.\n- `freeBetUseType` is `FreeBetPartialBalanceUseType` with the same `25-100 TRY` bounds\n per bet — meaning the player may combine free-bet money with real money on the\n same stake.\n- `isAutoActivates: false` — the partner must call `activate-player-bonus` after\n claim.\n\n```json\n{\n \"bonuses\": [\n {\n \"id\": \"0192bbb0-1234-7aef-9688-aabbccdd0011\",\n \"name\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet \\u2014 100 TRY\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"ACTIVE\",\n \"enabled\": true,\n \"promotionCode\": \"EPL100\",\n \"activityTime\": {\n \"timePeriod\": {\n \"timeRange\": {\n \"from\": 1761721205143,\n \"to\": 1764313205143\n },\n \"isShownBeforePeriod\": true,\n \"isShownAfterPeriod\": false,\n \"shownBeforePeriodMinutes\": null,\n \"shownAfterPeriodMinutes\": null\n },\n \"timeSchedule\": null\n },\n \"timeForActivationInHours\": 72,\n \"currencies\": [\n \"TRY\"\n ],\n \"isAutoActivates\": false,\n \"bonusSize\": {\n \"__payloadKind\": \"FreeBetSize\",\n \"rule\": {\n \"productRules\": [\n {\n \"note\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League pre-match singles and parlays only.\"\n }\n ],\n \"title\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet\"\n }\n ],\n \"criteria\": {\n \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n \"filters\": [\n {\n \"sportId\": \"0192aaaa-1111-7000-9000-000000000001\",\n \"categoryId\": \"0192aaaa-1111-7000-9000-000000000002\",\n \"tournamentId\": \"0192aaaa-1111-7000-9000-000000000003\",\n \"eventId\": null,\n \"markets\": [\n \"score_1x2\",\n \"score_ou\",\n \"score_both_to_score_yes_no\"\n ],\n \"betRule\": {\n \"betTypes\": [\n \"single\",\n \"parlay\"\n ],\n \"live\": false,\n \"singleMinOdd\": 1.5,\n \"accumulatorTotalOdds\": 3.0,\n \"accumulatorAtLeastOdd\": 1.3,\n \"accumulatorMinNumberOfSelections\": 3,\n \"accumulatorMinOddPerSelection\": 1.2,\n \"accumulatorMaxNumberOfSelections\": 10\n }\n }\n ],\n \"minValue\": {\n \"system\": {\n \"amount\": \"2500\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxWinAllowed\": {\n \"system\": {\n \"amount\": \"100000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxAmountOfBets\": 5\n },\n \"product\": \"SPORTS\"\n }\n ],\n \"validityInHours\": 72,\n \"note\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Pre-match Premier League free bet \\u2014 5 bets max within 72h.\"\n }\n ],\n \"freeBetUseType\": {\n \"__payloadKind\": \"FreeBetPartialBalanceUseType\",\n \"minValue\": {\n \"system\": {\n \"amount\": \"2500\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"amount\": {\n \"__payloadKind\": \"MonetarySize\",\n \"money\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"winSize\": null,\n \"wagering\": null\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Empty result\n\n```json\n{\n \"bonuses\": []\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- Both `available` and `tag` omitted.\n- `tag` provided but not equal to `\"REGISTRATION\"` (case-insensitive).\n- Malformed `brandId` (non-integer) or missing `Authorization`.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"either 'available=true' or 'tag=REGISTRATION' must be supplied\"\n}\n```\n\n### 400 Bad Request - Deserialization Error\n\nOccurs when the JSON body cannot be parsed (truncated, invalid escapes, etc.).\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 4,\n \"errorMessage\": \"Failed to deserialize request body\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\nOccurs in Mode 2 when the `externalUserId` cannot be resolved or registered\nautomatically.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\nOccurs when `Authorization` is missing, malformed, or does not match a known brand\ncredential.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 403 Forbidden - IP not whitelisted\n\nOccurs when the request originates from an IP not present in the per-brand allow\nlist. Returned by the gateway, before the application is hit.\n\n**Example Error Response (HTML body, status 403):**\n\n```text\nIP is not presented in white list\n```\n\n### 500 Internal Server Error - Unknown Error\n\nOccurs when an unexpected server error happens.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Sportsbook free-bet only.** This integration is purpose-built for\n `INTERNAL_FREE_BET` bonuses on the sportsbook product\n (`InternalFreeBetSportsbookCriteria` payload). `winSize` is always `null`,\n `wagering` is always `null`. All limits and rules are encoded inside\n `bonusSize.rule.productRules[].criteria` and `bonusSize.rule.freeBetUseType`. Other\n `bonusType` values and non-sportsbook free-bet criteria may appear in the catalogue\n and should be filtered out client-side.\n\n2. **Real schema values.** `betRule.betTypes` uses the **`BetHashType`** enum with\n lowercase JSON values (`\"single\"`, `\"parlay\"`, `\"system\"`) — the `parlay` value is\n the schema name for accumulator bets. `markets` uses the **`MarketType`** enum\n from the generated SportsbookSchema (lowercase names like `score_1x2`, `score_ou`,\n `score_both_to_score_yes_no`).\n\n3. **Visibility flag handling.** In Mode 1 (catalogue) the operator-side\n `\"Show For Players\"` visibility flag is ignored — partners see the full enabled\n catalogue. In Mode 2 (per-player) the flag is honoured: bonuses with\n `isShownForPlayers: false` are hidden.\n\n4. **Mode 2 player registration side-effect.** When `externalUserId` is unknown to\n Sumstats, the system attempts to register the player automatically before\n evaluating eligibility. Subsequent calls for the same `externalUserId` skip\n this step. If automatic registration fails, the request fails with\n `INVALID_USER` (109).\n\n5. **Polymorphic `__payloadKind` discriminator.** All polymorphic objects\n (`bonusSize`, `criteria`, `freeBetUseType`, `bonusSize.amount`) carry a\n `__payloadKind` field containing the concrete payload kind. Partners must\n discriminate on this field — adding new payload kinds in the future is the\n standard evolution path.\n\n6. **`MoneyBag.system` semantics.** `system` carries the canonical amount in the\n operator's accounting currency. When the player's currency matches an entry in\n `additional`, that override is used directly; otherwise the system entry is\n converted via the operator's currency-pair rates. Partners should prefer the\n `additional` entry matching the player's currency for display.\n\n7. **Currencies and bonus selection.** The `currencies` array on the bonus is the\n set of currencies the bonus supports. In Mode 2, only bonuses whose `currencies`\n array contains the player's currency are returned.\n\n8. **Empty filter list semantics.** `criteria.filters` is an array — an **empty\n array** means \"no narrowing\": the free bet may be staked on any sportsbook event.\n **A non-empty filter list is OR'd:** a stake is allowed when at least one filter\n accepts it.\n\n9. **Empty-vs-null in `betRule`.** `betRule.betTypes: []` and `betRule.markets: []`\n mean \"any\" (no restriction); `betRule.live: null` means \"any live mode\"; numeric /\n integer fields use `null` for \"no restriction\". The semantics differ — empty array\n on `betTypes` / `markets`, `null` on the rest.\n\n10. **`isAutoActivates` impact on the claim flow.** When `isAutoActivates: true`,\n calling `claim-bonus-for-player` immediately moves the player bonus to\n `IN_PROGRESS`. When `false`, the partner must call `activate-player-bonus` within\n `timeForActivationInHours` hours.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"bonuses\": [\n {\n \"id\": \"0192bbb0-1234-7aef-9688-aabbccdd0011\",\n \"name\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet \\u2014 100 TRY\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"ACTIVE\",\n \"enabled\": true,\n \"promotionCode\": \"EPL100\",\n \"activityTime\": {\n \"timePeriod\": {\n \"timeRange\": {\n \"from\": 1761721205143,\n \"to\": 1764313205143\n },\n \"isShownBeforePeriod\": true,\n \"isShownAfterPeriod\": false,\n \"shownBeforePeriodMinutes\": null,\n \"shownAfterPeriodMinutes\": null\n },\n \"timeSchedule\": null\n },\n \"timeForActivationInHours\": 72,\n \"currencies\": [\n \"TRY\"\n ],\n \"isAutoActivates\": false,\n \"bonusSize\": {\n \"__payloadKind\": \"FreeBetSize\",\n \"rule\": {\n \"productRules\": [\n {\n \"note\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League pre-match singles and parlays only.\"\n }\n ],\n \"title\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet\"\n }\n ],\n \"criteria\": {\n \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n \"filters\": [\n {\n \"sportId\": \"0192aaaa-1111-7000-9000-000000000001\",\n \"categoryId\": \"0192aaaa-1111-7000-9000-000000000002\",\n \"tournamentId\": \"0192aaaa-1111-7000-9000-000000000003\",\n \"eventId\": null,\n \"markets\": [\n \"score_1x2\",\n \"score_ou\",\n \"score_both_to_score_yes_no\"\n ],\n \"betRule\": {\n \"betTypes\": [\n \"single\",\n \"parlay\"\n ],\n \"live\": false,\n \"singleMinOdd\": 1.5,\n \"accumulatorTotalOdds\": 3.0,\n \"accumulatorAtLeastOdd\": 1.3,\n \"accumulatorMinNumberOfSelections\": 3,\n \"accumulatorMinOddPerSelection\": 1.2,\n \"accumulatorMaxNumberOfSelections\": 10\n }\n }\n ],\n \"minValue\": {\n \"system\": {\n \"amount\": \"2500\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxWinAllowed\": {\n \"system\": {\n \"amount\": \"100000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxAmountOfBets\": 5\n },\n \"product\": \"SPORTS\"\n }\n ],\n \"validityInHours\": 72,\n \"note\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Pre-match Premier League free bet \\u2014 5 bets max within 72h.\"\n }\n ],\n \"freeBetUseType\": {\n \"__payloadKind\": \"FreeBetPartialBalanceUseType\",\n \"minValue\": {\n \"system\": {\n \"amount\": \"2500\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"amount\": {\n \"__payloadKind\": \"MonetarySize\",\n \"money\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"winSize\": null,\n \"wagering\": null\n }\n ]\n}"},{"id":"13b2b86c-3db0-4a4a-ae64-97ffdaff9d4e","name":"success — Empty","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"available\": true,\n \"externalUserId\": \"ext_987654321\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/find-available-bonuses","description":"# Endpoint for Finding Available Bonuses\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/find-available-bonuses`\n\n## Description\n\nThis endpoint returns the **internal sportsbook free-bet bonuses** currently offered\nby the operator. Three usage modes are selected via the request body fields:\n\n- **Mode 1 — All available bonuses (catalogue).** `available: true`, `externalUserId`\n omitted. Returns all enabled, in-activity-window bonuses. The operator-side\n `\"Show For Players\"` visibility flag is **ignored** in this mode — the full catalogue\n is exposed so the partner can plan campaigns.\n- **Mode 2 — Available bonuses for a specific player.** `available: true`,\n `externalUserId` set. Returns only the bonuses available *for that player*: per-player\n limits, claim eligibility rules and the operator-side visibility flag are honoured,\n and bonuses already claimed/active for the player are excluded. If the external\n player is unknown to Sumstats, the system attempts to register them automatically\n before evaluating eligibility.\n- **Mode 3 — Registration bonuses only.** `tag: \"REGISTRATION\"` (with or without\n `available`). Returns the subset of bonuses tagged for new-player registration flows.\n\nThe response is **not paginated** — the operator catalogue is bounded (typically tens to\nlow hundreds of enabled bonuses). Each bonus carries a polymorphic free-bet payload\n(`bonusSize.__payloadKind = \"FreeBetSize\"`) describing the substantive offer; the\npartner is expected to discriminate on `__payloadKind` for nested polymorphic objects\n(`criteria`, `freeBetUseType`, `bonusSize.amount`).\n\n> **Scope.** This integration is purpose-built for `INTERNAL_FREE_BET` bonuses on the\n> sportsbook product (`InternalFreeBetSportsbookCriteria` payload). Other bonus types\n> (`CUSTOM`, `FIRST_DEPOSIT`, `EXTERNAL_FREE_BET`, `EXTERNAL_FREE_SPINS_WITH_WAGERING`,\n> `INTERNAL_FREE_SPINS_WITH_WAGERING`, `CASHBACK`) and non-sportsbook free-bet\n> criteria may exist in the operator catalogue but are out of scope for this contract — partners should filter the response to\n> `bonusType: \"INTERNAL_FREE_BET\"` with\n> `bonusSize.rule.productRules[0].criteria.__payloadKind: \"InternalFreeBetSportsbookCriteria\"`\n> client-side.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the brand\n encoded in the HTTP Basic credentials. Used together with `Authorization` for\n credential lookup.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only — partners on the new contract must send `brandId`.\n\n- **available** (boolean, optional) - When `true` activates Mode 1 or Mode 2 selection.\n When omitted, `tag` must be set, otherwise the request is rejected with\n `BAD_REQUEST`.\n\n- **externalUserId** (string, optional) - External player id in the operator system.\n When set, switches the call to Mode 2 (per-player filtering). If the player is\n unknown to Sumstats, the system attempts to register them automatically.\n\n- **tag** (string, optional) - When set, must be `\"REGISTRATION\"` (case-insensitive)\n and switches the call to Mode 3. Any other value is rejected with `BAD_REQUEST`.\n\n## Response Body Description\n\n**Object:**\n\n- **bonuses** (array of objects, required) - List of bonus objects matching the query.\n Empty list when nothing matches. The partner-facing slim shape drops\n internal/operational fields (`descriptionTitle`, `descriptionBonusRules`,\n `fullTermsAndConditions`, `descriptionFiles`, `isShownForPlayers`, `bonusTags`,\n `shareLimitsId`, `eligibilityClaimRulesCompletionInfo`, `notSatisfiedMatchResults`,\n `satisfiedMatchResults`, `operatorId`, `ruleIds`, `removedAt`, `updatedAt`,\n `playerGroupIds`, `bonusOverridableFeatures`).\n\n Each bonus object has the structure documented under **Bonus Fields** below.\n\n### Bonus Fields\n\nThe slim partner-facing bonus shape. Field-by-field semantics:\n\n- **id** (string, required) - Bonus identifier in **UUID v7** format. This is the\n *catalogue* id of the bonus configuration, not a per-player id. Pass to\n `claim-bonus-for-player`, `activate-player-bonus`, `cancel-player-bonus`. Stable\n across partner calls — repeated `find-available-bonuses` requests return the same\n `id` for the same operator-configured bonus until the operator deletes the\n configuration.\n\n- **name** (array of `{locale, translate}`, required) - Localised bonus names. Each\n entry binds a `locale` (BCP-47 / ICU locale code, e.g. `en_US`, `de_DE`) to\n the human-readable bonus name in that locale. Partners should pick the entry\n matching the player's locale; when no exact match exists, fall back to `en_US` or\n the first entry. Bonuses are guaranteed to have **at least one** translation\n (typically `en_US`).\n\n- **bonusType** (enum, required) - High-level bonus kind. **For this integration's\n contract, the relevant value is `INTERNAL_FREE_BET`.** Drives which payload shapes\n appear inside `bonusSize`. Other types may appear in the catalogue but are out of\n scope — partners should filter the response to `bonusType: \"INTERNAL_FREE_BET\"`\n client-side.\n\n- **status** (enum, required) - Lifecycle status of the bonus on the operator side.\n Possible values:\n\n - `NOT_STARTED` - Created and saved but the activity window has not started yet.\n - `SCHEDULED` - Inside the configured activity window but the bonus is scheduled to go active at a later point.\n - `ACTIVE` - Enabled and inside the activity window. Only `ACTIVE` bonuses can be claimed.\n - `DISABLED` - Operator switched the bonus off from the admin panel.\n - `EXPIRED` - Activity window has passed.\n - `REMOVED` - Operator deleted the bonus configuration. Catalogue audits only — not claimable.\n\n Only `ACTIVE` bonuses can be claimed — `find-available-bonuses` does not return\n non-`ACTIVE` bonuses by default; the field is informational for catalogue audits.\n\n- **enabled** (boolean, required) - `false` when the operator has explicitly disabled\n the bonus from the admin panel. A bonus with `status: ACTIVE` and `enabled: false`\n is unavailable for new claims and will not appear in Mode 2 (per-player) responses.\n Mode 1 (catalogue) responses include disabled bonuses for partner audit purposes.\n\n- **promotionCode** (string, optional) - Operator-issued promotion code (e.g.\n `\"500TRYFREEBET\"`, `\"EPL100\"`). When set, the bonus is gated by the code on the\n player-facing surface — players can only claim it through a promo-code flow.\n `null` when the bonus is freely claimable. **Partners using this integration claim\n by `bonusId` directly and bypass the promo-code gate**, but the field is exposed\n so partners can mirror operator-side promo flows on their UI.\n\n- **activityTime** (object, optional) - Activity window. `null` means always on\n (no time gate). The shape mirrors the internal `ActivityTime` record — at most\n one of `timePeriod` / `timeSchedule` is populated:\n\n - **timePeriod** (object, optional) - Continuous activity window.\n - **timeRange** (object, required) - Half-open period.\n - **from** (long, optional) - Start of the window in **epoch millis (UTC)**.\n `null` means open-ended start.\n - **to** (long, optional) - End of the window in **epoch millis (UTC)**.\n `null` means open-ended end.\n - **isShownBeforePeriod** (boolean, required) - Whether the bonus is exposed\n to players before `timeRange.from`.\n - **isShownAfterPeriod** (boolean, required) - Whether the bonus is exposed\n after `timeRange.to`.\n - **shownBeforePeriodMinutes** (long, optional) - How long before\n `timeRange.from` the bonus becomes visible.\n - **shownAfterPeriodMinutes** (long, optional) - How long after\n `timeRange.to` the bonus remains visible.\n - **timeSchedule** (object, optional) - Recurring activity schedule.\n Polymorphic on `__payloadKind`:\n - `HoursOfDayTimeSchedule` — recurring hours-of-day periods (`periods`).\n - `DaysOfWeekTimeSchedule` — recurring per-day-of-week periods\n (`periodsByDay`).\n - `DaysOfMonthTimeSchedule` — recurring per-day-of-month periods\n (`periodsByDay`).\n\n `null` when activity is window-only.\n\n Outside the window the bonus is unclaimable (Sumstats responds with\n `BONUS_NOT_AVAILABLE` (303) on claim).\n\n- **timeForActivationInHours** (integer, optional) - Hours after claim during which\n the player must activate the bonus (i.e. how long the `CLAIMED → IN_PROGRESS`\n transition is allowed). `null` = unlimited (the player bonus stays in `CLAIMED`\n until activation or manual cancel). Used by Sumstats to compute `expiredOnClaimAt`\n on the resulting player bonus. Example: `168` means the player has seven days to\n activate.\n\n- **currencies** (array of strings, required) - Currencies the bonus supports\n (ISO 4217 codes — `TRY`, `EUR`, `USD`, …). The bonus can only be claimed by players\n whose account currency is in this set. In Mode 2, only bonuses whose `currencies`\n array contains the player's currency are returned. Empty array indicates a\n misconfiguration on the operator side.\n\n- **isAutoActivates** (boolean, required) - When `true`, the bonus auto-activates on\n claim — partners do **not** need to call `activate-player-bonus`. The\n `claim-bonus-for-player` response carries `status: \"IN_PROGRESS\"` and a populated\n `activatedAt`. When `false`, the partner must explicitly call `activate-player-bonus`\n within `timeForActivationInHours` hours, or the player bonus expires.\n\n- **bonusSize** (object, required) - Substantive offer payload describing the\n free-bet rule and amount. **For `INTERNAL_FREE_BET` bonuses, `bonusSize.__payloadKind`\n is always `\"FreeBetSize\"`.** See **FreeBetSize** below.\n\n- **winSize** (object, optional) - Cap on potential winnings. **Always `null` for\n `INTERNAL_FREE_BET` bonuses** — the substantive limits are encoded inside the\n free-bet criteria (`bonusSize.rule.productRules[].criteria.maxWinAllowed`).\n\n- **wagering** (object, optional) - Wagering rules. **Always `null` for\n `INTERNAL_FREE_BET` bonuses** — free bets do not have a turnover requirement; the\n free bet either wins, loses, or expires per the criteria rules.\n\n### `bonusSize` — FreeBetSize\n\nFor `INTERNAL_FREE_BET` bonuses, `bonusSize.__payloadKind = \"FreeBetSize\"`. The\n`FreeBetSize` payload has two top-level fields:\n\n- **rule** (object, required) - The free-bet rule — defines per-product criteria,\n free-bet use type, and validity. See **FreeBetRule** below.\n- **amount** (object, optional) - Total monetary value handed to the player as a\n free-bet balance when the bonus is activated. Polymorphic on `__payloadKind`. Two\n practical kinds for free bets:\n\n - **MonetarySize** - Fixed amount.\n\n - **money** (MoneyBag, required) - The free-bet balance. See **MoneyBag** below.\n\n - **PercentageSize** - Percentage of a baseline (rare for free bets).\n\n - **percentage** (number, required) - Percentage value, e.g. `100.0` = 100%.\n - **maxAmount** (MoneyBag, optional) - Upper cap on the resulting balance.\n - **minAmount** (MoneyBag, optional) - Lower floor on the resulting balance.\n\n### `bonusSize.rule` — FreeBetRule\n\n**Object:**\n\n- **productRules** (array of `FreeBetProductRule`, required, length ≥ 1) - Per-product\n free-bet criteria. **For sportsbook free bets there is a single entry with\n `product: \"SPORTS\"`.**\n\n Each `FreeBetProductRule` has:\n\n - **note** (array of `{locale, translate}`, optional) - Operator-supplied note\n describing the rule, localised. `null` when no note was set.\n - **title** (array of `{locale, translate}`, optional) - Operator-supplied title\n for the rule, localised. `null` when no title was set.\n - **product** (string, required) - For this integration's scope, always `\"SPORTS\"`.\n - **criteria** (object, required) - Per-product limit rules. Polymorphic on\n `__payloadKind`. **For sportsbook free bets,\n `criteria.__payloadKind = \"InternalFreeBetSportsbookCriteria\"`.** See\n **InternalFreeBetSportsbookCriteria** below.\n\n- **validityInHours** (integer, required) - Lifetime of the *activated* bonus, in\n hours. `0` = unlimited (the bonus runs until the free-bet balance is exhausted,\n the bet limit hits, or the operator cancels). Maximum supported value ≈ 1 month.\n Used by Sumstats to compute `expiredAt` on the activated player bonus.\n\n- **note** (array of `{locale, translate}`, optional) - Free-form operator note for\n the rule as a whole, localised. `null` when no note was set.\n\n- **freeBetUseType** (object, required) - How the free-bet money composes the\n player's stake. Polymorphic on `__payloadKind`. See **FreeBetUseType union** below.\n\n### `criteria` — InternalFreeBetSportsbookCriteria\n\nFor sportsbook free bets, `criteria.__payloadKind = \"InternalFreeBetSportsbookCriteria\"`.\nTop-level fields:\n\n- **filters** (array of `InternalFreeBetSportsbookFilter`, required) - Filter list\n narrowing where the free bet may be staked. **An empty filter list means \"no\n narrowing\"** (the free bet may be staked on any sportsbook event). Multiple filters\n are OR'd: a stake is allowed if **at least one** filter accepts it. See\n **InternalFreeBetSportsbookFilter** below.\n\n- **minValue** (MoneyBag, optional) - Minimum bet stake required. `null` = no\n minimum. Stakes below this are rejected by the bet placement engine.\n\n- **maxValue** (MoneyBag, optional) - Maximum bet stake allowed. `null` = no\n maximum. Stakes above this are rejected.\n\n- **maxWinAllowed** (MoneyBag, optional) - Per-bet win cap. When set, winnings on a\n single free-bet stake are capped at this amount. `null` = no cap (free bet pays\n out the full computed winnings).\n\n- **maxAmountOfBets** (integer, optional) - Maximum number of bets the player may\n place using the free-bet balance. `null` = unlimited (the bonus runs until the\n free-bet balance is exhausted or expires). Once the limit is hit, the bonus\n transitions to `COMPLETED` automatically.\n\n#### `filters[]` — InternalFreeBetSportsbookFilter\n\nNarrows the events on which the free bet may be staked. **All scalar fields are\nnullable; `null` means \"no restriction on this dimension\".** The filter accepts a\nstake when *every* set field matches the stake's event metadata:\n\n- **sportId** (string, optional) - Restrict to a specific sport (UUID, operator-defined\n — e.g. football, basketball, tennis). `null` = any sport.\n\n- **categoryId** (string, optional) - Restrict to a category — typically a country /\n region inside a sport (UUID, operator-defined — e.g. England, Germany, ATP Tour).\n `null` = any category.\n\n- **tournamentId** (string, optional) - Restrict to a tournament inside a category\n (UUID, operator-defined — e.g. Premier League, Bundesliga, Wimbledon). `null` = any\n tournament.\n\n- **eventId** (string, optional) - Restrict to a single event / match (UUID,\n operator-defined). `null` = any event.\n\n- **markets** (array of `MarketType`, required) - Allow-listed market identifiers\n from the generated `MarketType` enum (lowercase enum names from the SportsbookSchema).\n Examples: `score_1x2`, `score_ou`, `score_dc`, `score_both_to_score_yes_no`,\n `score_ht_ft`, `score_winning_margin`, `score_exact_number`, `corner_1x2`,\n `yellow_card_1x2`. **Empty array means any market.**\n\n- **betRule** (object, optional) - Bet-shape restrictions. **All `betRule` fields\n are nullable; `null` (or empty for set-typed fields) means \"no restriction on this\n dimension\".** A stake is accepted when every set field matches.\n\n - **betTypes** (array of `BetHashType`, required) - Allowed bet types from the\n `BetHashType` enum. The JSON wire form is **lowercase** (set by Jackson\n `@JsonProperty` on the enum). Possible values:\n\n - `single` - A single selection bet.\n - `parlay` - Accumulator bet (multiple selections combined; all must win).\n The `accumulator*` betRule fields below apply only to this bet type.\n - `system` - System bet (combinations of accumulators).\n\n **Empty array means any bet type.**\n\n - **live** (boolean, optional) - `true` = live betting only, `false` = pre-match\n only, `null` = both allowed.\n - **singleMinOdd** (number, optional) - Minimum odd for `single` bets. Ignored\n for non-single bet types. Applied to the bet's single odd at placement time.\n - **accumulatorTotalOdds** (number, optional) - Minimum total odds for a `parlay`\n (the product of all selection odds). Ignored for non-`parlay` bet types.\n - **accumulatorAtLeastOdd** (number, optional) - At least one selection in the\n `parlay` must have an odd ≥ this value. Combined with\n `accumulatorMinOddPerSelection` for fine-grained control.\n - **accumulatorMinNumberOfSelections** (integer, optional) - Minimum number of\n legs (selections) in the `parlay`.\n - **accumulatorMaxNumberOfSelections** (integer, optional) - Maximum number of\n legs in the `parlay`.\n - **accumulatorMinOddPerSelection** (number, optional) - Minimum odd that\n **every** selection in the `parlay` must meet.\n\n### `freeBetUseType` — FreeBetUseType union\n\nDiscriminated by `__payloadKind`. Two concrete kinds:\n\n- **`FreeBetAllBalanceUseType`** - The stake must consist 100% of free-bet money. Real\n money cannot be mixed in.\n\n - **isMustBeStakedAtOnce** (boolean, required) - When `true`, the entire free-bet\n balance must be wagered in a **single** bet (the player cannot split the\n balance across multiple bets). When `false`, the player may place multiple bets\n until the balance is exhausted, subject to `maxAmountOfBets`.\n\n- **`FreeBetPartialBalanceUseType`** - The stake may mix free-bet money with real\n money. Each bet's free-bet portion is bounded.\n\n - **minValue** (MoneyBag, optional) - Minimum free-bet amount per bet. `null` =\n no minimum.\n - **maxValue** (MoneyBag, optional) - Maximum free-bet amount per bet. `null` =\n no maximum.\n\n### `MoneyBag`\n\nShape — examples in this document use only the `system` amount in a single currency:\n\n```json\n{\n \"system\": { \"amount\": \"50000\", \"currency\": \"TRY\" },\n \"additional\": []\n}\n```\n\n- **system** (`{amount, currency}`, required) - The amount in the bonus's currency.\n The `amount` is a **string** (decimal with no implied scaling — the bonus engine\n stores monetary values in raw integer minor-unit form, e.g. `\"50000\"` = 500.00 TRY).\n- **additional** (array, required) - Per-currency overrides for cross-currency\n bonuses. When the player's currency matches an entry's `currency`, the entry's\n `amount` is used directly; otherwise the `system` amount is converted via the\n operator's currency-pair rates. Single-currency bonuses (the common case) emit\n an empty array, as in all examples in this document.\n\n## Request Examples\n\n### Mode 1 — Catalogue lookup\n\n```json\n{\n \"brandId\": 0,\n \"available\": true\n}\n```\n\n### Mode 2 — Available bonuses for a specific player\n\n```json\n{\n \"brandId\": 0,\n \"available\": true,\n \"externalUserId\": \"ext_987654321\"\n}\n```\n\n### Mode 3 — Registration bonuses only\n\n```json\n{\n \"brandId\": 0,\n \"tag\": \"REGISTRATION\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Internal Free Bet (minimal sportsbook)\n\nThe faithful \"500 TRY FREE BET\" bonus from the legacy Bonus API documentation.\n**Demonstrates the unrestricted shape:** `filters[0]` has every dimension `null` /\nempty (any sport, any category, any tournament, any event, any market, any bet type,\nany odds, no selection limits). `freeBetUseType` is `FreeBetAllBalanceUseType` with\n`isMustBeStakedAtOnce: true`, meaning the entire 500 TRY balance must be wagered in a\nsingle bet.\n\n```json\n{\n \"bonuses\": [\n {\n \"id\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"name\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"ACTIVE\",\n \"enabled\": true,\n \"promotionCode\": \"500TRYFREEBET\",\n \"activityTime\": {\n \"timePeriod\": {\n \"timeRange\": {\n \"from\": 1761721205143,\n \"to\": 1764313205143\n },\n \"isShownBeforePeriod\": true,\n \"isShownAfterPeriod\": false,\n \"shownBeforePeriodMinutes\": null,\n \"shownAfterPeriodMinutes\": null\n },\n \"timeSchedule\": null\n },\n \"timeForActivationInHours\": 168,\n \"currencies\": [\n \"TRY\",\n \"EUR\"\n ],\n \"isAutoActivates\": true,\n \"bonusSize\": {\n \"__payloadKind\": \"FreeBetSize\",\n \"rule\": {\n \"productRules\": [\n {\n \"note\": null,\n \"title\": null,\n \"criteria\": {\n \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n \"filters\": [\n {\n \"sportId\": null,\n \"categoryId\": null,\n \"tournamentId\": null,\n \"eventId\": null,\n \"markets\": [],\n \"betRule\": {\n \"betTypes\": [],\n \"live\": null,\n \"singleMinOdd\": null,\n \"accumulatorTotalOdds\": null,\n \"accumulatorAtLeastOdd\": null,\n \"accumulatorMinNumberOfSelections\": null,\n \"accumulatorMinOddPerSelection\": null,\n \"accumulatorMaxNumberOfSelections\": null\n }\n }\n ],\n \"minValue\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxWinAllowed\": null,\n \"maxAmountOfBets\": null\n },\n \"product\": \"SPORTS\"\n }\n ],\n \"validityInHours\": 168,\n \"note\": null,\n \"freeBetUseType\": {\n \"__payloadKind\": \"FreeBetAllBalanceUseType\",\n \"isMustBeStakedAtOnce\": true\n }\n },\n \"amount\": {\n \"__payloadKind\": \"MonetarySize\",\n \"money\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"winSize\": null,\n \"wagering\": null\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Internal Free Bet (populated sportsbook)\n\nA 100 TRY free bet for **Premier League pre-match singles and parlays**.\n**Demonstrates every populated dimension using real SportsbookSchema values:**\n\n- Sport / category / tournament gating: `sportId` (Football),\n `categoryId` (England), `tournamentId` (Premier League).\n- Three real `MarketType` values allow-listed:\n `[\"score_1x2\", \"score_ou\", \"score_both_to_score_yes_no\"]`.\n- `betTypes: [\"single\", \"parlay\"]` — uses real `BetHashType` JSON values\n (lowercase via Jackson `@JsonProperty`).\n- `live: false` — pre-match only.\n- `single` bets must have an odd ≥ `1.5`.\n- `parlay` bets must have total odds ≥ `3.0`, between `3` and `10` selections, every\n selection at min odd `1.2`, with at least one selection at min odd `1.3`.\n- Stake band `25 TRY ≤ stake ≤ 100 TRY`, max win `1000 TRY`, max `5` bets.\n- 72-hour validity once activated.\n- `freeBetUseType` is `FreeBetPartialBalanceUseType` with the same `25-100 TRY` bounds\n per bet — meaning the player may combine free-bet money with real money on the\n same stake.\n- `isAutoActivates: false` — the partner must call `activate-player-bonus` after\n claim.\n\n```json\n{\n \"bonuses\": [\n {\n \"id\": \"0192bbb0-1234-7aef-9688-aabbccdd0011\",\n \"name\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet \\u2014 100 TRY\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"ACTIVE\",\n \"enabled\": true,\n \"promotionCode\": \"EPL100\",\n \"activityTime\": {\n \"timePeriod\": {\n \"timeRange\": {\n \"from\": 1761721205143,\n \"to\": 1764313205143\n },\n \"isShownBeforePeriod\": true,\n \"isShownAfterPeriod\": false,\n \"shownBeforePeriodMinutes\": null,\n \"shownAfterPeriodMinutes\": null\n },\n \"timeSchedule\": null\n },\n \"timeForActivationInHours\": 72,\n \"currencies\": [\n \"TRY\"\n ],\n \"isAutoActivates\": false,\n \"bonusSize\": {\n \"__payloadKind\": \"FreeBetSize\",\n \"rule\": {\n \"productRules\": [\n {\n \"note\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League pre-match singles and parlays only.\"\n }\n ],\n \"title\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet\"\n }\n ],\n \"criteria\": {\n \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n \"filters\": [\n {\n \"sportId\": \"0192aaaa-1111-7000-9000-000000000001\",\n \"categoryId\": \"0192aaaa-1111-7000-9000-000000000002\",\n \"tournamentId\": \"0192aaaa-1111-7000-9000-000000000003\",\n \"eventId\": null,\n \"markets\": [\n \"score_1x2\",\n \"score_ou\",\n \"score_both_to_score_yes_no\"\n ],\n \"betRule\": {\n \"betTypes\": [\n \"single\",\n \"parlay\"\n ],\n \"live\": false,\n \"singleMinOdd\": 1.5,\n \"accumulatorTotalOdds\": 3.0,\n \"accumulatorAtLeastOdd\": 1.3,\n \"accumulatorMinNumberOfSelections\": 3,\n \"accumulatorMinOddPerSelection\": 1.2,\n \"accumulatorMaxNumberOfSelections\": 10\n }\n }\n ],\n \"minValue\": {\n \"system\": {\n \"amount\": \"2500\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxWinAllowed\": {\n \"system\": {\n \"amount\": \"100000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxAmountOfBets\": 5\n },\n \"product\": \"SPORTS\"\n }\n ],\n \"validityInHours\": 72,\n \"note\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Pre-match Premier League free bet \\u2014 5 bets max within 72h.\"\n }\n ],\n \"freeBetUseType\": {\n \"__payloadKind\": \"FreeBetPartialBalanceUseType\",\n \"minValue\": {\n \"system\": {\n \"amount\": \"2500\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"amount\": {\n \"__payloadKind\": \"MonetarySize\",\n \"money\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"winSize\": null,\n \"wagering\": null\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Empty result\n\n```json\n{\n \"bonuses\": []\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- Both `available` and `tag` omitted.\n- `tag` provided but not equal to `\"REGISTRATION\"` (case-insensitive).\n- Malformed `brandId` (non-integer) or missing `Authorization`.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"either 'available=true' or 'tag=REGISTRATION' must be supplied\"\n}\n```\n\n### 400 Bad Request - Deserialization Error\n\nOccurs when the JSON body cannot be parsed (truncated, invalid escapes, etc.).\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 4,\n \"errorMessage\": \"Failed to deserialize request body\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\nOccurs in Mode 2 when the `externalUserId` cannot be resolved or registered\nautomatically.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\nOccurs when `Authorization` is missing, malformed, or does not match a known brand\ncredential.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 403 Forbidden - IP not whitelisted\n\nOccurs when the request originates from an IP not present in the per-brand allow\nlist. Returned by the gateway, before the application is hit.\n\n**Example Error Response (HTML body, status 403):**\n\n```text\nIP is not presented in white list\n```\n\n### 500 Internal Server Error - Unknown Error\n\nOccurs when an unexpected server error happens.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Sportsbook free-bet only.** This integration is purpose-built for\n `INTERNAL_FREE_BET` bonuses on the sportsbook product\n (`InternalFreeBetSportsbookCriteria` payload). `winSize` is always `null`,\n `wagering` is always `null`. All limits and rules are encoded inside\n `bonusSize.rule.productRules[].criteria` and `bonusSize.rule.freeBetUseType`. Other\n `bonusType` values and non-sportsbook free-bet criteria may appear in the catalogue\n and should be filtered out client-side.\n\n2. **Real schema values.** `betRule.betTypes` uses the **`BetHashType`** enum with\n lowercase JSON values (`\"single\"`, `\"parlay\"`, `\"system\"`) — the `parlay` value is\n the schema name for accumulator bets. `markets` uses the **`MarketType`** enum\n from the generated SportsbookSchema (lowercase names like `score_1x2`, `score_ou`,\n `score_both_to_score_yes_no`).\n\n3. **Visibility flag handling.** In Mode 1 (catalogue) the operator-side\n `\"Show For Players\"` visibility flag is ignored — partners see the full enabled\n catalogue. In Mode 2 (per-player) the flag is honoured: bonuses with\n `isShownForPlayers: false` are hidden.\n\n4. **Mode 2 player registration side-effect.** When `externalUserId` is unknown to\n Sumstats, the system attempts to register the player automatically before\n evaluating eligibility. Subsequent calls for the same `externalUserId` skip\n this step. If automatic registration fails, the request fails with\n `INVALID_USER` (109).\n\n5. **Polymorphic `__payloadKind` discriminator.** All polymorphic objects\n (`bonusSize`, `criteria`, `freeBetUseType`, `bonusSize.amount`) carry a\n `__payloadKind` field containing the concrete payload kind. Partners must\n discriminate on this field — adding new payload kinds in the future is the\n standard evolution path.\n\n6. **`MoneyBag.system` semantics.** `system` carries the canonical amount in the\n operator's accounting currency. When the player's currency matches an entry in\n `additional`, that override is used directly; otherwise the system entry is\n converted via the operator's currency-pair rates. Partners should prefer the\n `additional` entry matching the player's currency for display.\n\n7. **Currencies and bonus selection.** The `currencies` array on the bonus is the\n set of currencies the bonus supports. In Mode 2, only bonuses whose `currencies`\n array contains the player's currency are returned.\n\n8. **Empty filter list semantics.** `criteria.filters` is an array — an **empty\n array** means \"no narrowing\": the free bet may be staked on any sportsbook event.\n **A non-empty filter list is OR'd:** a stake is allowed when at least one filter\n accepts it.\n\n9. **Empty-vs-null in `betRule`.** `betRule.betTypes: []` and `betRule.markets: []`\n mean \"any\" (no restriction); `betRule.live: null` means \"any live mode\"; numeric /\n integer fields use `null` for \"no restriction\". The semantics differ — empty array\n on `betTypes` / `markets`, `null` on the rest.\n\n10. **`isAutoActivates` impact on the claim flow.** When `isAutoActivates: true`,\n calling `claim-bonus-for-player` immediately moves the player bonus to\n `IN_PROGRESS`. When `false`, the partner must call `activate-player-bonus` within\n `timeForActivationInHours` hours.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"bonuses\": []\n}"},{"id":"3a19312f-6408-4099-9ff9-151a115acf34","name":"fail — bad request","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"available\": true,\n \"externalUserId\": \"ext_987654321\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/find-available-bonuses","description":"# Endpoint for Finding Available Bonuses\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/find-available-bonuses`\n\n## Description\n\nThis endpoint returns the **internal sportsbook free-bet bonuses** currently offered\nby the operator. Three usage modes are selected via the request body fields:\n\n- **Mode 1 — All available bonuses (catalogue).** `available: true`, `externalUserId`\n omitted. Returns all enabled, in-activity-window bonuses. The operator-side\n `\"Show For Players\"` visibility flag is **ignored** in this mode — the full catalogue\n is exposed so the partner can plan campaigns.\n- **Mode 2 — Available bonuses for a specific player.** `available: true`,\n `externalUserId` set. Returns only the bonuses available *for that player*: per-player\n limits, claim eligibility rules and the operator-side visibility flag are honoured,\n and bonuses already claimed/active for the player are excluded. If the external\n player is unknown to Sumstats, the system attempts to register them automatically\n before evaluating eligibility.\n- **Mode 3 — Registration bonuses only.** `tag: \"REGISTRATION\"` (with or without\n `available`). Returns the subset of bonuses tagged for new-player registration flows.\n\nThe response is **not paginated** — the operator catalogue is bounded (typically tens to\nlow hundreds of enabled bonuses). Each bonus carries a polymorphic free-bet payload\n(`bonusSize.__payloadKind = \"FreeBetSize\"`) describing the substantive offer; the\npartner is expected to discriminate on `__payloadKind` for nested polymorphic objects\n(`criteria`, `freeBetUseType`, `bonusSize.amount`).\n\n> **Scope.** This integration is purpose-built for `INTERNAL_FREE_BET` bonuses on the\n> sportsbook product (`InternalFreeBetSportsbookCriteria` payload). Other bonus types\n> (`CUSTOM`, `FIRST_DEPOSIT`, `EXTERNAL_FREE_BET`, `EXTERNAL_FREE_SPINS_WITH_WAGERING`,\n> `INTERNAL_FREE_SPINS_WITH_WAGERING`, `CASHBACK`) and non-sportsbook free-bet\n> criteria may exist in the operator catalogue but are out of scope for this contract — partners should filter the response to\n> `bonusType: \"INTERNAL_FREE_BET\"` with\n> `bonusSize.rule.productRules[0].criteria.__payloadKind: \"InternalFreeBetSportsbookCriteria\"`\n> client-side.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the brand\n encoded in the HTTP Basic credentials. Used together with `Authorization` for\n credential lookup.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only — partners on the new contract must send `brandId`.\n\n- **available** (boolean, optional) - When `true` activates Mode 1 or Mode 2 selection.\n When omitted, `tag` must be set, otherwise the request is rejected with\n `BAD_REQUEST`.\n\n- **externalUserId** (string, optional) - External player id in the operator system.\n When set, switches the call to Mode 2 (per-player filtering). If the player is\n unknown to Sumstats, the system attempts to register them automatically.\n\n- **tag** (string, optional) - When set, must be `\"REGISTRATION\"` (case-insensitive)\n and switches the call to Mode 3. Any other value is rejected with `BAD_REQUEST`.\n\n## Response Body Description\n\n**Object:**\n\n- **bonuses** (array of objects, required) - List of bonus objects matching the query.\n Empty list when nothing matches. The partner-facing slim shape drops\n internal/operational fields (`descriptionTitle`, `descriptionBonusRules`,\n `fullTermsAndConditions`, `descriptionFiles`, `isShownForPlayers`, `bonusTags`,\n `shareLimitsId`, `eligibilityClaimRulesCompletionInfo`, `notSatisfiedMatchResults`,\n `satisfiedMatchResults`, `operatorId`, `ruleIds`, `removedAt`, `updatedAt`,\n `playerGroupIds`, `bonusOverridableFeatures`).\n\n Each bonus object has the structure documented under **Bonus Fields** below.\n\n### Bonus Fields\n\nThe slim partner-facing bonus shape. Field-by-field semantics:\n\n- **id** (string, required) - Bonus identifier in **UUID v7** format. This is the\n *catalogue* id of the bonus configuration, not a per-player id. Pass to\n `claim-bonus-for-player`, `activate-player-bonus`, `cancel-player-bonus`. Stable\n across partner calls — repeated `find-available-bonuses` requests return the same\n `id` for the same operator-configured bonus until the operator deletes the\n configuration.\n\n- **name** (array of `{locale, translate}`, required) - Localised bonus names. Each\n entry binds a `locale` (BCP-47 / ICU locale code, e.g. `en_US`, `de_DE`) to\n the human-readable bonus name in that locale. Partners should pick the entry\n matching the player's locale; when no exact match exists, fall back to `en_US` or\n the first entry. Bonuses are guaranteed to have **at least one** translation\n (typically `en_US`).\n\n- **bonusType** (enum, required) - High-level bonus kind. **For this integration's\n contract, the relevant value is `INTERNAL_FREE_BET`.** Drives which payload shapes\n appear inside `bonusSize`. Other types may appear in the catalogue but are out of\n scope — partners should filter the response to `bonusType: \"INTERNAL_FREE_BET\"`\n client-side.\n\n- **status** (enum, required) - Lifecycle status of the bonus on the operator side.\n Possible values:\n\n - `NOT_STARTED` - Created and saved but the activity window has not started yet.\n - `SCHEDULED` - Inside the configured activity window but the bonus is scheduled to go active at a later point.\n - `ACTIVE` - Enabled and inside the activity window. Only `ACTIVE` bonuses can be claimed.\n - `DISABLED` - Operator switched the bonus off from the admin panel.\n - `EXPIRED` - Activity window has passed.\n - `REMOVED` - Operator deleted the bonus configuration. Catalogue audits only — not claimable.\n\n Only `ACTIVE` bonuses can be claimed — `find-available-bonuses` does not return\n non-`ACTIVE` bonuses by default; the field is informational for catalogue audits.\n\n- **enabled** (boolean, required) - `false` when the operator has explicitly disabled\n the bonus from the admin panel. A bonus with `status: ACTIVE` and `enabled: false`\n is unavailable for new claims and will not appear in Mode 2 (per-player) responses.\n Mode 1 (catalogue) responses include disabled bonuses for partner audit purposes.\n\n- **promotionCode** (string, optional) - Operator-issued promotion code (e.g.\n `\"500TRYFREEBET\"`, `\"EPL100\"`). When set, the bonus is gated by the code on the\n player-facing surface — players can only claim it through a promo-code flow.\n `null` when the bonus is freely claimable. **Partners using this integration claim\n by `bonusId` directly and bypass the promo-code gate**, but the field is exposed\n so partners can mirror operator-side promo flows on their UI.\n\n- **activityTime** (object, optional) - Activity window. `null` means always on\n (no time gate). The shape mirrors the internal `ActivityTime` record — at most\n one of `timePeriod` / `timeSchedule` is populated:\n\n - **timePeriod** (object, optional) - Continuous activity window.\n - **timeRange** (object, required) - Half-open period.\n - **from** (long, optional) - Start of the window in **epoch millis (UTC)**.\n `null` means open-ended start.\n - **to** (long, optional) - End of the window in **epoch millis (UTC)**.\n `null` means open-ended end.\n - **isShownBeforePeriod** (boolean, required) - Whether the bonus is exposed\n to players before `timeRange.from`.\n - **isShownAfterPeriod** (boolean, required) - Whether the bonus is exposed\n after `timeRange.to`.\n - **shownBeforePeriodMinutes** (long, optional) - How long before\n `timeRange.from` the bonus becomes visible.\n - **shownAfterPeriodMinutes** (long, optional) - How long after\n `timeRange.to` the bonus remains visible.\n - **timeSchedule** (object, optional) - Recurring activity schedule.\n Polymorphic on `__payloadKind`:\n - `HoursOfDayTimeSchedule` — recurring hours-of-day periods (`periods`).\n - `DaysOfWeekTimeSchedule` — recurring per-day-of-week periods\n (`periodsByDay`).\n - `DaysOfMonthTimeSchedule` — recurring per-day-of-month periods\n (`periodsByDay`).\n\n `null` when activity is window-only.\n\n Outside the window the bonus is unclaimable (Sumstats responds with\n `BONUS_NOT_AVAILABLE` (303) on claim).\n\n- **timeForActivationInHours** (integer, optional) - Hours after claim during which\n the player must activate the bonus (i.e. how long the `CLAIMED → IN_PROGRESS`\n transition is allowed). `null` = unlimited (the player bonus stays in `CLAIMED`\n until activation or manual cancel). Used by Sumstats to compute `expiredOnClaimAt`\n on the resulting player bonus. Example: `168` means the player has seven days to\n activate.\n\n- **currencies** (array of strings, required) - Currencies the bonus supports\n (ISO 4217 codes — `TRY`, `EUR`, `USD`, …). The bonus can only be claimed by players\n whose account currency is in this set. In Mode 2, only bonuses whose `currencies`\n array contains the player's currency are returned. Empty array indicates a\n misconfiguration on the operator side.\n\n- **isAutoActivates** (boolean, required) - When `true`, the bonus auto-activates on\n claim — partners do **not** need to call `activate-player-bonus`. The\n `claim-bonus-for-player` response carries `status: \"IN_PROGRESS\"` and a populated\n `activatedAt`. When `false`, the partner must explicitly call `activate-player-bonus`\n within `timeForActivationInHours` hours, or the player bonus expires.\n\n- **bonusSize** (object, required) - Substantive offer payload describing the\n free-bet rule and amount. **For `INTERNAL_FREE_BET` bonuses, `bonusSize.__payloadKind`\n is always `\"FreeBetSize\"`.** See **FreeBetSize** below.\n\n- **winSize** (object, optional) - Cap on potential winnings. **Always `null` for\n `INTERNAL_FREE_BET` bonuses** — the substantive limits are encoded inside the\n free-bet criteria (`bonusSize.rule.productRules[].criteria.maxWinAllowed`).\n\n- **wagering** (object, optional) - Wagering rules. **Always `null` for\n `INTERNAL_FREE_BET` bonuses** — free bets do not have a turnover requirement; the\n free bet either wins, loses, or expires per the criteria rules.\n\n### `bonusSize` — FreeBetSize\n\nFor `INTERNAL_FREE_BET` bonuses, `bonusSize.__payloadKind = \"FreeBetSize\"`. The\n`FreeBetSize` payload has two top-level fields:\n\n- **rule** (object, required) - The free-bet rule — defines per-product criteria,\n free-bet use type, and validity. See **FreeBetRule** below.\n- **amount** (object, optional) - Total monetary value handed to the player as a\n free-bet balance when the bonus is activated. Polymorphic on `__payloadKind`. Two\n practical kinds for free bets:\n\n - **MonetarySize** - Fixed amount.\n\n - **money** (MoneyBag, required) - The free-bet balance. See **MoneyBag** below.\n\n - **PercentageSize** - Percentage of a baseline (rare for free bets).\n\n - **percentage** (number, required) - Percentage value, e.g. `100.0` = 100%.\n - **maxAmount** (MoneyBag, optional) - Upper cap on the resulting balance.\n - **minAmount** (MoneyBag, optional) - Lower floor on the resulting balance.\n\n### `bonusSize.rule` — FreeBetRule\n\n**Object:**\n\n- **productRules** (array of `FreeBetProductRule`, required, length ≥ 1) - Per-product\n free-bet criteria. **For sportsbook free bets there is a single entry with\n `product: \"SPORTS\"`.**\n\n Each `FreeBetProductRule` has:\n\n - **note** (array of `{locale, translate}`, optional) - Operator-supplied note\n describing the rule, localised. `null` when no note was set.\n - **title** (array of `{locale, translate}`, optional) - Operator-supplied title\n for the rule, localised. `null` when no title was set.\n - **product** (string, required) - For this integration's scope, always `\"SPORTS\"`.\n - **criteria** (object, required) - Per-product limit rules. Polymorphic on\n `__payloadKind`. **For sportsbook free bets,\n `criteria.__payloadKind = \"InternalFreeBetSportsbookCriteria\"`.** See\n **InternalFreeBetSportsbookCriteria** below.\n\n- **validityInHours** (integer, required) - Lifetime of the *activated* bonus, in\n hours. `0` = unlimited (the bonus runs until the free-bet balance is exhausted,\n the bet limit hits, or the operator cancels). Maximum supported value ≈ 1 month.\n Used by Sumstats to compute `expiredAt` on the activated player bonus.\n\n- **note** (array of `{locale, translate}`, optional) - Free-form operator note for\n the rule as a whole, localised. `null` when no note was set.\n\n- **freeBetUseType** (object, required) - How the free-bet money composes the\n player's stake. Polymorphic on `__payloadKind`. See **FreeBetUseType union** below.\n\n### `criteria` — InternalFreeBetSportsbookCriteria\n\nFor sportsbook free bets, `criteria.__payloadKind = \"InternalFreeBetSportsbookCriteria\"`.\nTop-level fields:\n\n- **filters** (array of `InternalFreeBetSportsbookFilter`, required) - Filter list\n narrowing where the free bet may be staked. **An empty filter list means \"no\n narrowing\"** (the free bet may be staked on any sportsbook event). Multiple filters\n are OR'd: a stake is allowed if **at least one** filter accepts it. See\n **InternalFreeBetSportsbookFilter** below.\n\n- **minValue** (MoneyBag, optional) - Minimum bet stake required. `null` = no\n minimum. Stakes below this are rejected by the bet placement engine.\n\n- **maxValue** (MoneyBag, optional) - Maximum bet stake allowed. `null` = no\n maximum. Stakes above this are rejected.\n\n- **maxWinAllowed** (MoneyBag, optional) - Per-bet win cap. When set, winnings on a\n single free-bet stake are capped at this amount. `null` = no cap (free bet pays\n out the full computed winnings).\n\n- **maxAmountOfBets** (integer, optional) - Maximum number of bets the player may\n place using the free-bet balance. `null` = unlimited (the bonus runs until the\n free-bet balance is exhausted or expires). Once the limit is hit, the bonus\n transitions to `COMPLETED` automatically.\n\n#### `filters[]` — InternalFreeBetSportsbookFilter\n\nNarrows the events on which the free bet may be staked. **All scalar fields are\nnullable; `null` means \"no restriction on this dimension\".** The filter accepts a\nstake when *every* set field matches the stake's event metadata:\n\n- **sportId** (string, optional) - Restrict to a specific sport (UUID, operator-defined\n — e.g. football, basketball, tennis). `null` = any sport.\n\n- **categoryId** (string, optional) - Restrict to a category — typically a country /\n region inside a sport (UUID, operator-defined — e.g. England, Germany, ATP Tour).\n `null` = any category.\n\n- **tournamentId** (string, optional) - Restrict to a tournament inside a category\n (UUID, operator-defined — e.g. Premier League, Bundesliga, Wimbledon). `null` = any\n tournament.\n\n- **eventId** (string, optional) - Restrict to a single event / match (UUID,\n operator-defined). `null` = any event.\n\n- **markets** (array of `MarketType`, required) - Allow-listed market identifiers\n from the generated `MarketType` enum (lowercase enum names from the SportsbookSchema).\n Examples: `score_1x2`, `score_ou`, `score_dc`, `score_both_to_score_yes_no`,\n `score_ht_ft`, `score_winning_margin`, `score_exact_number`, `corner_1x2`,\n `yellow_card_1x2`. **Empty array means any market.**\n\n- **betRule** (object, optional) - Bet-shape restrictions. **All `betRule` fields\n are nullable; `null` (or empty for set-typed fields) means \"no restriction on this\n dimension\".** A stake is accepted when every set field matches.\n\n - **betTypes** (array of `BetHashType`, required) - Allowed bet types from the\n `BetHashType` enum. The JSON wire form is **lowercase** (set by Jackson\n `@JsonProperty` on the enum). Possible values:\n\n - `single` - A single selection bet.\n - `parlay` - Accumulator bet (multiple selections combined; all must win).\n The `accumulator*` betRule fields below apply only to this bet type.\n - `system` - System bet (combinations of accumulators).\n\n **Empty array means any bet type.**\n\n - **live** (boolean, optional) - `true` = live betting only, `false` = pre-match\n only, `null` = both allowed.\n - **singleMinOdd** (number, optional) - Minimum odd for `single` bets. Ignored\n for non-single bet types. Applied to the bet's single odd at placement time.\n - **accumulatorTotalOdds** (number, optional) - Minimum total odds for a `parlay`\n (the product of all selection odds). Ignored for non-`parlay` bet types.\n - **accumulatorAtLeastOdd** (number, optional) - At least one selection in the\n `parlay` must have an odd ≥ this value. Combined with\n `accumulatorMinOddPerSelection` for fine-grained control.\n - **accumulatorMinNumberOfSelections** (integer, optional) - Minimum number of\n legs (selections) in the `parlay`.\n - **accumulatorMaxNumberOfSelections** (integer, optional) - Maximum number of\n legs in the `parlay`.\n - **accumulatorMinOddPerSelection** (number, optional) - Minimum odd that\n **every** selection in the `parlay` must meet.\n\n### `freeBetUseType` — FreeBetUseType union\n\nDiscriminated by `__payloadKind`. Two concrete kinds:\n\n- **`FreeBetAllBalanceUseType`** - The stake must consist 100% of free-bet money. Real\n money cannot be mixed in.\n\n - **isMustBeStakedAtOnce** (boolean, required) - When `true`, the entire free-bet\n balance must be wagered in a **single** bet (the player cannot split the\n balance across multiple bets). When `false`, the player may place multiple bets\n until the balance is exhausted, subject to `maxAmountOfBets`.\n\n- **`FreeBetPartialBalanceUseType`** - The stake may mix free-bet money with real\n money. Each bet's free-bet portion is bounded.\n\n - **minValue** (MoneyBag, optional) - Minimum free-bet amount per bet. `null` =\n no minimum.\n - **maxValue** (MoneyBag, optional) - Maximum free-bet amount per bet. `null` =\n no maximum.\n\n### `MoneyBag`\n\nShape — examples in this document use only the `system` amount in a single currency:\n\n```json\n{\n \"system\": { \"amount\": \"50000\", \"currency\": \"TRY\" },\n \"additional\": []\n}\n```\n\n- **system** (`{amount, currency}`, required) - The amount in the bonus's currency.\n The `amount` is a **string** (decimal with no implied scaling — the bonus engine\n stores monetary values in raw integer minor-unit form, e.g. `\"50000\"` = 500.00 TRY).\n- **additional** (array, required) - Per-currency overrides for cross-currency\n bonuses. When the player's currency matches an entry's `currency`, the entry's\n `amount` is used directly; otherwise the `system` amount is converted via the\n operator's currency-pair rates. Single-currency bonuses (the common case) emit\n an empty array, as in all examples in this document.\n\n## Request Examples\n\n### Mode 1 — Catalogue lookup\n\n```json\n{\n \"brandId\": 0,\n \"available\": true\n}\n```\n\n### Mode 2 — Available bonuses for a specific player\n\n```json\n{\n \"brandId\": 0,\n \"available\": true,\n \"externalUserId\": \"ext_987654321\"\n}\n```\n\n### Mode 3 — Registration bonuses only\n\n```json\n{\n \"brandId\": 0,\n \"tag\": \"REGISTRATION\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Internal Free Bet (minimal sportsbook)\n\nThe faithful \"500 TRY FREE BET\" bonus from the legacy Bonus API documentation.\n**Demonstrates the unrestricted shape:** `filters[0]` has every dimension `null` /\nempty (any sport, any category, any tournament, any event, any market, any bet type,\nany odds, no selection limits). `freeBetUseType` is `FreeBetAllBalanceUseType` with\n`isMustBeStakedAtOnce: true`, meaning the entire 500 TRY balance must be wagered in a\nsingle bet.\n\n```json\n{\n \"bonuses\": [\n {\n \"id\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"name\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"ACTIVE\",\n \"enabled\": true,\n \"promotionCode\": \"500TRYFREEBET\",\n \"activityTime\": {\n \"timePeriod\": {\n \"timeRange\": {\n \"from\": 1761721205143,\n \"to\": 1764313205143\n },\n \"isShownBeforePeriod\": true,\n \"isShownAfterPeriod\": false,\n \"shownBeforePeriodMinutes\": null,\n \"shownAfterPeriodMinutes\": null\n },\n \"timeSchedule\": null\n },\n \"timeForActivationInHours\": 168,\n \"currencies\": [\n \"TRY\",\n \"EUR\"\n ],\n \"isAutoActivates\": true,\n \"bonusSize\": {\n \"__payloadKind\": \"FreeBetSize\",\n \"rule\": {\n \"productRules\": [\n {\n \"note\": null,\n \"title\": null,\n \"criteria\": {\n \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n \"filters\": [\n {\n \"sportId\": null,\n \"categoryId\": null,\n \"tournamentId\": null,\n \"eventId\": null,\n \"markets\": [],\n \"betRule\": {\n \"betTypes\": [],\n \"live\": null,\n \"singleMinOdd\": null,\n \"accumulatorTotalOdds\": null,\n \"accumulatorAtLeastOdd\": null,\n \"accumulatorMinNumberOfSelections\": null,\n \"accumulatorMinOddPerSelection\": null,\n \"accumulatorMaxNumberOfSelections\": null\n }\n }\n ],\n \"minValue\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxWinAllowed\": null,\n \"maxAmountOfBets\": null\n },\n \"product\": \"SPORTS\"\n }\n ],\n \"validityInHours\": 168,\n \"note\": null,\n \"freeBetUseType\": {\n \"__payloadKind\": \"FreeBetAllBalanceUseType\",\n \"isMustBeStakedAtOnce\": true\n }\n },\n \"amount\": {\n \"__payloadKind\": \"MonetarySize\",\n \"money\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"winSize\": null,\n \"wagering\": null\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Internal Free Bet (populated sportsbook)\n\nA 100 TRY free bet for **Premier League pre-match singles and parlays**.\n**Demonstrates every populated dimension using real SportsbookSchema values:**\n\n- Sport / category / tournament gating: `sportId` (Football),\n `categoryId` (England), `tournamentId` (Premier League).\n- Three real `MarketType` values allow-listed:\n `[\"score_1x2\", \"score_ou\", \"score_both_to_score_yes_no\"]`.\n- `betTypes: [\"single\", \"parlay\"]` — uses real `BetHashType` JSON values\n (lowercase via Jackson `@JsonProperty`).\n- `live: false` — pre-match only.\n- `single` bets must have an odd ≥ `1.5`.\n- `parlay` bets must have total odds ≥ `3.0`, between `3` and `10` selections, every\n selection at min odd `1.2`, with at least one selection at min odd `1.3`.\n- Stake band `25 TRY ≤ stake ≤ 100 TRY`, max win `1000 TRY`, max `5` bets.\n- 72-hour validity once activated.\n- `freeBetUseType` is `FreeBetPartialBalanceUseType` with the same `25-100 TRY` bounds\n per bet — meaning the player may combine free-bet money with real money on the\n same stake.\n- `isAutoActivates: false` — the partner must call `activate-player-bonus` after\n claim.\n\n```json\n{\n \"bonuses\": [\n {\n \"id\": \"0192bbb0-1234-7aef-9688-aabbccdd0011\",\n \"name\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet \\u2014 100 TRY\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"ACTIVE\",\n \"enabled\": true,\n \"promotionCode\": \"EPL100\",\n \"activityTime\": {\n \"timePeriod\": {\n \"timeRange\": {\n \"from\": 1761721205143,\n \"to\": 1764313205143\n },\n \"isShownBeforePeriod\": true,\n \"isShownAfterPeriod\": false,\n \"shownBeforePeriodMinutes\": null,\n \"shownAfterPeriodMinutes\": null\n },\n \"timeSchedule\": null\n },\n \"timeForActivationInHours\": 72,\n \"currencies\": [\n \"TRY\"\n ],\n \"isAutoActivates\": false,\n \"bonusSize\": {\n \"__payloadKind\": \"FreeBetSize\",\n \"rule\": {\n \"productRules\": [\n {\n \"note\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League pre-match singles and parlays only.\"\n }\n ],\n \"title\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet\"\n }\n ],\n \"criteria\": {\n \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n \"filters\": [\n {\n \"sportId\": \"0192aaaa-1111-7000-9000-000000000001\",\n \"categoryId\": \"0192aaaa-1111-7000-9000-000000000002\",\n \"tournamentId\": \"0192aaaa-1111-7000-9000-000000000003\",\n \"eventId\": null,\n \"markets\": [\n \"score_1x2\",\n \"score_ou\",\n \"score_both_to_score_yes_no\"\n ],\n \"betRule\": {\n \"betTypes\": [\n \"single\",\n \"parlay\"\n ],\n \"live\": false,\n \"singleMinOdd\": 1.5,\n \"accumulatorTotalOdds\": 3.0,\n \"accumulatorAtLeastOdd\": 1.3,\n \"accumulatorMinNumberOfSelections\": 3,\n \"accumulatorMinOddPerSelection\": 1.2,\n \"accumulatorMaxNumberOfSelections\": 10\n }\n }\n ],\n \"minValue\": {\n \"system\": {\n \"amount\": \"2500\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxWinAllowed\": {\n \"system\": {\n \"amount\": \"100000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxAmountOfBets\": 5\n },\n \"product\": \"SPORTS\"\n }\n ],\n \"validityInHours\": 72,\n \"note\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Pre-match Premier League free bet \\u2014 5 bets max within 72h.\"\n }\n ],\n \"freeBetUseType\": {\n \"__payloadKind\": \"FreeBetPartialBalanceUseType\",\n \"minValue\": {\n \"system\": {\n \"amount\": \"2500\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"amount\": {\n \"__payloadKind\": \"MonetarySize\",\n \"money\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"winSize\": null,\n \"wagering\": null\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Empty result\n\n```json\n{\n \"bonuses\": []\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- Both `available` and `tag` omitted.\n- `tag` provided but not equal to `\"REGISTRATION\"` (case-insensitive).\n- Malformed `brandId` (non-integer) or missing `Authorization`.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"either 'available=true' or 'tag=REGISTRATION' must be supplied\"\n}\n```\n\n### 400 Bad Request - Deserialization Error\n\nOccurs when the JSON body cannot be parsed (truncated, invalid escapes, etc.).\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 4,\n \"errorMessage\": \"Failed to deserialize request body\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\nOccurs in Mode 2 when the `externalUserId` cannot be resolved or registered\nautomatically.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\nOccurs when `Authorization` is missing, malformed, or does not match a known brand\ncredential.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 403 Forbidden - IP not whitelisted\n\nOccurs when the request originates from an IP not present in the per-brand allow\nlist. Returned by the gateway, before the application is hit.\n\n**Example Error Response (HTML body, status 403):**\n\n```text\nIP is not presented in white list\n```\n\n### 500 Internal Server Error - Unknown Error\n\nOccurs when an unexpected server error happens.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Sportsbook free-bet only.** This integration is purpose-built for\n `INTERNAL_FREE_BET` bonuses on the sportsbook product\n (`InternalFreeBetSportsbookCriteria` payload). `winSize` is always `null`,\n `wagering` is always `null`. All limits and rules are encoded inside\n `bonusSize.rule.productRules[].criteria` and `bonusSize.rule.freeBetUseType`. Other\n `bonusType` values and non-sportsbook free-bet criteria may appear in the catalogue\n and should be filtered out client-side.\n\n2. **Real schema values.** `betRule.betTypes` uses the **`BetHashType`** enum with\n lowercase JSON values (`\"single\"`, `\"parlay\"`, `\"system\"`) — the `parlay` value is\n the schema name for accumulator bets. `markets` uses the **`MarketType`** enum\n from the generated SportsbookSchema (lowercase names like `score_1x2`, `score_ou`,\n `score_both_to_score_yes_no`).\n\n3. **Visibility flag handling.** In Mode 1 (catalogue) the operator-side\n `\"Show For Players\"` visibility flag is ignored — partners see the full enabled\n catalogue. In Mode 2 (per-player) the flag is honoured: bonuses with\n `isShownForPlayers: false` are hidden.\n\n4. **Mode 2 player registration side-effect.** When `externalUserId` is unknown to\n Sumstats, the system attempts to register the player automatically before\n evaluating eligibility. Subsequent calls for the same `externalUserId` skip\n this step. If automatic registration fails, the request fails with\n `INVALID_USER` (109).\n\n5. **Polymorphic `__payloadKind` discriminator.** All polymorphic objects\n (`bonusSize`, `criteria`, `freeBetUseType`, `bonusSize.amount`) carry a\n `__payloadKind` field containing the concrete payload kind. Partners must\n discriminate on this field — adding new payload kinds in the future is the\n standard evolution path.\n\n6. **`MoneyBag.system` semantics.** `system` carries the canonical amount in the\n operator's accounting currency. When the player's currency matches an entry in\n `additional`, that override is used directly; otherwise the system entry is\n converted via the operator's currency-pair rates. Partners should prefer the\n `additional` entry matching the player's currency for display.\n\n7. **Currencies and bonus selection.** The `currencies` array on the bonus is the\n set of currencies the bonus supports. In Mode 2, only bonuses whose `currencies`\n array contains the player's currency are returned.\n\n8. **Empty filter list semantics.** `criteria.filters` is an array — an **empty\n array** means \"no narrowing\": the free bet may be staked on any sportsbook event.\n **A non-empty filter list is OR'd:** a stake is allowed when at least one filter\n accepts it.\n\n9. **Empty-vs-null in `betRule`.** `betRule.betTypes: []` and `betRule.markets: []`\n mean \"any\" (no restriction); `betRule.live: null` means \"any live mode\"; numeric /\n integer fields use `null` for \"no restriction\". The semantics differ — empty array\n on `betTypes` / `markets`, `null` on the rest.\n\n10. **`isAutoActivates` impact on the claim flow.** When `isAutoActivates: true`,\n calling `claim-bonus-for-player` immediately moves the player bonus to\n `IN_PROGRESS`. When `false`, the partner must call `activate-player-bonus` within\n `timeForActivationInHours` hours.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 3,\n \"errorMessage\": \"either 'available=true' or 'tag=REGISTRATION' must be supplied\"\n}"},{"id":"ebe219cf-6478-4e69-8f16-725384b4f1e1","name":"fail — invalid user","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"available\": true,\n \"externalUserId\": \"ext_987654321\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/find-available-bonuses","description":"# Endpoint for Finding Available Bonuses\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/find-available-bonuses`\n\n## Description\n\nThis endpoint returns the **internal sportsbook free-bet bonuses** currently offered\nby the operator. Three usage modes are selected via the request body fields:\n\n- **Mode 1 — All available bonuses (catalogue).** `available: true`, `externalUserId`\n omitted. Returns all enabled, in-activity-window bonuses. The operator-side\n `\"Show For Players\"` visibility flag is **ignored** in this mode — the full catalogue\n is exposed so the partner can plan campaigns.\n- **Mode 2 — Available bonuses for a specific player.** `available: true`,\n `externalUserId` set. Returns only the bonuses available *for that player*: per-player\n limits, claim eligibility rules and the operator-side visibility flag are honoured,\n and bonuses already claimed/active for the player are excluded. If the external\n player is unknown to Sumstats, the system attempts to register them automatically\n before evaluating eligibility.\n- **Mode 3 — Registration bonuses only.** `tag: \"REGISTRATION\"` (with or without\n `available`). Returns the subset of bonuses tagged for new-player registration flows.\n\nThe response is **not paginated** — the operator catalogue is bounded (typically tens to\nlow hundreds of enabled bonuses). Each bonus carries a polymorphic free-bet payload\n(`bonusSize.__payloadKind = \"FreeBetSize\"`) describing the substantive offer; the\npartner is expected to discriminate on `__payloadKind` for nested polymorphic objects\n(`criteria`, `freeBetUseType`, `bonusSize.amount`).\n\n> **Scope.** This integration is purpose-built for `INTERNAL_FREE_BET` bonuses on the\n> sportsbook product (`InternalFreeBetSportsbookCriteria` payload). Other bonus types\n> (`CUSTOM`, `FIRST_DEPOSIT`, `EXTERNAL_FREE_BET`, `EXTERNAL_FREE_SPINS_WITH_WAGERING`,\n> `INTERNAL_FREE_SPINS_WITH_WAGERING`, `CASHBACK`) and non-sportsbook free-bet\n> criteria may exist in the operator catalogue but are out of scope for this contract — partners should filter the response to\n> `bonusType: \"INTERNAL_FREE_BET\"` with\n> `bonusSize.rule.productRules[0].criteria.__payloadKind: \"InternalFreeBetSportsbookCriteria\"`\n> client-side.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the brand\n encoded in the HTTP Basic credentials. Used together with `Authorization` for\n credential lookup.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only — partners on the new contract must send `brandId`.\n\n- **available** (boolean, optional) - When `true` activates Mode 1 or Mode 2 selection.\n When omitted, `tag` must be set, otherwise the request is rejected with\n `BAD_REQUEST`.\n\n- **externalUserId** (string, optional) - External player id in the operator system.\n When set, switches the call to Mode 2 (per-player filtering). If the player is\n unknown to Sumstats, the system attempts to register them automatically.\n\n- **tag** (string, optional) - When set, must be `\"REGISTRATION\"` (case-insensitive)\n and switches the call to Mode 3. Any other value is rejected with `BAD_REQUEST`.\n\n## Response Body Description\n\n**Object:**\n\n- **bonuses** (array of objects, required) - List of bonus objects matching the query.\n Empty list when nothing matches. The partner-facing slim shape drops\n internal/operational fields (`descriptionTitle`, `descriptionBonusRules`,\n `fullTermsAndConditions`, `descriptionFiles`, `isShownForPlayers`, `bonusTags`,\n `shareLimitsId`, `eligibilityClaimRulesCompletionInfo`, `notSatisfiedMatchResults`,\n `satisfiedMatchResults`, `operatorId`, `ruleIds`, `removedAt`, `updatedAt`,\n `playerGroupIds`, `bonusOverridableFeatures`).\n\n Each bonus object has the structure documented under **Bonus Fields** below.\n\n### Bonus Fields\n\nThe slim partner-facing bonus shape. Field-by-field semantics:\n\n- **id** (string, required) - Bonus identifier in **UUID v7** format. This is the\n *catalogue* id of the bonus configuration, not a per-player id. Pass to\n `claim-bonus-for-player`, `activate-player-bonus`, `cancel-player-bonus`. Stable\n across partner calls — repeated `find-available-bonuses` requests return the same\n `id` for the same operator-configured bonus until the operator deletes the\n configuration.\n\n- **name** (array of `{locale, translate}`, required) - Localised bonus names. Each\n entry binds a `locale` (BCP-47 / ICU locale code, e.g. `en_US`, `de_DE`) to\n the human-readable bonus name in that locale. Partners should pick the entry\n matching the player's locale; when no exact match exists, fall back to `en_US` or\n the first entry. Bonuses are guaranteed to have **at least one** translation\n (typically `en_US`).\n\n- **bonusType** (enum, required) - High-level bonus kind. **For this integration's\n contract, the relevant value is `INTERNAL_FREE_BET`.** Drives which payload shapes\n appear inside `bonusSize`. Other types may appear in the catalogue but are out of\n scope — partners should filter the response to `bonusType: \"INTERNAL_FREE_BET\"`\n client-side.\n\n- **status** (enum, required) - Lifecycle status of the bonus on the operator side.\n Possible values:\n\n - `NOT_STARTED` - Created and saved but the activity window has not started yet.\n - `SCHEDULED` - Inside the configured activity window but the bonus is scheduled to go active at a later point.\n - `ACTIVE` - Enabled and inside the activity window. Only `ACTIVE` bonuses can be claimed.\n - `DISABLED` - Operator switched the bonus off from the admin panel.\n - `EXPIRED` - Activity window has passed.\n - `REMOVED` - Operator deleted the bonus configuration. Catalogue audits only — not claimable.\n\n Only `ACTIVE` bonuses can be claimed — `find-available-bonuses` does not return\n non-`ACTIVE` bonuses by default; the field is informational for catalogue audits.\n\n- **enabled** (boolean, required) - `false` when the operator has explicitly disabled\n the bonus from the admin panel. A bonus with `status: ACTIVE` and `enabled: false`\n is unavailable for new claims and will not appear in Mode 2 (per-player) responses.\n Mode 1 (catalogue) responses include disabled bonuses for partner audit purposes.\n\n- **promotionCode** (string, optional) - Operator-issued promotion code (e.g.\n `\"500TRYFREEBET\"`, `\"EPL100\"`). When set, the bonus is gated by the code on the\n player-facing surface — players can only claim it through a promo-code flow.\n `null` when the bonus is freely claimable. **Partners using this integration claim\n by `bonusId` directly and bypass the promo-code gate**, but the field is exposed\n so partners can mirror operator-side promo flows on their UI.\n\n- **activityTime** (object, optional) - Activity window. `null` means always on\n (no time gate). The shape mirrors the internal `ActivityTime` record — at most\n one of `timePeriod` / `timeSchedule` is populated:\n\n - **timePeriod** (object, optional) - Continuous activity window.\n - **timeRange** (object, required) - Half-open period.\n - **from** (long, optional) - Start of the window in **epoch millis (UTC)**.\n `null` means open-ended start.\n - **to** (long, optional) - End of the window in **epoch millis (UTC)**.\n `null` means open-ended end.\n - **isShownBeforePeriod** (boolean, required) - Whether the bonus is exposed\n to players before `timeRange.from`.\n - **isShownAfterPeriod** (boolean, required) - Whether the bonus is exposed\n after `timeRange.to`.\n - **shownBeforePeriodMinutes** (long, optional) - How long before\n `timeRange.from` the bonus becomes visible.\n - **shownAfterPeriodMinutes** (long, optional) - How long after\n `timeRange.to` the bonus remains visible.\n - **timeSchedule** (object, optional) - Recurring activity schedule.\n Polymorphic on `__payloadKind`:\n - `HoursOfDayTimeSchedule` — recurring hours-of-day periods (`periods`).\n - `DaysOfWeekTimeSchedule` — recurring per-day-of-week periods\n (`periodsByDay`).\n - `DaysOfMonthTimeSchedule` — recurring per-day-of-month periods\n (`periodsByDay`).\n\n `null` when activity is window-only.\n\n Outside the window the bonus is unclaimable (Sumstats responds with\n `BONUS_NOT_AVAILABLE` (303) on claim).\n\n- **timeForActivationInHours** (integer, optional) - Hours after claim during which\n the player must activate the bonus (i.e. how long the `CLAIMED → IN_PROGRESS`\n transition is allowed). `null` = unlimited (the player bonus stays in `CLAIMED`\n until activation or manual cancel). Used by Sumstats to compute `expiredOnClaimAt`\n on the resulting player bonus. Example: `168` means the player has seven days to\n activate.\n\n- **currencies** (array of strings, required) - Currencies the bonus supports\n (ISO 4217 codes — `TRY`, `EUR`, `USD`, …). The bonus can only be claimed by players\n whose account currency is in this set. In Mode 2, only bonuses whose `currencies`\n array contains the player's currency are returned. Empty array indicates a\n misconfiguration on the operator side.\n\n- **isAutoActivates** (boolean, required) - When `true`, the bonus auto-activates on\n claim — partners do **not** need to call `activate-player-bonus`. The\n `claim-bonus-for-player` response carries `status: \"IN_PROGRESS\"` and a populated\n `activatedAt`. When `false`, the partner must explicitly call `activate-player-bonus`\n within `timeForActivationInHours` hours, or the player bonus expires.\n\n- **bonusSize** (object, required) - Substantive offer payload describing the\n free-bet rule and amount. **For `INTERNAL_FREE_BET` bonuses, `bonusSize.__payloadKind`\n is always `\"FreeBetSize\"`.** See **FreeBetSize** below.\n\n- **winSize** (object, optional) - Cap on potential winnings. **Always `null` for\n `INTERNAL_FREE_BET` bonuses** — the substantive limits are encoded inside the\n free-bet criteria (`bonusSize.rule.productRules[].criteria.maxWinAllowed`).\n\n- **wagering** (object, optional) - Wagering rules. **Always `null` for\n `INTERNAL_FREE_BET` bonuses** — free bets do not have a turnover requirement; the\n free bet either wins, loses, or expires per the criteria rules.\n\n### `bonusSize` — FreeBetSize\n\nFor `INTERNAL_FREE_BET` bonuses, `bonusSize.__payloadKind = \"FreeBetSize\"`. The\n`FreeBetSize` payload has two top-level fields:\n\n- **rule** (object, required) - The free-bet rule — defines per-product criteria,\n free-bet use type, and validity. See **FreeBetRule** below.\n- **amount** (object, optional) - Total monetary value handed to the player as a\n free-bet balance when the bonus is activated. Polymorphic on `__payloadKind`. Two\n practical kinds for free bets:\n\n - **MonetarySize** - Fixed amount.\n\n - **money** (MoneyBag, required) - The free-bet balance. See **MoneyBag** below.\n\n - **PercentageSize** - Percentage of a baseline (rare for free bets).\n\n - **percentage** (number, required) - Percentage value, e.g. `100.0` = 100%.\n - **maxAmount** (MoneyBag, optional) - Upper cap on the resulting balance.\n - **minAmount** (MoneyBag, optional) - Lower floor on the resulting balance.\n\n### `bonusSize.rule` — FreeBetRule\n\n**Object:**\n\n- **productRules** (array of `FreeBetProductRule`, required, length ≥ 1) - Per-product\n free-bet criteria. **For sportsbook free bets there is a single entry with\n `product: \"SPORTS\"`.**\n\n Each `FreeBetProductRule` has:\n\n - **note** (array of `{locale, translate}`, optional) - Operator-supplied note\n describing the rule, localised. `null` when no note was set.\n - **title** (array of `{locale, translate}`, optional) - Operator-supplied title\n for the rule, localised. `null` when no title was set.\n - **product** (string, required) - For this integration's scope, always `\"SPORTS\"`.\n - **criteria** (object, required) - Per-product limit rules. Polymorphic on\n `__payloadKind`. **For sportsbook free bets,\n `criteria.__payloadKind = \"InternalFreeBetSportsbookCriteria\"`.** See\n **InternalFreeBetSportsbookCriteria** below.\n\n- **validityInHours** (integer, required) - Lifetime of the *activated* bonus, in\n hours. `0` = unlimited (the bonus runs until the free-bet balance is exhausted,\n the bet limit hits, or the operator cancels). Maximum supported value ≈ 1 month.\n Used by Sumstats to compute `expiredAt` on the activated player bonus.\n\n- **note** (array of `{locale, translate}`, optional) - Free-form operator note for\n the rule as a whole, localised. `null` when no note was set.\n\n- **freeBetUseType** (object, required) - How the free-bet money composes the\n player's stake. Polymorphic on `__payloadKind`. See **FreeBetUseType union** below.\n\n### `criteria` — InternalFreeBetSportsbookCriteria\n\nFor sportsbook free bets, `criteria.__payloadKind = \"InternalFreeBetSportsbookCriteria\"`.\nTop-level fields:\n\n- **filters** (array of `InternalFreeBetSportsbookFilter`, required) - Filter list\n narrowing where the free bet may be staked. **An empty filter list means \"no\n narrowing\"** (the free bet may be staked on any sportsbook event). Multiple filters\n are OR'd: a stake is allowed if **at least one** filter accepts it. See\n **InternalFreeBetSportsbookFilter** below.\n\n- **minValue** (MoneyBag, optional) - Minimum bet stake required. `null` = no\n minimum. Stakes below this are rejected by the bet placement engine.\n\n- **maxValue** (MoneyBag, optional) - Maximum bet stake allowed. `null` = no\n maximum. Stakes above this are rejected.\n\n- **maxWinAllowed** (MoneyBag, optional) - Per-bet win cap. When set, winnings on a\n single free-bet stake are capped at this amount. `null` = no cap (free bet pays\n out the full computed winnings).\n\n- **maxAmountOfBets** (integer, optional) - Maximum number of bets the player may\n place using the free-bet balance. `null` = unlimited (the bonus runs until the\n free-bet balance is exhausted or expires). Once the limit is hit, the bonus\n transitions to `COMPLETED` automatically.\n\n#### `filters[]` — InternalFreeBetSportsbookFilter\n\nNarrows the events on which the free bet may be staked. **All scalar fields are\nnullable; `null` means \"no restriction on this dimension\".** The filter accepts a\nstake when *every* set field matches the stake's event metadata:\n\n- **sportId** (string, optional) - Restrict to a specific sport (UUID, operator-defined\n — e.g. football, basketball, tennis). `null` = any sport.\n\n- **categoryId** (string, optional) - Restrict to a category — typically a country /\n region inside a sport (UUID, operator-defined — e.g. England, Germany, ATP Tour).\n `null` = any category.\n\n- **tournamentId** (string, optional) - Restrict to a tournament inside a category\n (UUID, operator-defined — e.g. Premier League, Bundesliga, Wimbledon). `null` = any\n tournament.\n\n- **eventId** (string, optional) - Restrict to a single event / match (UUID,\n operator-defined). `null` = any event.\n\n- **markets** (array of `MarketType`, required) - Allow-listed market identifiers\n from the generated `MarketType` enum (lowercase enum names from the SportsbookSchema).\n Examples: `score_1x2`, `score_ou`, `score_dc`, `score_both_to_score_yes_no`,\n `score_ht_ft`, `score_winning_margin`, `score_exact_number`, `corner_1x2`,\n `yellow_card_1x2`. **Empty array means any market.**\n\n- **betRule** (object, optional) - Bet-shape restrictions. **All `betRule` fields\n are nullable; `null` (or empty for set-typed fields) means \"no restriction on this\n dimension\".** A stake is accepted when every set field matches.\n\n - **betTypes** (array of `BetHashType`, required) - Allowed bet types from the\n `BetHashType` enum. The JSON wire form is **lowercase** (set by Jackson\n `@JsonProperty` on the enum). Possible values:\n\n - `single` - A single selection bet.\n - `parlay` - Accumulator bet (multiple selections combined; all must win).\n The `accumulator*` betRule fields below apply only to this bet type.\n - `system` - System bet (combinations of accumulators).\n\n **Empty array means any bet type.**\n\n - **live** (boolean, optional) - `true` = live betting only, `false` = pre-match\n only, `null` = both allowed.\n - **singleMinOdd** (number, optional) - Minimum odd for `single` bets. Ignored\n for non-single bet types. Applied to the bet's single odd at placement time.\n - **accumulatorTotalOdds** (number, optional) - Minimum total odds for a `parlay`\n (the product of all selection odds). Ignored for non-`parlay` bet types.\n - **accumulatorAtLeastOdd** (number, optional) - At least one selection in the\n `parlay` must have an odd ≥ this value. Combined with\n `accumulatorMinOddPerSelection` for fine-grained control.\n - **accumulatorMinNumberOfSelections** (integer, optional) - Minimum number of\n legs (selections) in the `parlay`.\n - **accumulatorMaxNumberOfSelections** (integer, optional) - Maximum number of\n legs in the `parlay`.\n - **accumulatorMinOddPerSelection** (number, optional) - Minimum odd that\n **every** selection in the `parlay` must meet.\n\n### `freeBetUseType` — FreeBetUseType union\n\nDiscriminated by `__payloadKind`. Two concrete kinds:\n\n- **`FreeBetAllBalanceUseType`** - The stake must consist 100% of free-bet money. Real\n money cannot be mixed in.\n\n - **isMustBeStakedAtOnce** (boolean, required) - When `true`, the entire free-bet\n balance must be wagered in a **single** bet (the player cannot split the\n balance across multiple bets). When `false`, the player may place multiple bets\n until the balance is exhausted, subject to `maxAmountOfBets`.\n\n- **`FreeBetPartialBalanceUseType`** - The stake may mix free-bet money with real\n money. Each bet's free-bet portion is bounded.\n\n - **minValue** (MoneyBag, optional) - Minimum free-bet amount per bet. `null` =\n no minimum.\n - **maxValue** (MoneyBag, optional) - Maximum free-bet amount per bet. `null` =\n no maximum.\n\n### `MoneyBag`\n\nShape — examples in this document use only the `system` amount in a single currency:\n\n```json\n{\n \"system\": { \"amount\": \"50000\", \"currency\": \"TRY\" },\n \"additional\": []\n}\n```\n\n- **system** (`{amount, currency}`, required) - The amount in the bonus's currency.\n The `amount` is a **string** (decimal with no implied scaling — the bonus engine\n stores monetary values in raw integer minor-unit form, e.g. `\"50000\"` = 500.00 TRY).\n- **additional** (array, required) - Per-currency overrides for cross-currency\n bonuses. When the player's currency matches an entry's `currency`, the entry's\n `amount` is used directly; otherwise the `system` amount is converted via the\n operator's currency-pair rates. Single-currency bonuses (the common case) emit\n an empty array, as in all examples in this document.\n\n## Request Examples\n\n### Mode 1 — Catalogue lookup\n\n```json\n{\n \"brandId\": 0,\n \"available\": true\n}\n```\n\n### Mode 2 — Available bonuses for a specific player\n\n```json\n{\n \"brandId\": 0,\n \"available\": true,\n \"externalUserId\": \"ext_987654321\"\n}\n```\n\n### Mode 3 — Registration bonuses only\n\n```json\n{\n \"brandId\": 0,\n \"tag\": \"REGISTRATION\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Internal Free Bet (minimal sportsbook)\n\nThe faithful \"500 TRY FREE BET\" bonus from the legacy Bonus API documentation.\n**Demonstrates the unrestricted shape:** `filters[0]` has every dimension `null` /\nempty (any sport, any category, any tournament, any event, any market, any bet type,\nany odds, no selection limits). `freeBetUseType` is `FreeBetAllBalanceUseType` with\n`isMustBeStakedAtOnce: true`, meaning the entire 500 TRY balance must be wagered in a\nsingle bet.\n\n```json\n{\n \"bonuses\": [\n {\n \"id\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"name\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"ACTIVE\",\n \"enabled\": true,\n \"promotionCode\": \"500TRYFREEBET\",\n \"activityTime\": {\n \"timePeriod\": {\n \"timeRange\": {\n \"from\": 1761721205143,\n \"to\": 1764313205143\n },\n \"isShownBeforePeriod\": true,\n \"isShownAfterPeriod\": false,\n \"shownBeforePeriodMinutes\": null,\n \"shownAfterPeriodMinutes\": null\n },\n \"timeSchedule\": null\n },\n \"timeForActivationInHours\": 168,\n \"currencies\": [\n \"TRY\",\n \"EUR\"\n ],\n \"isAutoActivates\": true,\n \"bonusSize\": {\n \"__payloadKind\": \"FreeBetSize\",\n \"rule\": {\n \"productRules\": [\n {\n \"note\": null,\n \"title\": null,\n \"criteria\": {\n \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n \"filters\": [\n {\n \"sportId\": null,\n \"categoryId\": null,\n \"tournamentId\": null,\n \"eventId\": null,\n \"markets\": [],\n \"betRule\": {\n \"betTypes\": [],\n \"live\": null,\n \"singleMinOdd\": null,\n \"accumulatorTotalOdds\": null,\n \"accumulatorAtLeastOdd\": null,\n \"accumulatorMinNumberOfSelections\": null,\n \"accumulatorMinOddPerSelection\": null,\n \"accumulatorMaxNumberOfSelections\": null\n }\n }\n ],\n \"minValue\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxWinAllowed\": null,\n \"maxAmountOfBets\": null\n },\n \"product\": \"SPORTS\"\n }\n ],\n \"validityInHours\": 168,\n \"note\": null,\n \"freeBetUseType\": {\n \"__payloadKind\": \"FreeBetAllBalanceUseType\",\n \"isMustBeStakedAtOnce\": true\n }\n },\n \"amount\": {\n \"__payloadKind\": \"MonetarySize\",\n \"money\": {\n \"system\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"winSize\": null,\n \"wagering\": null\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Internal Free Bet (populated sportsbook)\n\nA 100 TRY free bet for **Premier League pre-match singles and parlays**.\n**Demonstrates every populated dimension using real SportsbookSchema values:**\n\n- Sport / category / tournament gating: `sportId` (Football),\n `categoryId` (England), `tournamentId` (Premier League).\n- Three real `MarketType` values allow-listed:\n `[\"score_1x2\", \"score_ou\", \"score_both_to_score_yes_no\"]`.\n- `betTypes: [\"single\", \"parlay\"]` — uses real `BetHashType` JSON values\n (lowercase via Jackson `@JsonProperty`).\n- `live: false` — pre-match only.\n- `single` bets must have an odd ≥ `1.5`.\n- `parlay` bets must have total odds ≥ `3.0`, between `3` and `10` selections, every\n selection at min odd `1.2`, with at least one selection at min odd `1.3`.\n- Stake band `25 TRY ≤ stake ≤ 100 TRY`, max win `1000 TRY`, max `5` bets.\n- 72-hour validity once activated.\n- `freeBetUseType` is `FreeBetPartialBalanceUseType` with the same `25-100 TRY` bounds\n per bet — meaning the player may combine free-bet money with real money on the\n same stake.\n- `isAutoActivates: false` — the partner must call `activate-player-bonus` after\n claim.\n\n```json\n{\n \"bonuses\": [\n {\n \"id\": \"0192bbb0-1234-7aef-9688-aabbccdd0011\",\n \"name\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet \\u2014 100 TRY\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"ACTIVE\",\n \"enabled\": true,\n \"promotionCode\": \"EPL100\",\n \"activityTime\": {\n \"timePeriod\": {\n \"timeRange\": {\n \"from\": 1761721205143,\n \"to\": 1764313205143\n },\n \"isShownBeforePeriod\": true,\n \"isShownAfterPeriod\": false,\n \"shownBeforePeriodMinutes\": null,\n \"shownAfterPeriodMinutes\": null\n },\n \"timeSchedule\": null\n },\n \"timeForActivationInHours\": 72,\n \"currencies\": [\n \"TRY\"\n ],\n \"isAutoActivates\": false,\n \"bonusSize\": {\n \"__payloadKind\": \"FreeBetSize\",\n \"rule\": {\n \"productRules\": [\n {\n \"note\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League pre-match singles and parlays only.\"\n }\n ],\n \"title\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet\"\n }\n ],\n \"criteria\": {\n \"__payloadKind\": \"InternalFreeBetSportsbookCriteria\",\n \"filters\": [\n {\n \"sportId\": \"0192aaaa-1111-7000-9000-000000000001\",\n \"categoryId\": \"0192aaaa-1111-7000-9000-000000000002\",\n \"tournamentId\": \"0192aaaa-1111-7000-9000-000000000003\",\n \"eventId\": null,\n \"markets\": [\n \"score_1x2\",\n \"score_ou\",\n \"score_both_to_score_yes_no\"\n ],\n \"betRule\": {\n \"betTypes\": [\n \"single\",\n \"parlay\"\n ],\n \"live\": false,\n \"singleMinOdd\": 1.5,\n \"accumulatorTotalOdds\": 3.0,\n \"accumulatorAtLeastOdd\": 1.3,\n \"accumulatorMinNumberOfSelections\": 3,\n \"accumulatorMinOddPerSelection\": 1.2,\n \"accumulatorMaxNumberOfSelections\": 10\n }\n }\n ],\n \"minValue\": {\n \"system\": {\n \"amount\": \"2500\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxWinAllowed\": {\n \"system\": {\n \"amount\": \"100000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxAmountOfBets\": 5\n },\n \"product\": \"SPORTS\"\n }\n ],\n \"validityInHours\": 72,\n \"note\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Pre-match Premier League free bet \\u2014 5 bets max within 72h.\"\n }\n ],\n \"freeBetUseType\": {\n \"__payloadKind\": \"FreeBetPartialBalanceUseType\",\n \"minValue\": {\n \"system\": {\n \"amount\": \"2500\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n },\n \"maxValue\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"amount\": {\n \"__payloadKind\": \"MonetarySize\",\n \"money\": {\n \"system\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"additional\": []\n }\n }\n },\n \"winSize\": null,\n \"wagering\": null\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Empty result\n\n```json\n{\n \"bonuses\": []\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- Both `available` and `tag` omitted.\n- `tag` provided but not equal to `\"REGISTRATION\"` (case-insensitive).\n- Malformed `brandId` (non-integer) or missing `Authorization`.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"either 'available=true' or 'tag=REGISTRATION' must be supplied\"\n}\n```\n\n### 400 Bad Request - Deserialization Error\n\nOccurs when the JSON body cannot be parsed (truncated, invalid escapes, etc.).\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 4,\n \"errorMessage\": \"Failed to deserialize request body\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\nOccurs in Mode 2 when the `externalUserId` cannot be resolved or registered\nautomatically.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\nOccurs when `Authorization` is missing, malformed, or does not match a known brand\ncredential.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 403 Forbidden - IP not whitelisted\n\nOccurs when the request originates from an IP not present in the per-brand allow\nlist. Returned by the gateway, before the application is hit.\n\n**Example Error Response (HTML body, status 403):**\n\n```text\nIP is not presented in white list\n```\n\n### 500 Internal Server Error - Unknown Error\n\nOccurs when an unexpected server error happens.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Sportsbook free-bet only.** This integration is purpose-built for\n `INTERNAL_FREE_BET` bonuses on the sportsbook product\n (`InternalFreeBetSportsbookCriteria` payload). `winSize` is always `null`,\n `wagering` is always `null`. All limits and rules are encoded inside\n `bonusSize.rule.productRules[].criteria` and `bonusSize.rule.freeBetUseType`. Other\n `bonusType` values and non-sportsbook free-bet criteria may appear in the catalogue\n and should be filtered out client-side.\n\n2. **Real schema values.** `betRule.betTypes` uses the **`BetHashType`** enum with\n lowercase JSON values (`\"single\"`, `\"parlay\"`, `\"system\"`) — the `parlay` value is\n the schema name for accumulator bets. `markets` uses the **`MarketType`** enum\n from the generated SportsbookSchema (lowercase names like `score_1x2`, `score_ou`,\n `score_both_to_score_yes_no`).\n\n3. **Visibility flag handling.** In Mode 1 (catalogue) the operator-side\n `\"Show For Players\"` visibility flag is ignored — partners see the full enabled\n catalogue. In Mode 2 (per-player) the flag is honoured: bonuses with\n `isShownForPlayers: false` are hidden.\n\n4. **Mode 2 player registration side-effect.** When `externalUserId` is unknown to\n Sumstats, the system attempts to register the player automatically before\n evaluating eligibility. Subsequent calls for the same `externalUserId` skip\n this step. If automatic registration fails, the request fails with\n `INVALID_USER` (109).\n\n5. **Polymorphic `__payloadKind` discriminator.** All polymorphic objects\n (`bonusSize`, `criteria`, `freeBetUseType`, `bonusSize.amount`) carry a\n `__payloadKind` field containing the concrete payload kind. Partners must\n discriminate on this field — adding new payload kinds in the future is the\n standard evolution path.\n\n6. **`MoneyBag.system` semantics.** `system` carries the canonical amount in the\n operator's accounting currency. When the player's currency matches an entry in\n `additional`, that override is used directly; otherwise the system entry is\n converted via the operator's currency-pair rates. Partners should prefer the\n `additional` entry matching the player's currency for display.\n\n7. **Currencies and bonus selection.** The `currencies` array on the bonus is the\n set of currencies the bonus supports. In Mode 2, only bonuses whose `currencies`\n array contains the player's currency are returned.\n\n8. **Empty filter list semantics.** `criteria.filters` is an array — an **empty\n array** means \"no narrowing\": the free bet may be staked on any sportsbook event.\n **A non-empty filter list is OR'd:** a stake is allowed when at least one filter\n accepts it.\n\n9. **Empty-vs-null in `betRule`.** `betRule.betTypes: []` and `betRule.markets: []`\n mean \"any\" (no restriction); `betRule.live: null` means \"any live mode\"; numeric /\n integer fields use `null` for \"no restriction\". The semantics differ — empty array\n on `betTypes` / `markets`, `null` on the rest.\n\n10. **`isAutoActivates` impact on the claim flow.** When `isAutoActivates: true`,\n calling `claim-bonus-for-player` immediately moves the player bonus to\n `IN_PROGRESS`. When `false`, the partner must call `activate-player-bonus` within\n `timeForActivationInHours` hours.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}"}],"_postman_id":"ff735f49-0e6f-44aa-9cbd-5de8c0a13051"},{"name":"Find Player Bonuses","id":"e44ffde8-9b83-40a8-bfb8-63fe00dc6985","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\n \"CLAIMED\",\n \"IN_PROGRESS\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/find-player-bonuses","description":"

Endpoint for Finding Player Bonuses

Endpoint

POST /external-casino-client/v1/bonus/find-player-bonuses

Description

This endpoint returns the internal sportsbook free-bet player bonuses currently
associated with a given external player, filtered by status. Use it to determine
whether a player has any active or completed free-bet bonuses before deciding whether
to offer a new claim, to drive a \"My Bonuses\" surface on the partner side, or to
reconcile partner-side bookkeeping with Sumstats's record.

The response is not paginated — partners typically hold ≤ a few dozen player
bonuses at a time per player.

Request Body Description

Object:

brandId (integer, required) - Brand id provided by Sumstats. Must match the
brand encoded in the HTTP Basic credentials.
\n
brand (string, optional) - Deprecated alias for brandId. Accepted during the
brand migration window only.
\n
externalUserId (string, required) - External player id in the operator system.
Resolved automatically if unknown to Sumstats.
\n
statuses (array of strings, required, length ≥ 1) - Status filter. The result
contains player bonuses whose current status is any of the values in this array
(OR semantics, equivalent to a SQL IN clause). Possible values:
\n
- CLAIMED - Player bonus is created but not yet activated. Only reachable for
  bonuses where isAutoActivates: false — the player has not yet received a
  free-bet balance.
  \n
- IN_PROGRESS - Active player bonus. The player has a free-bet balance and is
  placing bets towards completion.
  \n
- WON - Wagering bonus finished with a positive outcome and the player was
  rewarded the win amount. Reachable for wagering-style bonuses (e.g. CUSTOM,
  FIRST_DEPOSIT, \\*_FREE_SPINS_WITH_WAGERING) that may surface via legacy
  paths. Pure INTERNAL_FREE_BET bonuses settle directly through the bet
  engine and typically transition to COMPLETED / LOST instead.
  \n
- COMPLETED - The player exhausted the free-bet balance (or hit
  maxAmountOfBets) and the bonus is finished.
  \n
- CANCELLED - Operator (or this integration) explicitly cancelled the player
  bonus. finishedAt is set to the cancellation timestamp.
  \n
- EXPIRED - The bonus's claim window or activity window passed before the
  player exhausted the balance. expiredAt / expiredOnClaimAt is set.
  \n
- LOST - All free-bet stakes settled as losses (and maxAmountOfBets was hit
  or the validity expired with no winning stakes).
  \n
\n
Empty array is rejected with BAD_REQUEST.
\n

Response Body Description

Object:

playerBonuses (array of objects, required) - List of player bonus objects
matching the status filter. Empty list when nothing matches.
\n
Each player bonus object has the structure documented under Player Bonus Fields
below.
\n

Player Bonus Fields

The slim partner-facing player-bonus shape. Internal fields dropped: tinyId,
playerId, snapshotVersion, the heavy bonusSnapshot (replaced by bonusId +
bonusName + bonusType), operator overrides (overriddenBonusAmount,
overriddenDepositAmount, overriddenFreeSpinsCount, overriddenWinAmount,
wonGiven), heldDepositSum, wageringProductsProgress[],
freeBetProductsProgress[], and updatedAt.

Field-by-field semantics:

id (string, required) - Player-bonus identifier (UUID v7). Store this for****reconciliation. Distinct from bonusId — the id is unique per claim, while
bonusId is shared across all players who claimed the same catalogue bonus.
\n
bonusId (string, required) - Underlying bonus id (UUID v7). Refers back to
the bonus catalogue entry returned by find-available-bonuses. Use this to fetch
the catalogue-side rules / criteria when needed.
\n
bonusName (array of {locale, translate}, required) - Localised bonus names
captured at claim time. Snapshot — does not reflect later catalogue edits.
Partners should pick the entry matching the player's locale and fall back to
en_US when no exact match exists.
\n
bonusType (enum, required) - Captured bonusType of the underlying bonus.
For this integration's contract, expect INTERNAL_FREE_BET. Other types may
surface if the player previously claimed via legacy paths.
\n
status (enum, required) - Current player-bonus status. See the list of
possible values above in the request statuses field documentation.
\n
externalPlayerId (string, optional) - Echo of the partner-side user id
supplied at claim. null for player bonuses created via internal flows (e.g.
legacy admin panel, VIP-club rewards).
\n
createdAt (long, required) - Created-at timestamp (epoch millis, UTC)
when the player bonus was claimed.
\n
activatedAt (long, optional) - Activated-at timestamp (epoch millis, UTC).
null while still CLAIMED. For auto-activating bonuses, equals createdAt + Δ
where Δ is small (the activation event is committed immediately after the claim
event).
\n
finishedAt (long, optional) - Finished-at timestamp (epoch millis, UTC).
null while the bonus is CLAIMED or IN_PROGRESS. Set when status becomes
COMPLETED, CANCELLED, EXPIRED, or LOST.
\n
expiredAt (long, optional) - Expiry timestamp (epoch millis, UTC) for the
IN_PROGRESS window. null for unlimited bonuses (validityInHours: 0 on the
rule). Computed as activatedAt + rule.validityInHours × 3600 × 1000.
\n
expiredOnClaimAt (long, optional) - Expiry timestamp (epoch millis, UTC) for
the CLAIMED activation window — i.e. when the player must call activate by.
null after the bonus has been activated. Computed as createdAt + timeForActivationInHours × 3600 × 1000.
\n
isAutoActivates (boolean, required) - Snapshot of the catalogue-side flag at
claim time. Drives whether the partner needs to call activate-player-bonus.
\n
bonusGiven (object, optional) - Awarded free-bet balance in the player's
currency. null while CLAIMED (no money has been credited yet). Once the
bonus is IN_PROGRESS, this reflects the original awarded balance — it does
not decrement as the player places bets (use the bonus wallet balance API
to track real-time consumption).
\n
- amount (string, required) - Amount in raw integer minor-unit form (e.g.
  \"50000\" = 500.00 TRY).
  \n
- currency (string, required) - Currency code, ISO 4217.
  \n
\n
totalWagering (object, optional) - Always null for INTERNAL_FREE_BET
— free bets do not have a turnover requirement. Present only for player bonuses
created from non-free-bet catalogue entries that may surface via legacy paths.
\n
- amount (string, required) - Amount in raw integer minor-unit form.
  \n
- currency (string, required) - Currency code.
  \n
\n
currency (string, required) - Currency the bonus was issued in. Matches the
player's currency at claim time. If the player later switches currency, the
existing player bonus retains its original currency.
\n

Request Examples

Active player bonuses

{\n  \"brandId\": 0,\n  \"externalUserId\": \"ext_987654321\",\n  \"statuses\": [\"CLAIMED\", \"IN_PROGRESS\"]\n}\n\n

Terminal player bonuses (history view)

{\n  \"brandId\": 0,\n  \"externalUserId\": \"ext_987654321\",\n  \"statuses\": [\"COMPLETED\", \"CANCELLED\", \"EXPIRED\", \"LOST\"]\n}\n\n

Single-status query

{\n  \"brandId\": 0,\n  \"externalUserId\": \"ext_987654321\",\n  \"statuses\": [\"IN_PROGRESS\"]\n}\n\n

Response Examples

Successful Response (200 OK) — Active free-bet player bonuses

{\n    \"playerBonuses\": [\n        {\n            \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n            \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n            \"bonusName\": [\n                {\n                    \"locale\": \"en_US\",\n                    \"translate\": \"500 TRY FREE BET\"\n                }\n            ],\n            \"bonusType\": \"INTERNAL_FREE_BET\",\n            \"status\": \"IN_PROGRESS\",\n            \"externalPlayerId\": \"ext_987654321\",\n            \"createdAt\": 1761721205143,\n            \"activatedAt\": 1761724805143,\n            \"finishedAt\": null,\n            \"expiredAt\": null,\n            \"expiredOnClaimAt\": 1762326005143,\n            \"isAutoActivates\": true,\n            \"bonusGiven\": {\n                \"amount\": \"50000\",\n                \"currency\": \"TRY\"\n            },\n            \"totalWagering\": null,\n            \"currency\": \"TRY\"\n        },\n        {\n            \"id\": \"0192f888-aaaa-7e2f-bd44-deadbeef0001\",\n            \"bonusId\": \"0192bbb0-1234-7aef-9688-aabbccdd0011\",\n            \"bonusName\": [\n                {\n                    \"locale\": \"en_US\",\n                    \"translate\": \"Premier League Free Bet \\u2014 100 TRY\"\n                }\n            ],\n            \"bonusType\": \"INTERNAL_FREE_BET\",\n            \"status\": \"IN_PROGRESS\",\n            \"externalPlayerId\": \"ext_987654321\",\n            \"createdAt\": 1761721205143,\n            \"activatedAt\": 1761724805143,\n            \"finishedAt\": null,\n            \"expiredAt\": 1761983205143,\n            \"expiredOnClaimAt\": null,\n            \"isAutoActivates\": false,\n            \"bonusGiven\": {\n                \"amount\": \"10000\",\n                \"currency\": \"TRY\"\n            },\n            \"totalWagering\": null,\n            \"currency\": \"TRY\"\n        }\n    ]\n}\n\n

Successful Response (200 OK) — Empty list

{\n    \"playerBonuses\": []\n}\n\n

Error Responses

400 Bad Request - Request Validation Error

Occurs when request validation fails. Common causes:

statuses array is empty.
\n
statuses contains a value that is not a known PlayerBonusStatus.
\n
externalUserId is blank.
\n

Example Error Response:

{\n    \"errorCode\": 3,\n    \"errorMessage\": \"'statuses' must contain at least one value\"\n}\n\n

400 Bad Request - Deserialization Error

{\n    \"errorCode\": 4,\n    \"errorMessage\": \"Failed to deserialize request body\"\n}\n\n

400 Bad Request - Invalid User

{\n    \"errorCode\": 109,\n    \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n\n

401 Unauthorized - Invalid Credentials

{\n    \"errorCode\": 2,\n    \"errorMessage\": \"Invalid credentials\"\n}\n\n

500 Internal Server Error - Unknown Error

{\n    \"errorCode\": 1,\n    \"errorMessage\": \"Unknown error\"\n}\n\n

Important Notes

Slim shape. Money fields are projected to plain {amount, currency} in the
player's currency — partners do not need the MoneyTransaction system / external
/ currency-pair scaffolding the internal model carries.
\n
Status filter is OR. Multiple values in statuses produce a result containing
bonuses whose current status is any of the values.
\n
Result ordering. Result is sorted by createdAt descending (most recent
first). Partners that need a stable order should sort client-side on id.
\n
Currency. A player bonus is always denominated in a single currency, captured
at claim time. If the player later switches currency, existing player bonuses
retain their original currency.
\n
bonusGiven does not decrement. bonusGiven reflects the original****awarded balance — it does not track real-time consumption as the player places
bets. To observe live free-bet wallet balance, use the bonus-wallet APIs.
\n

Authentication

This endpoint requires HTTP Basic authentication. Per-brand credentials are issued by
Sumstats Support and configured via the operator dashboard. Calls also pass an IP
whitelist — requests originating outside the allow-listed IPs are rejected at the
gateway with HTTP 403.

Authorization: Basic base64(username:password)\nContent-Type: application/json\n\n

Use the brandId body field together with the credentials — Sumstats resolves the brand
from the credentials and validates that the request brandId matches.

\n","urlObject":{"path":["external-casino-client","v1","bonus","find-player-bonuses"],"host":["{apiUrl}"],"query":[],"variable":[]}},"response":[{"id":"b28ddb19-edf6-45f0-9119-799beebbb1ae","name":"success — Active free-bet player bonuses","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\n \"CLAIMED\",\n \"IN_PROGRESS\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/find-player-bonuses","description":"# Endpoint for Finding Player Bonuses\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/find-player-bonuses`\n\n## Description\n\nThis endpoint returns the **internal sportsbook free-bet** player bonuses currently\nassociated with a given external player, filtered by status. Use it to determine\nwhether a player has any active or completed free-bet bonuses before deciding whether\nto offer a new claim, to drive a \"My Bonuses\" surface on the partner side, or to\nreconcile partner-side bookkeeping with Sumstats's record.\n\nThe response is **not paginated** — partners typically hold ≤ a few dozen player\nbonuses at a time per player.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Resolved automatically if unknown to Sumstats.\n\n- **statuses** (array of strings, required, length ≥ 1) - Status filter. The result\n contains player bonuses whose current status is **any** of the values in this array\n (OR semantics, equivalent to a SQL `IN` clause). Possible values:\n\n - `CLAIMED` - Player bonus is created but not yet activated. Only reachable for\n bonuses where `isAutoActivates: false` — the player has not yet received a\n free-bet balance.\n - `IN_PROGRESS` - Active player bonus. The player has a free-bet balance and is\n placing bets towards completion.\n - `WON` - Wagering bonus finished with a positive outcome and the player was\n rewarded the win amount. Reachable for wagering-style bonuses (e.g. `CUSTOM`,\n `FIRST_DEPOSIT`, `*_FREE_SPINS_WITH_WAGERING`) that may surface via legacy\n paths. Pure `INTERNAL_FREE_BET` bonuses settle directly through the bet\n engine and typically transition to `COMPLETED` / `LOST` instead.\n - `COMPLETED` - The player exhausted the free-bet balance (or hit\n `maxAmountOfBets`) and the bonus is finished.\n - `CANCELLED` - Operator (or this integration) explicitly cancelled the player\n bonus. `finishedAt` is set to the cancellation timestamp.\n - `EXPIRED` - The bonus's claim window or activity window passed before the\n player exhausted the balance. `expiredAt` / `expiredOnClaimAt` is set.\n - `LOST` - All free-bet stakes settled as losses (and `maxAmountOfBets` was hit\n or the validity expired with no winning stakes).\n\n Empty array is rejected with `BAD_REQUEST`.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonuses** (array of objects, required) - List of player bonus objects\n matching the status filter. Empty list when nothing matches.\n\n Each player bonus object has the structure documented under **Player Bonus Fields**\n below.\n\n### Player Bonus Fields\n\nThe slim partner-facing player-bonus shape. Internal fields dropped: `tinyId`,\n`playerId`, `snapshotVersion`, the heavy `bonusSnapshot` (replaced by `bonusId` +\n`bonusName` + `bonusType`), operator overrides (`overriddenBonusAmount`,\n`overriddenDepositAmount`, `overriddenFreeSpinsCount`, `overriddenWinAmount`,\n`wonGiven`), `heldDepositSum`, `wageringProductsProgress[]`,\n`freeBetProductsProgress[]`, and `updatedAt`.\n\nField-by-field semantics:\n\n- **id** (string, required) - Player-bonus identifier (UUID v7). **Store this for\n reconciliation.** Distinct from `bonusId` — the `id` is unique per claim, while\n `bonusId` is shared across all players who claimed the same catalogue bonus.\n\n- **bonusId** (string, required) - Underlying bonus id (UUID v7). Refers back to\n the bonus catalogue entry returned by `find-available-bonuses`. Use this to fetch\n the catalogue-side rules / criteria when needed.\n\n- **bonusName** (array of `{locale, translate}`, required) - Localised bonus names\n captured at claim time. **Snapshot — does not reflect later catalogue edits.**\n Partners should pick the entry matching the player's locale and fall back to\n `en_US` when no exact match exists.\n\n- **bonusType** (enum, required) - Captured `bonusType` of the underlying bonus.\n For this integration's contract, expect `INTERNAL_FREE_BET`. Other types may\n surface if the player previously claimed via legacy paths.\n\n- **status** (enum, required) - Current player-bonus status. See the list of\n possible values above in the request `statuses` field documentation.\n\n- **externalPlayerId** (string, optional) - Echo of the partner-side user id\n supplied at claim. `null` for player bonuses created via internal flows (e.g.\n legacy admin panel, VIP-club rewards).\n\n- **createdAt** (long, required) - Created-at timestamp (**epoch millis, UTC**)\n when the player bonus was claimed.\n\n- **activatedAt** (long, optional) - Activated-at timestamp (epoch millis, UTC).\n `null` while still `CLAIMED`. For auto-activating bonuses, equals `createdAt + Δ`\n where Δ is small (the activation event is committed immediately after the claim\n event).\n\n- **finishedAt** (long, optional) - Finished-at timestamp (epoch millis, UTC).\n `null` while the bonus is `CLAIMED` or `IN_PROGRESS`. Set when `status` becomes\n `COMPLETED`, `CANCELLED`, `EXPIRED`, or `LOST`.\n\n- **expiredAt** (long, optional) - Expiry timestamp (epoch millis, UTC) for the\n `IN_PROGRESS` window. `null` for unlimited bonuses (`validityInHours: 0` on the\n rule). Computed as `activatedAt + rule.validityInHours × 3600 × 1000`.\n\n- **expiredOnClaimAt** (long, optional) - Expiry timestamp (epoch millis, UTC) for\n the `CLAIMED` activation window — i.e. when the player must call activate by.\n `null` after the bonus has been activated. Computed as `createdAt +\n timeForActivationInHours × 3600 × 1000`.\n\n- **isAutoActivates** (boolean, required) - Snapshot of the catalogue-side flag at\n claim time. Drives whether the partner needs to call `activate-player-bonus`.\n\n- **bonusGiven** (object, optional) - Awarded **free-bet balance** in the player's\n currency. `null` while `CLAIMED` (no money has been credited yet). Once the\n bonus is `IN_PROGRESS`, this reflects the original awarded balance — it does\n **not** decrement as the player places bets (use the bonus wallet balance API\n to track real-time consumption).\n\n - **amount** (string, required) - Amount in raw integer minor-unit form (e.g.\n `\"50000\"` = 500.00 TRY).\n - **currency** (string, required) - Currency code, ISO 4217.\n\n- **totalWagering** (object, optional) - **Always `null` for `INTERNAL_FREE_BET`**\n — free bets do not have a turnover requirement. Present only for player bonuses\n created from non-free-bet catalogue entries that may surface via legacy paths.\n\n - **amount** (string, required) - Amount in raw integer minor-unit form.\n - **currency** (string, required) - Currency code.\n\n- **currency** (string, required) - Currency the bonus was issued in. Matches the\n player's currency at claim time. If the player later switches currency, the\n existing player bonus retains its original `currency`.\n\n## Request Examples\n\n### Active player bonuses\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\"CLAIMED\", \"IN_PROGRESS\"]\n}\n```\n\n### Terminal player bonuses (history view)\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\"COMPLETED\", \"CANCELLED\", \"EXPIRED\", \"LOST\"]\n}\n```\n\n### Single-status query\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\"IN_PROGRESS\"]\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Active free-bet player bonuses\n\n```json\n{\n \"playerBonuses\": [\n {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n },\n {\n \"id\": \"0192f888-aaaa-7e2f-bd44-deadbeef0001\",\n \"bonusId\": \"0192bbb0-1234-7aef-9688-aabbccdd0011\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet \\u2014 100 TRY\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": 1761983205143,\n \"expiredOnClaimAt\": null,\n \"isAutoActivates\": false,\n \"bonusGiven\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Empty list\n\n```json\n{\n \"playerBonuses\": []\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- `statuses` array is empty.\n- `statuses` contains a value that is not a known `PlayerBonusStatus`.\n- `externalUserId` is blank.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'statuses' must contain at least one value\"\n}\n```\n\n### 400 Bad Request - Deserialization Error\n\n```json\n{\n \"errorCode\": 4,\n \"errorMessage\": \"Failed to deserialize request body\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Slim shape.** Money fields are projected to plain `{amount, currency}` in the\n player's currency — partners do not need the `MoneyTransaction` system / external\n / currency-pair scaffolding the internal model carries.\n\n2. **Status filter is OR.** Multiple values in `statuses` produce a result containing\n bonuses whose current status is **any** of the values.\n\n3. **Result ordering.** Result is sorted by `createdAt` descending (most recent\n first). Partners that need a stable order should sort client-side on `id`.\n\n4. **Currency.** A player bonus is always denominated in a single currency, captured\n at claim time. If the player later switches currency, existing player bonuses\n retain their original `currency`.\n\n5. **`bonusGiven` does not decrement.** `bonusGiven` reflects the **original\n awarded balance** — it does not track real-time consumption as the player places\n bets. To observe live free-bet wallet balance, use the bonus-wallet APIs.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"playerBonuses\": [\n {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n },\n {\n \"id\": \"0192f888-aaaa-7e2f-bd44-deadbeef0001\",\n \"bonusId\": \"0192bbb0-1234-7aef-9688-aabbccdd0011\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet \\u2014 100 TRY\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": 1761983205143,\n \"expiredOnClaimAt\": null,\n \"isAutoActivates\": false,\n \"bonusGiven\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n ]\n}"},{"id":"0998925a-65ac-4223-990c-afef90b3f98f","name":"success — Empty","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\n \"CLAIMED\",\n \"IN_PROGRESS\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/find-player-bonuses","description":"# Endpoint for Finding Player Bonuses\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/find-player-bonuses`\n\n## Description\n\nThis endpoint returns the **internal sportsbook free-bet** player bonuses currently\nassociated with a given external player, filtered by status. Use it to determine\nwhether a player has any active or completed free-bet bonuses before deciding whether\nto offer a new claim, to drive a \"My Bonuses\" surface on the partner side, or to\nreconcile partner-side bookkeeping with Sumstats's record.\n\nThe response is **not paginated** — partners typically hold ≤ a few dozen player\nbonuses at a time per player.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Resolved automatically if unknown to Sumstats.\n\n- **statuses** (array of strings, required, length ≥ 1) - Status filter. The result\n contains player bonuses whose current status is **any** of the values in this array\n (OR semantics, equivalent to a SQL `IN` clause). Possible values:\n\n - `CLAIMED` - Player bonus is created but not yet activated. Only reachable for\n bonuses where `isAutoActivates: false` — the player has not yet received a\n free-bet balance.\n - `IN_PROGRESS` - Active player bonus. The player has a free-bet balance and is\n placing bets towards completion.\n - `WON` - Wagering bonus finished with a positive outcome and the player was\n rewarded the win amount. Reachable for wagering-style bonuses (e.g. `CUSTOM`,\n `FIRST_DEPOSIT`, `*_FREE_SPINS_WITH_WAGERING`) that may surface via legacy\n paths. Pure `INTERNAL_FREE_BET` bonuses settle directly through the bet\n engine and typically transition to `COMPLETED` / `LOST` instead.\n - `COMPLETED` - The player exhausted the free-bet balance (or hit\n `maxAmountOfBets`) and the bonus is finished.\n - `CANCELLED` - Operator (or this integration) explicitly cancelled the player\n bonus. `finishedAt` is set to the cancellation timestamp.\n - `EXPIRED` - The bonus's claim window or activity window passed before the\n player exhausted the balance. `expiredAt` / `expiredOnClaimAt` is set.\n - `LOST` - All free-bet stakes settled as losses (and `maxAmountOfBets` was hit\n or the validity expired with no winning stakes).\n\n Empty array is rejected with `BAD_REQUEST`.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonuses** (array of objects, required) - List of player bonus objects\n matching the status filter. Empty list when nothing matches.\n\n Each player bonus object has the structure documented under **Player Bonus Fields**\n below.\n\n### Player Bonus Fields\n\nThe slim partner-facing player-bonus shape. Internal fields dropped: `tinyId`,\n`playerId`, `snapshotVersion`, the heavy `bonusSnapshot` (replaced by `bonusId` +\n`bonusName` + `bonusType`), operator overrides (`overriddenBonusAmount`,\n`overriddenDepositAmount`, `overriddenFreeSpinsCount`, `overriddenWinAmount`,\n`wonGiven`), `heldDepositSum`, `wageringProductsProgress[]`,\n`freeBetProductsProgress[]`, and `updatedAt`.\n\nField-by-field semantics:\n\n- **id** (string, required) - Player-bonus identifier (UUID v7). **Store this for\n reconciliation.** Distinct from `bonusId` — the `id` is unique per claim, while\n `bonusId` is shared across all players who claimed the same catalogue bonus.\n\n- **bonusId** (string, required) - Underlying bonus id (UUID v7). Refers back to\n the bonus catalogue entry returned by `find-available-bonuses`. Use this to fetch\n the catalogue-side rules / criteria when needed.\n\n- **bonusName** (array of `{locale, translate}`, required) - Localised bonus names\n captured at claim time. **Snapshot — does not reflect later catalogue edits.**\n Partners should pick the entry matching the player's locale and fall back to\n `en_US` when no exact match exists.\n\n- **bonusType** (enum, required) - Captured `bonusType` of the underlying bonus.\n For this integration's contract, expect `INTERNAL_FREE_BET`. Other types may\n surface if the player previously claimed via legacy paths.\n\n- **status** (enum, required) - Current player-bonus status. See the list of\n possible values above in the request `statuses` field documentation.\n\n- **externalPlayerId** (string, optional) - Echo of the partner-side user id\n supplied at claim. `null` for player bonuses created via internal flows (e.g.\n legacy admin panel, VIP-club rewards).\n\n- **createdAt** (long, required) - Created-at timestamp (**epoch millis, UTC**)\n when the player bonus was claimed.\n\n- **activatedAt** (long, optional) - Activated-at timestamp (epoch millis, UTC).\n `null` while still `CLAIMED`. For auto-activating bonuses, equals `createdAt + Δ`\n where Δ is small (the activation event is committed immediately after the claim\n event).\n\n- **finishedAt** (long, optional) - Finished-at timestamp (epoch millis, UTC).\n `null` while the bonus is `CLAIMED` or `IN_PROGRESS`. Set when `status` becomes\n `COMPLETED`, `CANCELLED`, `EXPIRED`, or `LOST`.\n\n- **expiredAt** (long, optional) - Expiry timestamp (epoch millis, UTC) for the\n `IN_PROGRESS` window. `null` for unlimited bonuses (`validityInHours: 0` on the\n rule). Computed as `activatedAt + rule.validityInHours × 3600 × 1000`.\n\n- **expiredOnClaimAt** (long, optional) - Expiry timestamp (epoch millis, UTC) for\n the `CLAIMED` activation window — i.e. when the player must call activate by.\n `null` after the bonus has been activated. Computed as `createdAt +\n timeForActivationInHours × 3600 × 1000`.\n\n- **isAutoActivates** (boolean, required) - Snapshot of the catalogue-side flag at\n claim time. Drives whether the partner needs to call `activate-player-bonus`.\n\n- **bonusGiven** (object, optional) - Awarded **free-bet balance** in the player's\n currency. `null` while `CLAIMED` (no money has been credited yet). Once the\n bonus is `IN_PROGRESS`, this reflects the original awarded balance — it does\n **not** decrement as the player places bets (use the bonus wallet balance API\n to track real-time consumption).\n\n - **amount** (string, required) - Amount in raw integer minor-unit form (e.g.\n `\"50000\"` = 500.00 TRY).\n - **currency** (string, required) - Currency code, ISO 4217.\n\n- **totalWagering** (object, optional) - **Always `null` for `INTERNAL_FREE_BET`**\n — free bets do not have a turnover requirement. Present only for player bonuses\n created from non-free-bet catalogue entries that may surface via legacy paths.\n\n - **amount** (string, required) - Amount in raw integer minor-unit form.\n - **currency** (string, required) - Currency code.\n\n- **currency** (string, required) - Currency the bonus was issued in. Matches the\n player's currency at claim time. If the player later switches currency, the\n existing player bonus retains its original `currency`.\n\n## Request Examples\n\n### Active player bonuses\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\"CLAIMED\", \"IN_PROGRESS\"]\n}\n```\n\n### Terminal player bonuses (history view)\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\"COMPLETED\", \"CANCELLED\", \"EXPIRED\", \"LOST\"]\n}\n```\n\n### Single-status query\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\"IN_PROGRESS\"]\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Active free-bet player bonuses\n\n```json\n{\n \"playerBonuses\": [\n {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n },\n {\n \"id\": \"0192f888-aaaa-7e2f-bd44-deadbeef0001\",\n \"bonusId\": \"0192bbb0-1234-7aef-9688-aabbccdd0011\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet \\u2014 100 TRY\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": 1761983205143,\n \"expiredOnClaimAt\": null,\n \"isAutoActivates\": false,\n \"bonusGiven\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Empty list\n\n```json\n{\n \"playerBonuses\": []\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- `statuses` array is empty.\n- `statuses` contains a value that is not a known `PlayerBonusStatus`.\n- `externalUserId` is blank.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'statuses' must contain at least one value\"\n}\n```\n\n### 400 Bad Request - Deserialization Error\n\n```json\n{\n \"errorCode\": 4,\n \"errorMessage\": \"Failed to deserialize request body\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Slim shape.** Money fields are projected to plain `{amount, currency}` in the\n player's currency — partners do not need the `MoneyTransaction` system / external\n / currency-pair scaffolding the internal model carries.\n\n2. **Status filter is OR.** Multiple values in `statuses` produce a result containing\n bonuses whose current status is **any** of the values.\n\n3. **Result ordering.** Result is sorted by `createdAt` descending (most recent\n first). Partners that need a stable order should sort client-side on `id`.\n\n4. **Currency.** A player bonus is always denominated in a single currency, captured\n at claim time. If the player later switches currency, existing player bonuses\n retain their original `currency`.\n\n5. **`bonusGiven` does not decrement.** `bonusGiven` reflects the **original\n awarded balance** — it does not track real-time consumption as the player places\n bets. To observe live free-bet wallet balance, use the bonus-wallet APIs.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"playerBonuses\": []\n}"},{"id":"4a80aec6-19c2-4ba2-82c7-037cb694f139","name":"fail — empty statuses","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\n \"CLAIMED\",\n \"IN_PROGRESS\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/find-player-bonuses","description":"# Endpoint for Finding Player Bonuses\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/find-player-bonuses`\n\n## Description\n\nThis endpoint returns the **internal sportsbook free-bet** player bonuses currently\nassociated with a given external player, filtered by status. Use it to determine\nwhether a player has any active or completed free-bet bonuses before deciding whether\nto offer a new claim, to drive a \"My Bonuses\" surface on the partner side, or to\nreconcile partner-side bookkeeping with Sumstats's record.\n\nThe response is **not paginated** — partners typically hold ≤ a few dozen player\nbonuses at a time per player.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Resolved automatically if unknown to Sumstats.\n\n- **statuses** (array of strings, required, length ≥ 1) - Status filter. The result\n contains player bonuses whose current status is **any** of the values in this array\n (OR semantics, equivalent to a SQL `IN` clause). Possible values:\n\n - `CLAIMED` - Player bonus is created but not yet activated. Only reachable for\n bonuses where `isAutoActivates: false` — the player has not yet received a\n free-bet balance.\n - `IN_PROGRESS` - Active player bonus. The player has a free-bet balance and is\n placing bets towards completion.\n - `WON` - Wagering bonus finished with a positive outcome and the player was\n rewarded the win amount. Reachable for wagering-style bonuses (e.g. `CUSTOM`,\n `FIRST_DEPOSIT`, `*_FREE_SPINS_WITH_WAGERING`) that may surface via legacy\n paths. Pure `INTERNAL_FREE_BET` bonuses settle directly through the bet\n engine and typically transition to `COMPLETED` / `LOST` instead.\n - `COMPLETED` - The player exhausted the free-bet balance (or hit\n `maxAmountOfBets`) and the bonus is finished.\n - `CANCELLED` - Operator (or this integration) explicitly cancelled the player\n bonus. `finishedAt` is set to the cancellation timestamp.\n - `EXPIRED` - The bonus's claim window or activity window passed before the\n player exhausted the balance. `expiredAt` / `expiredOnClaimAt` is set.\n - `LOST` - All free-bet stakes settled as losses (and `maxAmountOfBets` was hit\n or the validity expired with no winning stakes).\n\n Empty array is rejected with `BAD_REQUEST`.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonuses** (array of objects, required) - List of player bonus objects\n matching the status filter. Empty list when nothing matches.\n\n Each player bonus object has the structure documented under **Player Bonus Fields**\n below.\n\n### Player Bonus Fields\n\nThe slim partner-facing player-bonus shape. Internal fields dropped: `tinyId`,\n`playerId`, `snapshotVersion`, the heavy `bonusSnapshot` (replaced by `bonusId` +\n`bonusName` + `bonusType`), operator overrides (`overriddenBonusAmount`,\n`overriddenDepositAmount`, `overriddenFreeSpinsCount`, `overriddenWinAmount`,\n`wonGiven`), `heldDepositSum`, `wageringProductsProgress[]`,\n`freeBetProductsProgress[]`, and `updatedAt`.\n\nField-by-field semantics:\n\n- **id** (string, required) - Player-bonus identifier (UUID v7). **Store this for\n reconciliation.** Distinct from `bonusId` — the `id` is unique per claim, while\n `bonusId` is shared across all players who claimed the same catalogue bonus.\n\n- **bonusId** (string, required) - Underlying bonus id (UUID v7). Refers back to\n the bonus catalogue entry returned by `find-available-bonuses`. Use this to fetch\n the catalogue-side rules / criteria when needed.\n\n- **bonusName** (array of `{locale, translate}`, required) - Localised bonus names\n captured at claim time. **Snapshot — does not reflect later catalogue edits.**\n Partners should pick the entry matching the player's locale and fall back to\n `en_US` when no exact match exists.\n\n- **bonusType** (enum, required) - Captured `bonusType` of the underlying bonus.\n For this integration's contract, expect `INTERNAL_FREE_BET`. Other types may\n surface if the player previously claimed via legacy paths.\n\n- **status** (enum, required) - Current player-bonus status. See the list of\n possible values above in the request `statuses` field documentation.\n\n- **externalPlayerId** (string, optional) - Echo of the partner-side user id\n supplied at claim. `null` for player bonuses created via internal flows (e.g.\n legacy admin panel, VIP-club rewards).\n\n- **createdAt** (long, required) - Created-at timestamp (**epoch millis, UTC**)\n when the player bonus was claimed.\n\n- **activatedAt** (long, optional) - Activated-at timestamp (epoch millis, UTC).\n `null` while still `CLAIMED`. For auto-activating bonuses, equals `createdAt + Δ`\n where Δ is small (the activation event is committed immediately after the claim\n event).\n\n- **finishedAt** (long, optional) - Finished-at timestamp (epoch millis, UTC).\n `null` while the bonus is `CLAIMED` or `IN_PROGRESS`. Set when `status` becomes\n `COMPLETED`, `CANCELLED`, `EXPIRED`, or `LOST`.\n\n- **expiredAt** (long, optional) - Expiry timestamp (epoch millis, UTC) for the\n `IN_PROGRESS` window. `null` for unlimited bonuses (`validityInHours: 0` on the\n rule). Computed as `activatedAt + rule.validityInHours × 3600 × 1000`.\n\n- **expiredOnClaimAt** (long, optional) - Expiry timestamp (epoch millis, UTC) for\n the `CLAIMED` activation window — i.e. when the player must call activate by.\n `null` after the bonus has been activated. Computed as `createdAt +\n timeForActivationInHours × 3600 × 1000`.\n\n- **isAutoActivates** (boolean, required) - Snapshot of the catalogue-side flag at\n claim time. Drives whether the partner needs to call `activate-player-bonus`.\n\n- **bonusGiven** (object, optional) - Awarded **free-bet balance** in the player's\n currency. `null` while `CLAIMED` (no money has been credited yet). Once the\n bonus is `IN_PROGRESS`, this reflects the original awarded balance — it does\n **not** decrement as the player places bets (use the bonus wallet balance API\n to track real-time consumption).\n\n - **amount** (string, required) - Amount in raw integer minor-unit form (e.g.\n `\"50000\"` = 500.00 TRY).\n - **currency** (string, required) - Currency code, ISO 4217.\n\n- **totalWagering** (object, optional) - **Always `null` for `INTERNAL_FREE_BET`**\n — free bets do not have a turnover requirement. Present only for player bonuses\n created from non-free-bet catalogue entries that may surface via legacy paths.\n\n - **amount** (string, required) - Amount in raw integer minor-unit form.\n - **currency** (string, required) - Currency code.\n\n- **currency** (string, required) - Currency the bonus was issued in. Matches the\n player's currency at claim time. If the player later switches currency, the\n existing player bonus retains its original `currency`.\n\n## Request Examples\n\n### Active player bonuses\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\"CLAIMED\", \"IN_PROGRESS\"]\n}\n```\n\n### Terminal player bonuses (history view)\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\"COMPLETED\", \"CANCELLED\", \"EXPIRED\", \"LOST\"]\n}\n```\n\n### Single-status query\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\"IN_PROGRESS\"]\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Active free-bet player bonuses\n\n```json\n{\n \"playerBonuses\": [\n {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n },\n {\n \"id\": \"0192f888-aaaa-7e2f-bd44-deadbeef0001\",\n \"bonusId\": \"0192bbb0-1234-7aef-9688-aabbccdd0011\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet \\u2014 100 TRY\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": 1761983205143,\n \"expiredOnClaimAt\": null,\n \"isAutoActivates\": false,\n \"bonusGiven\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Empty list\n\n```json\n{\n \"playerBonuses\": []\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- `statuses` array is empty.\n- `statuses` contains a value that is not a known `PlayerBonusStatus`.\n- `externalUserId` is blank.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'statuses' must contain at least one value\"\n}\n```\n\n### 400 Bad Request - Deserialization Error\n\n```json\n{\n \"errorCode\": 4,\n \"errorMessage\": \"Failed to deserialize request body\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Slim shape.** Money fields are projected to plain `{amount, currency}` in the\n player's currency — partners do not need the `MoneyTransaction` system / external\n / currency-pair scaffolding the internal model carries.\n\n2. **Status filter is OR.** Multiple values in `statuses` produce a result containing\n bonuses whose current status is **any** of the values.\n\n3. **Result ordering.** Result is sorted by `createdAt` descending (most recent\n first). Partners that need a stable order should sort client-side on `id`.\n\n4. **Currency.** A player bonus is always denominated in a single currency, captured\n at claim time. If the player later switches currency, existing player bonuses\n retain their original `currency`.\n\n5. **`bonusGiven` does not decrement.** `bonusGiven` reflects the **original\n awarded balance** — it does not track real-time consumption as the player places\n bets. To observe live free-bet wallet balance, use the bonus-wallet APIs.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 3,\n \"errorMessage\": \"'statuses' must contain at least one value\"\n}"},{"id":"fcf0f2d2-e761-40f0-8283-749802fb9d81","name":"fail — invalid user","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\n \"CLAIMED\",\n \"IN_PROGRESS\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/find-player-bonuses","description":"# Endpoint for Finding Player Bonuses\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/find-player-bonuses`\n\n## Description\n\nThis endpoint returns the **internal sportsbook free-bet** player bonuses currently\nassociated with a given external player, filtered by status. Use it to determine\nwhether a player has any active or completed free-bet bonuses before deciding whether\nto offer a new claim, to drive a \"My Bonuses\" surface on the partner side, or to\nreconcile partner-side bookkeeping with Sumstats's record.\n\nThe response is **not paginated** — partners typically hold ≤ a few dozen player\nbonuses at a time per player.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Resolved automatically if unknown to Sumstats.\n\n- **statuses** (array of strings, required, length ≥ 1) - Status filter. The result\n contains player bonuses whose current status is **any** of the values in this array\n (OR semantics, equivalent to a SQL `IN` clause). Possible values:\n\n - `CLAIMED` - Player bonus is created but not yet activated. Only reachable for\n bonuses where `isAutoActivates: false` — the player has not yet received a\n free-bet balance.\n - `IN_PROGRESS` - Active player bonus. The player has a free-bet balance and is\n placing bets towards completion.\n - `WON` - Wagering bonus finished with a positive outcome and the player was\n rewarded the win amount. Reachable for wagering-style bonuses (e.g. `CUSTOM`,\n `FIRST_DEPOSIT`, `*_FREE_SPINS_WITH_WAGERING`) that may surface via legacy\n paths. Pure `INTERNAL_FREE_BET` bonuses settle directly through the bet\n engine and typically transition to `COMPLETED` / `LOST` instead.\n - `COMPLETED` - The player exhausted the free-bet balance (or hit\n `maxAmountOfBets`) and the bonus is finished.\n - `CANCELLED` - Operator (or this integration) explicitly cancelled the player\n bonus. `finishedAt` is set to the cancellation timestamp.\n - `EXPIRED` - The bonus's claim window or activity window passed before the\n player exhausted the balance. `expiredAt` / `expiredOnClaimAt` is set.\n - `LOST` - All free-bet stakes settled as losses (and `maxAmountOfBets` was hit\n or the validity expired with no winning stakes).\n\n Empty array is rejected with `BAD_REQUEST`.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonuses** (array of objects, required) - List of player bonus objects\n matching the status filter. Empty list when nothing matches.\n\n Each player bonus object has the structure documented under **Player Bonus Fields**\n below.\n\n### Player Bonus Fields\n\nThe slim partner-facing player-bonus shape. Internal fields dropped: `tinyId`,\n`playerId`, `snapshotVersion`, the heavy `bonusSnapshot` (replaced by `bonusId` +\n`bonusName` + `bonusType`), operator overrides (`overriddenBonusAmount`,\n`overriddenDepositAmount`, `overriddenFreeSpinsCount`, `overriddenWinAmount`,\n`wonGiven`), `heldDepositSum`, `wageringProductsProgress[]`,\n`freeBetProductsProgress[]`, and `updatedAt`.\n\nField-by-field semantics:\n\n- **id** (string, required) - Player-bonus identifier (UUID v7). **Store this for\n reconciliation.** Distinct from `bonusId` — the `id` is unique per claim, while\n `bonusId` is shared across all players who claimed the same catalogue bonus.\n\n- **bonusId** (string, required) - Underlying bonus id (UUID v7). Refers back to\n the bonus catalogue entry returned by `find-available-bonuses`. Use this to fetch\n the catalogue-side rules / criteria when needed.\n\n- **bonusName** (array of `{locale, translate}`, required) - Localised bonus names\n captured at claim time. **Snapshot — does not reflect later catalogue edits.**\n Partners should pick the entry matching the player's locale and fall back to\n `en_US` when no exact match exists.\n\n- **bonusType** (enum, required) - Captured `bonusType` of the underlying bonus.\n For this integration's contract, expect `INTERNAL_FREE_BET`. Other types may\n surface if the player previously claimed via legacy paths.\n\n- **status** (enum, required) - Current player-bonus status. See the list of\n possible values above in the request `statuses` field documentation.\n\n- **externalPlayerId** (string, optional) - Echo of the partner-side user id\n supplied at claim. `null` for player bonuses created via internal flows (e.g.\n legacy admin panel, VIP-club rewards).\n\n- **createdAt** (long, required) - Created-at timestamp (**epoch millis, UTC**)\n when the player bonus was claimed.\n\n- **activatedAt** (long, optional) - Activated-at timestamp (epoch millis, UTC).\n `null` while still `CLAIMED`. For auto-activating bonuses, equals `createdAt + Δ`\n where Δ is small (the activation event is committed immediately after the claim\n event).\n\n- **finishedAt** (long, optional) - Finished-at timestamp (epoch millis, UTC).\n `null` while the bonus is `CLAIMED` or `IN_PROGRESS`. Set when `status` becomes\n `COMPLETED`, `CANCELLED`, `EXPIRED`, or `LOST`.\n\n- **expiredAt** (long, optional) - Expiry timestamp (epoch millis, UTC) for the\n `IN_PROGRESS` window. `null` for unlimited bonuses (`validityInHours: 0` on the\n rule). Computed as `activatedAt + rule.validityInHours × 3600 × 1000`.\n\n- **expiredOnClaimAt** (long, optional) - Expiry timestamp (epoch millis, UTC) for\n the `CLAIMED` activation window — i.e. when the player must call activate by.\n `null` after the bonus has been activated. Computed as `createdAt +\n timeForActivationInHours × 3600 × 1000`.\n\n- **isAutoActivates** (boolean, required) - Snapshot of the catalogue-side flag at\n claim time. Drives whether the partner needs to call `activate-player-bonus`.\n\n- **bonusGiven** (object, optional) - Awarded **free-bet balance** in the player's\n currency. `null` while `CLAIMED` (no money has been credited yet). Once the\n bonus is `IN_PROGRESS`, this reflects the original awarded balance — it does\n **not** decrement as the player places bets (use the bonus wallet balance API\n to track real-time consumption).\n\n - **amount** (string, required) - Amount in raw integer minor-unit form (e.g.\n `\"50000\"` = 500.00 TRY).\n - **currency** (string, required) - Currency code, ISO 4217.\n\n- **totalWagering** (object, optional) - **Always `null` for `INTERNAL_FREE_BET`**\n — free bets do not have a turnover requirement. Present only for player bonuses\n created from non-free-bet catalogue entries that may surface via legacy paths.\n\n - **amount** (string, required) - Amount in raw integer minor-unit form.\n - **currency** (string, required) - Currency code.\n\n- **currency** (string, required) - Currency the bonus was issued in. Matches the\n player's currency at claim time. If the player later switches currency, the\n existing player bonus retains its original `currency`.\n\n## Request Examples\n\n### Active player bonuses\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\"CLAIMED\", \"IN_PROGRESS\"]\n}\n```\n\n### Terminal player bonuses (history view)\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\"COMPLETED\", \"CANCELLED\", \"EXPIRED\", \"LOST\"]\n}\n```\n\n### Single-status query\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"statuses\": [\"IN_PROGRESS\"]\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Active free-bet player bonuses\n\n```json\n{\n \"playerBonuses\": [\n {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n },\n {\n \"id\": \"0192f888-aaaa-7e2f-bd44-deadbeef0001\",\n \"bonusId\": \"0192bbb0-1234-7aef-9688-aabbccdd0011\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"Premier League Free Bet \\u2014 100 TRY\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": 1761983205143,\n \"expiredOnClaimAt\": null,\n \"isAutoActivates\": false,\n \"bonusGiven\": {\n \"amount\": \"10000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n ]\n}\n```\n\n### Successful Response (200 OK) — Empty list\n\n```json\n{\n \"playerBonuses\": []\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- `statuses` array is empty.\n- `statuses` contains a value that is not a known `PlayerBonusStatus`.\n- `externalUserId` is blank.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'statuses' must contain at least one value\"\n}\n```\n\n### 400 Bad Request - Deserialization Error\n\n```json\n{\n \"errorCode\": 4,\n \"errorMessage\": \"Failed to deserialize request body\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Slim shape.** Money fields are projected to plain `{amount, currency}` in the\n player's currency — partners do not need the `MoneyTransaction` system / external\n / currency-pair scaffolding the internal model carries.\n\n2. **Status filter is OR.** Multiple values in `statuses` produce a result containing\n bonuses whose current status is **any** of the values.\n\n3. **Result ordering.** Result is sorted by `createdAt` descending (most recent\n first). Partners that need a stable order should sort client-side on `id`.\n\n4. **Currency.** A player bonus is always denominated in a single currency, captured\n at claim time. If the player later switches currency, existing player bonuses\n retain their original `currency`.\n\n5. **`bonusGiven` does not decrement.** `bonusGiven` reflects the **original\n awarded balance** — it does not track real-time consumption as the player places\n bets. To observe live free-bet wallet balance, use the bonus-wallet APIs.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}"}],"_postman_id":"e44ffde8-9b83-40a8-bfb8-63fe00dc6985"},{"name":"Claim Bonus for Player","id":"6bf615c6-0848-495a-9ae2-c3b277bba532","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/claim-bonus-for-player","description":"

Endpoint for Claiming a Bonus on Behalf of a Player

Endpoint

POST /external-casino-client/v1/bonus/claim-bonus-for-player

Description

This endpoint claims a specific internal sportsbook free-bet bonus on behalf of an\nexternal player. The exact effect depends on the bonus's isAutoActivates flag:

isAutoActivates: true - The freshly created player-bonus is also activated in\nthe same call. The response carries status: \"IN_PROGRESS\" plus a populated\nactivatedAt and bonusGiven (the awarded free-bet balance).
isAutoActivates: false - The player-bonus is created with status: \"CLAIMED\".\nThe partner must call Activate Player Bonus\nwithin timeForActivationInHours hours to move the player-bonus to IN_PROGRESS —\notherwise it expires (expiredOnClaimAt).

The action is recorded in the bonus action history as a ClaimedByExternalSystem\nentry — the same audit trail used by all partner-driven claims.

If the bonus is not available for this player (limit exceeded, claim rules not\nsatisfied, already-claimed, tag conflict, etc.) the call is rejected with one of the\ndomain-mapped error codes documented below.

Request Body Description

Object:

brandId (integer, required) - Brand id provided by Sumstats. Must match the\nbrand encoded in the HTTP Basic credentials.
\n
brand (string, optional) - Deprecated alias for brandId. Accepted during the\nbrand migration window only.
\n
externalUserId (string, required) - External player id in the operator system.\nResolved automatically if unknown to Sumstats. Cannot be blank.
\n
bonusId (string, required) - UUID of the bonus to claim — typically taken from\na prior Find Available Bonuses response. Must reference an enabled, in-activity-window\nfree-bet bonus that supports the player's currency. Cannot be blank.
\n

Response Body Description

Object:

playerBonus (object, required) - The freshly-created player bonus. Same slim\nshape returned by Find Player Bonuses, Activate, and Cancel — see the\nFind Player Bonuses field reference for the\nfield-by-field description. Notable fields after a successful claim:
\n
- id (string, required) - Player-bonus identifier (UUID v7).\nStore this for reconciliation.
- bonusId (string, required) - Echo of the request bonusId.
- status (enum, required) - \"CLAIMED\" if the catalogue bonus has\nisAutoActivates: false, otherwise \"IN_PROGRESS\".
- createdAt (long, required) - Claim timestamp (epoch millis, UTC).
- activatedAt (long, optional) - Populated only when the bonus auto-activated.
- bonusGiven (object, optional) - Populated when the bonus auto-activated:\nthe awarded free-bet balance in the player's currency. null for CLAIMED.
- expiredOnClaimAt (long, optional) - Activation deadline for CLAIMED\nstatus. null after auto-activation.
\n

Request Example

{\n  \"brandId\": 0,\n  \"externalUserId\": \"ext_987654321\",\n  \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n

Response Examples

Successful Response (200 OK) — Auto-activated free bet

When the underlying free-bet bonus has isAutoActivates: true, the player-bonus is\ncreated and activated in the same call. Note status: \"IN_PROGRESS\", populated\nactivatedAt, and populated bonusGiven (the awarded free-bet balance).

{\n    \"playerBonus\": {\n        \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n        \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n        \"bonusName\": [\n            {\n                \"locale\": \"en_US\",\n                \"translate\": \"500 TRY FREE BET\"\n            }\n        ],\n        \"bonusType\": \"INTERNAL_FREE_BET\",\n        \"status\": \"IN_PROGRESS\",\n        \"externalPlayerId\": \"ext_987654321\",\n        \"createdAt\": 1761721205143,\n        \"activatedAt\": 1761724805143,\n        \"finishedAt\": null,\n        \"expiredAt\": null,\n        \"expiredOnClaimAt\": 1762326005143,\n        \"isAutoActivates\": true,\n        \"bonusGiven\": {\n            \"amount\": \"50000\",\n            \"currency\": \"TRY\"\n        },\n        \"totalWagering\": null,\n        \"currency\": \"TRY\"\n    }\n}\n

Successful Response (200 OK) — Manual-claim free bet (CLAIMED)

When the underlying free-bet bonus has isAutoActivates: false, the player-bonus\nstops at CLAIMED. Note activatedAt: null, bonusGiven: null, and a populated\nexpiredOnClaimAt — the partner must call activate before that timestamp.

{\n    \"playerBonus\": {\n        \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n        \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n        \"bonusName\": [\n            {\n                \"locale\": \"en_US\",\n                \"translate\": \"500 TRY FREE BET\"\n            }\n        ],\n        \"bonusType\": \"INTERNAL_FREE_BET\",\n        \"status\": \"CLAIMED\",\n        \"externalPlayerId\": \"ext_987654321\",\n        \"createdAt\": 1761721205143,\n        \"activatedAt\": null,\n        \"finishedAt\": null,\n        \"expiredAt\": null,\n        \"expiredOnClaimAt\": 1762326005143,\n        \"isAutoActivates\": false,\n        \"bonusGiven\": null,\n        \"totalWagering\": null,\n        \"currency\": \"TRY\"\n    }\n}\n

Error Responses

400 Bad Request - Request Validation Error

Occurs when request validation fails. Common causes:

bonusId is blank or not a valid UUID.
externalUserId is blank.
Missing brandId.

Example Error Response:

{\n    \"errorCode\": 3,\n    \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n

400 Bad Request - Invalid User

Maps to the legacy player_cannot_be_resolved domain code. Occurs when the\nexternalUserId cannot be resolved automatically.

{\n    \"errorCode\": 109,\n    \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n

400 Bad Request - Bonus Not Found

Maps to the legacy bonus.not_found domain code. Occurs when no bonus exists with\nthe given bonusId (or the bonus has been deleted).

{\n    \"errorCode\": 301,\n    \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' not found\"\n}\n

400 Bad Request - Bonus Disabled

Maps to the legacy bonus.disabled domain code. Occurs when the bonus exists but\nthe operator has switched it off (enabled: false).

{\n    \"errorCode\": 302,\n    \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is disabled\"\n}\n

400 Bad Request - Bonus Not Available

Maps to the legacy bonus.not_available domain code. Occurs when the bonus's\nactivityTime window has expired or has not started yet.

{\n    \"errorCode\": 303,\n    \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is not available, activity time has expired\"\n}\n

400 Bad Request - Bonus User Limits Exceeded

Maps to the legacy bonus.user_limits_exceeded domain code. Occurs when the\nplayer-scoped daily / weekly / total claim limit on the bonus would be exceeded.

{\n    \"errorCode\": 304,\n    \"errorMessage\": \"User limits exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n

400 Bad Request - Bonus Total Limits Exceeded

Maps to the legacy bonus.total_limits_exceeded domain code. Occurs when the\noperator-wide total claim limit on the bonus has been hit.

{\n    \"errorCode\": 305,\n    \"errorMessage\": \"Total bonus claim limit exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n

400 Bad Request - Bonus Eligibility Claim Rules Not Satisfied

Maps to the legacy bonus.eligibility_claim_rules_not_satisfied domain code. Occurs\nwhen the bonus has claim rules (deposit thresholds, country gating, age gating,\nprevious-bonus-completion gating, etc.) and the player does not satisfy at least one\nof them.

{\n    \"errorCode\": 306,\n    \"errorMessage\": \"Eligibility claim rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n

400 Bad Request - Player Bonus Already Claimed

Maps to the legacy player_bonus.player_has_already_claimed_this_bonus domain code.\nOccurs when the player has an existing player-bonus for this bonus that is in a\nstatus preventing re-claim (typically CLAIMED or IN_PROGRESS, sometimes also\nCOMPLETED for one-off bonuses).

{\n    \"errorCode\": 307,\n    \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' has already been claimed by this player\"\n}\n

400 Bad Request - Bonus One-Per-Player Tag Violation

Maps to the legacy bonus_tag_validation.already_used_with_one_per_player_tag\ndomain code. Occurs when the bonus has the One Per Player tag and the player has\npreviously claimed any bonus carrying the same tag.

{\n    \"errorCode\": 308,\n    \"errorMessage\": \"Bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' was already used by player with the 'One Per Player' tag\"\n}\n

400 Bad Request - Bonus New-Customer Tag Violation

Maps to the legacy bonus_tag_validation.already_used_bonus_with_new_customer_tag\ndomain code. Occurs when the bonus has the New Customer tag and the player has\npreviously claimed any bonus carrying the same tag.

{\n    \"errorCode\": 309,\n    \"errorMessage\": \"Player has already claimed bonuses with the 'New Customer' tag — bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' cannot be claimed\"\n}\n

401 Unauthorized - Invalid Credentials

{\n    \"errorCode\": 2,\n    \"errorMessage\": \"Invalid credentials\"\n}\n

500 Internal Server Error - Unknown Error

{\n    \"errorCode\": 1,\n    \"errorMessage\": \"Unknown error\"\n}\n

Important Notes

Idempotency. The endpoint is not idempotent. A second claim-bonus-for-player\ncall for the same (externalUserId, bonusId) pair returns\nPLAYER_BONUS_ALREADY_CLAIMED (307), not the previously-created playerBonus.\nUse Find Player Bonuses to fetch the existing player bonus when you need a\nre-read.
\n
Player registration side-effect. When externalUserId is unknown to Sumstats,\nthe system attempts to register the player automatically before evaluating\neligibility. If automatic registration fails, the request fails with\nINVALID_USER (109).
\n
Bonus snapshot. The newly-created player bonus captures a snapshot of the\ncatalogue bonus (bonusSnapshot.id, bonusSnapshot.name,\nbonusSnapshot.bonusType) at claim time. Subsequent edits to the catalogue bonus\ndo not mutate existing player bonuses — partners always see the snapshot the\nplayer was awarded.
\n
Action-history entry. The claim is recorded in the bonus action history as a\nClaimedByExternalSystem entry (actionType: CLAIMED_BY_EXTERNAL_SYSTEM), with\nthe external request id captured for audit. The same entry is used by all\npartner-side claims regardless of bonus type.
\n
Currency selection. The player bonus is denominated in the player's currency\nat claim time. The bonus must support the player's currency (bonus.currencies\ncontains the player currency); otherwise the bonus engine rejects the claim with\nBONUS_NOT_AVAILABLE (303).
\n
Bonus tags affect availability. One Per Player and New Customer tags are\nevaluated together with the catalogue eligibility rules. A bonus with\nNew Customer tag is unclaimable for any player who has previously claimed any\nNew-Customer-tagged bonus regardless of which one.
\n

Authentication

Authorization: Basic base64(username:password)\nContent-Type: application/json\n

Use the brandId body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request brandId matches.

\n","urlObject":{"path":["external-casino-client","v1","bonus","claim-bonus-for-player"],"host":["{apiUrl}"],"query":[],"variable":[]}},"response":[{"id":"df669f33-a45d-4e2b-96e3-bdbc9512adcc","name":"success — Auto-activated free bet","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/claim-bonus-for-player","description":"# Endpoint for Claiming a Bonus on Behalf of a Player\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/claim-bonus-for-player`\n\n## Description\n\nThis endpoint claims a specific **internal sportsbook free-bet** bonus on behalf of an\nexternal player. The exact effect depends on the bonus's `isAutoActivates` flag:\n\n- **`isAutoActivates: true`** - The freshly created player-bonus is also activated in\n the same call. The response carries `status: \"IN_PROGRESS\"` plus a populated\n `activatedAt` and `bonusGiven` (the awarded free-bet balance).\n- **`isAutoActivates: false`** - The player-bonus is created with `status: \"CLAIMED\"`.\n The partner must call [Activate Player Bonus](#endpoint-for-activating-a-player-bonus)\n within `timeForActivationInHours` hours to move the player-bonus to `IN_PROGRESS` —\n otherwise it expires (`expiredOnClaimAt`).\n\nThe action is recorded in the bonus action history as a `ClaimedByExternalSystem`\nentry — the same audit trail used by all partner-driven claims.\n\nIf the bonus is not available for this player (limit exceeded, claim rules not\nsatisfied, already-claimed, tag conflict, etc.) the call is rejected with one of the\ndomain-mapped error codes documented below.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Resolved automatically if unknown to Sumstats. Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus to claim — typically taken from\n a prior Find Available Bonuses response. Must reference an enabled, in-activity-window\n free-bet bonus that supports the player's currency. Cannot be blank.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The freshly-created player bonus. Same slim\n shape returned by Find Player Bonuses, Activate, and Cancel — see the\n [Find Player Bonuses](#endpoint-for-finding-player-bonuses) field reference for the\n field-by-field description. Notable fields after a successful claim:\n\n - **id** (string, required) - Player-bonus identifier (UUID v7).\n **Store this for reconciliation.**\n - **bonusId** (string, required) - Echo of the request `bonusId`.\n - **status** (enum, required) - `\"CLAIMED\"` if the catalogue bonus has\n `isAutoActivates: false`, otherwise `\"IN_PROGRESS\"`.\n - **createdAt** (long, required) - Claim timestamp (epoch millis, UTC).\n - **activatedAt** (long, optional) - Populated only when the bonus auto-activated.\n - **bonusGiven** (object, optional) - Populated when the bonus auto-activated:\n the awarded free-bet balance in the player's currency. `null` for `CLAIMED`.\n - **expiredOnClaimAt** (long, optional) - Activation deadline for `CLAIMED`\n status. `null` after auto-activation.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Auto-activated free bet\n\nWhen the underlying free-bet bonus has `isAutoActivates: true`, the player-bonus is\ncreated and activated in the same call. Note `status: \"IN_PROGRESS\"`, populated\n`activatedAt`, and populated `bonusGiven` (the awarded free-bet balance).\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n### Successful Response (200 OK) — Manual-claim free bet (CLAIMED)\n\nWhen the underlying free-bet bonus has `isAutoActivates: false`, the player-bonus\nstops at `CLAIMED`. Note `activatedAt: null`, `bonusGiven: null`, and a populated\n`expiredOnClaimAt` — the partner must call activate before that timestamp.\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CLAIMED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": null,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": false,\n \"bonusGiven\": null,\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- `bonusId` is blank or not a valid UUID.\n- `externalUserId` is blank.\n- Missing `brandId`.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\nMaps to the legacy `player_cannot_be_resolved` domain code. Occurs when the\n`externalUserId` cannot be resolved automatically.\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Bonus Not Found\n\nMaps to the legacy `bonus.not_found` domain code. Occurs when no bonus exists with\nthe given `bonusId` (or the bonus has been deleted).\n\n```json\n{\n \"errorCode\": 301,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' not found\"\n}\n```\n\n### 400 Bad Request - Bonus Disabled\n\nMaps to the legacy `bonus.disabled` domain code. Occurs when the bonus exists but\nthe operator has switched it off (`enabled: false`).\n\n```json\n{\n \"errorCode\": 302,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is disabled\"\n}\n```\n\n### 400 Bad Request - Bonus Not Available\n\nMaps to the legacy `bonus.not_available` domain code. Occurs when the bonus's\n`activityTime` window has expired or has not started yet.\n\n```json\n{\n \"errorCode\": 303,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is not available, activity time has expired\"\n}\n```\n\n### 400 Bad Request - Bonus User Limits Exceeded\n\nMaps to the legacy `bonus.user_limits_exceeded` domain code. Occurs when the\nplayer-scoped daily / weekly / total claim limit on the bonus would be exceeded.\n\n```json\n{\n \"errorCode\": 304,\n \"errorMessage\": \"User limits exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Bonus Total Limits Exceeded\n\nMaps to the legacy `bonus.total_limits_exceeded` domain code. Occurs when the\noperator-wide total claim limit on the bonus has been hit.\n\n```json\n{\n \"errorCode\": 305,\n \"errorMessage\": \"Total bonus claim limit exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Bonus Eligibility Claim Rules Not Satisfied\n\nMaps to the legacy `bonus.eligibility_claim_rules_not_satisfied` domain code. Occurs\nwhen the bonus has claim rules (deposit thresholds, country gating, age gating,\nprevious-bonus-completion gating, etc.) and the player does not satisfy at least one\nof them.\n\n```json\n{\n \"errorCode\": 306,\n \"errorMessage\": \"Eligibility claim rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Already Claimed\n\nMaps to the legacy `player_bonus.player_has_already_claimed_this_bonus` domain code.\nOccurs when the player has an existing player-bonus for this bonus that is in a\nstatus preventing re-claim (typically `CLAIMED` or `IN_PROGRESS`, sometimes also\n`COMPLETED` for one-off bonuses).\n\n```json\n{\n \"errorCode\": 307,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' has already been claimed by this player\"\n}\n```\n\n### 400 Bad Request - Bonus One-Per-Player Tag Violation\n\nMaps to the legacy `bonus_tag_validation.already_used_with_one_per_player_tag`\ndomain code. Occurs when the bonus has the `One Per Player` tag and the player has\npreviously claimed any bonus carrying the same tag.\n\n```json\n{\n \"errorCode\": 308,\n \"errorMessage\": \"Bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' was already used by player with the 'One Per Player' tag\"\n}\n```\n\n### 400 Bad Request - Bonus New-Customer Tag Violation\n\nMaps to the legacy `bonus_tag_validation.already_used_bonus_with_new_customer_tag`\ndomain code. Occurs when the bonus has the `New Customer` tag and the player has\npreviously claimed any bonus carrying the same tag.\n\n```json\n{\n \"errorCode\": 309,\n \"errorMessage\": \"Player has already claimed bonuses with the 'New Customer' tag — bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' cannot be claimed\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Idempotency.** The endpoint is **not** idempotent. A second `claim-bonus-for-player`\n call for the same `(externalUserId, bonusId)` pair returns\n `PLAYER_BONUS_ALREADY_CLAIMED` (307), not the previously-created `playerBonus`.\n Use Find Player Bonuses to fetch the existing player bonus when you need a\n re-read.\n\n2. **Player registration side-effect.** When `externalUserId` is unknown to Sumstats,\n the system attempts to register the player automatically before evaluating\n eligibility. If automatic registration fails, the request fails with\n `INVALID_USER` (109).\n\n3. **Bonus snapshot.** The newly-created player bonus captures a snapshot of the\n catalogue bonus (`bonusSnapshot.id`, `bonusSnapshot.name`,\n `bonusSnapshot.bonusType`) at claim time. Subsequent edits to the catalogue bonus\n do **not** mutate existing player bonuses — partners always see the snapshot the\n player was awarded.\n\n4. **Action-history entry.** The claim is recorded in the bonus action history as a\n `ClaimedByExternalSystem` entry (`actionType: CLAIMED_BY_EXTERNAL_SYSTEM`), with\n the external request id captured for audit. The same entry is used by all\n partner-side claims regardless of bonus type.\n\n5. **Currency selection.** The player bonus is denominated in the player's currency\n at claim time. The bonus must support the player's currency (`bonus.currencies`\n contains the player currency); otherwise the bonus engine rejects the claim with\n `BONUS_NOT_AVAILABLE` (303).\n\n6. **Bonus tags affect availability.** `One Per Player` and `New Customer` tags are\n evaluated together with the catalogue eligibility rules. A bonus with\n `New Customer` tag is unclaimable for any player who has previously claimed any\n `New-Customer`-tagged bonus regardless of which one.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}"},{"id":"08f5c137-9c3c-45bb-960a-e42b6cbfdd57","name":"success — Manual-claim free bet (CLAIMED)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/claim-bonus-for-player","description":"# Endpoint for Claiming a Bonus on Behalf of a Player\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/claim-bonus-for-player`\n\n## Description\n\nThis endpoint claims a specific **internal sportsbook free-bet** bonus on behalf of an\nexternal player. The exact effect depends on the bonus's `isAutoActivates` flag:\n\n- **`isAutoActivates: true`** - The freshly created player-bonus is also activated in\n the same call. The response carries `status: \"IN_PROGRESS\"` plus a populated\n `activatedAt` and `bonusGiven` (the awarded free-bet balance).\n- **`isAutoActivates: false`** - The player-bonus is created with `status: \"CLAIMED\"`.\n The partner must call [Activate Player Bonus](#endpoint-for-activating-a-player-bonus)\n within `timeForActivationInHours` hours to move the player-bonus to `IN_PROGRESS` —\n otherwise it expires (`expiredOnClaimAt`).\n\nThe action is recorded in the bonus action history as a `ClaimedByExternalSystem`\nentry — the same audit trail used by all partner-driven claims.\n\nIf the bonus is not available for this player (limit exceeded, claim rules not\nsatisfied, already-claimed, tag conflict, etc.) the call is rejected with one of the\ndomain-mapped error codes documented below.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Resolved automatically if unknown to Sumstats. Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus to claim — typically taken from\n a prior Find Available Bonuses response. Must reference an enabled, in-activity-window\n free-bet bonus that supports the player's currency. Cannot be blank.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The freshly-created player bonus. Same slim\n shape returned by Find Player Bonuses, Activate, and Cancel — see the\n [Find Player Bonuses](#endpoint-for-finding-player-bonuses) field reference for the\n field-by-field description. Notable fields after a successful claim:\n\n - **id** (string, required) - Player-bonus identifier (UUID v7).\n **Store this for reconciliation.**\n - **bonusId** (string, required) - Echo of the request `bonusId`.\n - **status** (enum, required) - `\"CLAIMED\"` if the catalogue bonus has\n `isAutoActivates: false`, otherwise `\"IN_PROGRESS\"`.\n - **createdAt** (long, required) - Claim timestamp (epoch millis, UTC).\n - **activatedAt** (long, optional) - Populated only when the bonus auto-activated.\n - **bonusGiven** (object, optional) - Populated when the bonus auto-activated:\n the awarded free-bet balance in the player's currency. `null` for `CLAIMED`.\n - **expiredOnClaimAt** (long, optional) - Activation deadline for `CLAIMED`\n status. `null` after auto-activation.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Auto-activated free bet\n\nWhen the underlying free-bet bonus has `isAutoActivates: true`, the player-bonus is\ncreated and activated in the same call. Note `status: \"IN_PROGRESS\"`, populated\n`activatedAt`, and populated `bonusGiven` (the awarded free-bet balance).\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n### Successful Response (200 OK) — Manual-claim free bet (CLAIMED)\n\nWhen the underlying free-bet bonus has `isAutoActivates: false`, the player-bonus\nstops at `CLAIMED`. Note `activatedAt: null`, `bonusGiven: null`, and a populated\n`expiredOnClaimAt` — the partner must call activate before that timestamp.\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CLAIMED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": null,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": false,\n \"bonusGiven\": null,\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- `bonusId` is blank or not a valid UUID.\n- `externalUserId` is blank.\n- Missing `brandId`.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\nMaps to the legacy `player_cannot_be_resolved` domain code. Occurs when the\n`externalUserId` cannot be resolved automatically.\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Bonus Not Found\n\nMaps to the legacy `bonus.not_found` domain code. Occurs when no bonus exists with\nthe given `bonusId` (or the bonus has been deleted).\n\n```json\n{\n \"errorCode\": 301,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' not found\"\n}\n```\n\n### 400 Bad Request - Bonus Disabled\n\nMaps to the legacy `bonus.disabled` domain code. Occurs when the bonus exists but\nthe operator has switched it off (`enabled: false`).\n\n```json\n{\n \"errorCode\": 302,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is disabled\"\n}\n```\n\n### 400 Bad Request - Bonus Not Available\n\nMaps to the legacy `bonus.not_available` domain code. Occurs when the bonus's\n`activityTime` window has expired or has not started yet.\n\n```json\n{\n \"errorCode\": 303,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is not available, activity time has expired\"\n}\n```\n\n### 400 Bad Request - Bonus User Limits Exceeded\n\nMaps to the legacy `bonus.user_limits_exceeded` domain code. Occurs when the\nplayer-scoped daily / weekly / total claim limit on the bonus would be exceeded.\n\n```json\n{\n \"errorCode\": 304,\n \"errorMessage\": \"User limits exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Bonus Total Limits Exceeded\n\nMaps to the legacy `bonus.total_limits_exceeded` domain code. Occurs when the\noperator-wide total claim limit on the bonus has been hit.\n\n```json\n{\n \"errorCode\": 305,\n \"errorMessage\": \"Total bonus claim limit exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Bonus Eligibility Claim Rules Not Satisfied\n\nMaps to the legacy `bonus.eligibility_claim_rules_not_satisfied` domain code. Occurs\nwhen the bonus has claim rules (deposit thresholds, country gating, age gating,\nprevious-bonus-completion gating, etc.) and the player does not satisfy at least one\nof them.\n\n```json\n{\n \"errorCode\": 306,\n \"errorMessage\": \"Eligibility claim rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Already Claimed\n\nMaps to the legacy `player_bonus.player_has_already_claimed_this_bonus` domain code.\nOccurs when the player has an existing player-bonus for this bonus that is in a\nstatus preventing re-claim (typically `CLAIMED` or `IN_PROGRESS`, sometimes also\n`COMPLETED` for one-off bonuses).\n\n```json\n{\n \"errorCode\": 307,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' has already been claimed by this player\"\n}\n```\n\n### 400 Bad Request - Bonus One-Per-Player Tag Violation\n\nMaps to the legacy `bonus_tag_validation.already_used_with_one_per_player_tag`\ndomain code. Occurs when the bonus has the `One Per Player` tag and the player has\npreviously claimed any bonus carrying the same tag.\n\n```json\n{\n \"errorCode\": 308,\n \"errorMessage\": \"Bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' was already used by player with the 'One Per Player' tag\"\n}\n```\n\n### 400 Bad Request - Bonus New-Customer Tag Violation\n\nMaps to the legacy `bonus_tag_validation.already_used_bonus_with_new_customer_tag`\ndomain code. Occurs when the bonus has the `New Customer` tag and the player has\npreviously claimed any bonus carrying the same tag.\n\n```json\n{\n \"errorCode\": 309,\n \"errorMessage\": \"Player has already claimed bonuses with the 'New Customer' tag — bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' cannot be claimed\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Idempotency.** The endpoint is **not** idempotent. A second `claim-bonus-for-player`\n call for the same `(externalUserId, bonusId)` pair returns\n `PLAYER_BONUS_ALREADY_CLAIMED` (307), not the previously-created `playerBonus`.\n Use Find Player Bonuses to fetch the existing player bonus when you need a\n re-read.\n\n2. **Player registration side-effect.** When `externalUserId` is unknown to Sumstats,\n the system attempts to register the player automatically before evaluating\n eligibility. If automatic registration fails, the request fails with\n `INVALID_USER` (109).\n\n3. **Bonus snapshot.** The newly-created player bonus captures a snapshot of the\n catalogue bonus (`bonusSnapshot.id`, `bonusSnapshot.name`,\n `bonusSnapshot.bonusType`) at claim time. Subsequent edits to the catalogue bonus\n do **not** mutate existing player bonuses — partners always see the snapshot the\n player was awarded.\n\n4. **Action-history entry.** The claim is recorded in the bonus action history as a\n `ClaimedByExternalSystem` entry (`actionType: CLAIMED_BY_EXTERNAL_SYSTEM`), with\n the external request id captured for audit. The same entry is used by all\n partner-side claims regardless of bonus type.\n\n5. **Currency selection.** The player bonus is denominated in the player's currency\n at claim time. The bonus must support the player's currency (`bonus.currencies`\n contains the player currency); otherwise the bonus engine rejects the claim with\n `BONUS_NOT_AVAILABLE` (303).\n\n6. **Bonus tags affect availability.** `One Per Player` and `New Customer` tags are\n evaluated together with the catalogue eligibility rules. A bonus with\n `New Customer` tag is unclaimable for any player who has previously claimed any\n `New-Customer`-tagged bonus regardless of which one.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CLAIMED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": null,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": false,\n \"bonusGiven\": null,\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}"},{"id":"6de5efb1-350c-41de-837a-1dfdc5f32864","name":"fail — already claimed (307)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/claim-bonus-for-player","description":"# Endpoint for Claiming a Bonus on Behalf of a Player\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/claim-bonus-for-player`\n\n## Description\n\nThis endpoint claims a specific **internal sportsbook free-bet** bonus on behalf of an\nexternal player. The exact effect depends on the bonus's `isAutoActivates` flag:\n\n- **`isAutoActivates: true`** - The freshly created player-bonus is also activated in\n the same call. The response carries `status: \"IN_PROGRESS\"` plus a populated\n `activatedAt` and `bonusGiven` (the awarded free-bet balance).\n- **`isAutoActivates: false`** - The player-bonus is created with `status: \"CLAIMED\"`.\n The partner must call [Activate Player Bonus](#endpoint-for-activating-a-player-bonus)\n within `timeForActivationInHours` hours to move the player-bonus to `IN_PROGRESS` —\n otherwise it expires (`expiredOnClaimAt`).\n\nThe action is recorded in the bonus action history as a `ClaimedByExternalSystem`\nentry — the same audit trail used by all partner-driven claims.\n\nIf the bonus is not available for this player (limit exceeded, claim rules not\nsatisfied, already-claimed, tag conflict, etc.) the call is rejected with one of the\ndomain-mapped error codes documented below.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Resolved automatically if unknown to Sumstats. Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus to claim — typically taken from\n a prior Find Available Bonuses response. Must reference an enabled, in-activity-window\n free-bet bonus that supports the player's currency. Cannot be blank.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The freshly-created player bonus. Same slim\n shape returned by Find Player Bonuses, Activate, and Cancel — see the\n [Find Player Bonuses](#endpoint-for-finding-player-bonuses) field reference for the\n field-by-field description. Notable fields after a successful claim:\n\n - **id** (string, required) - Player-bonus identifier (UUID v7).\n **Store this for reconciliation.**\n - **bonusId** (string, required) - Echo of the request `bonusId`.\n - **status** (enum, required) - `\"CLAIMED\"` if the catalogue bonus has\n `isAutoActivates: false`, otherwise `\"IN_PROGRESS\"`.\n - **createdAt** (long, required) - Claim timestamp (epoch millis, UTC).\n - **activatedAt** (long, optional) - Populated only when the bonus auto-activated.\n - **bonusGiven** (object, optional) - Populated when the bonus auto-activated:\n the awarded free-bet balance in the player's currency. `null` for `CLAIMED`.\n - **expiredOnClaimAt** (long, optional) - Activation deadline for `CLAIMED`\n status. `null` after auto-activation.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Auto-activated free bet\n\nWhen the underlying free-bet bonus has `isAutoActivates: true`, the player-bonus is\ncreated and activated in the same call. Note `status: \"IN_PROGRESS\"`, populated\n`activatedAt`, and populated `bonusGiven` (the awarded free-bet balance).\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n### Successful Response (200 OK) — Manual-claim free bet (CLAIMED)\n\nWhen the underlying free-bet bonus has `isAutoActivates: false`, the player-bonus\nstops at `CLAIMED`. Note `activatedAt: null`, `bonusGiven: null`, and a populated\n`expiredOnClaimAt` — the partner must call activate before that timestamp.\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CLAIMED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": null,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": false,\n \"bonusGiven\": null,\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- `bonusId` is blank or not a valid UUID.\n- `externalUserId` is blank.\n- Missing `brandId`.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\nMaps to the legacy `player_cannot_be_resolved` domain code. Occurs when the\n`externalUserId` cannot be resolved automatically.\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Bonus Not Found\n\nMaps to the legacy `bonus.not_found` domain code. Occurs when no bonus exists with\nthe given `bonusId` (or the bonus has been deleted).\n\n```json\n{\n \"errorCode\": 301,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' not found\"\n}\n```\n\n### 400 Bad Request - Bonus Disabled\n\nMaps to the legacy `bonus.disabled` domain code. Occurs when the bonus exists but\nthe operator has switched it off (`enabled: false`).\n\n```json\n{\n \"errorCode\": 302,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is disabled\"\n}\n```\n\n### 400 Bad Request - Bonus Not Available\n\nMaps to the legacy `bonus.not_available` domain code. Occurs when the bonus's\n`activityTime` window has expired or has not started yet.\n\n```json\n{\n \"errorCode\": 303,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is not available, activity time has expired\"\n}\n```\n\n### 400 Bad Request - Bonus User Limits Exceeded\n\nMaps to the legacy `bonus.user_limits_exceeded` domain code. Occurs when the\nplayer-scoped daily / weekly / total claim limit on the bonus would be exceeded.\n\n```json\n{\n \"errorCode\": 304,\n \"errorMessage\": \"User limits exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Bonus Total Limits Exceeded\n\nMaps to the legacy `bonus.total_limits_exceeded` domain code. Occurs when the\noperator-wide total claim limit on the bonus has been hit.\n\n```json\n{\n \"errorCode\": 305,\n \"errorMessage\": \"Total bonus claim limit exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Bonus Eligibility Claim Rules Not Satisfied\n\nMaps to the legacy `bonus.eligibility_claim_rules_not_satisfied` domain code. Occurs\nwhen the bonus has claim rules (deposit thresholds, country gating, age gating,\nprevious-bonus-completion gating, etc.) and the player does not satisfy at least one\nof them.\n\n```json\n{\n \"errorCode\": 306,\n \"errorMessage\": \"Eligibility claim rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Already Claimed\n\nMaps to the legacy `player_bonus.player_has_already_claimed_this_bonus` domain code.\nOccurs when the player has an existing player-bonus for this bonus that is in a\nstatus preventing re-claim (typically `CLAIMED` or `IN_PROGRESS`, sometimes also\n`COMPLETED` for one-off bonuses).\n\n```json\n{\n \"errorCode\": 307,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' has already been claimed by this player\"\n}\n```\n\n### 400 Bad Request - Bonus One-Per-Player Tag Violation\n\nMaps to the legacy `bonus_tag_validation.already_used_with_one_per_player_tag`\ndomain code. Occurs when the bonus has the `One Per Player` tag and the player has\npreviously claimed any bonus carrying the same tag.\n\n```json\n{\n \"errorCode\": 308,\n \"errorMessage\": \"Bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' was already used by player with the 'One Per Player' tag\"\n}\n```\n\n### 400 Bad Request - Bonus New-Customer Tag Violation\n\nMaps to the legacy `bonus_tag_validation.already_used_bonus_with_new_customer_tag`\ndomain code. Occurs when the bonus has the `New Customer` tag and the player has\npreviously claimed any bonus carrying the same tag.\n\n```json\n{\n \"errorCode\": 309,\n \"errorMessage\": \"Player has already claimed bonuses with the 'New Customer' tag — bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' cannot be claimed\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Idempotency.** The endpoint is **not** idempotent. A second `claim-bonus-for-player`\n call for the same `(externalUserId, bonusId)` pair returns\n `PLAYER_BONUS_ALREADY_CLAIMED` (307), not the previously-created `playerBonus`.\n Use Find Player Bonuses to fetch the existing player bonus when you need a\n re-read.\n\n2. **Player registration side-effect.** When `externalUserId` is unknown to Sumstats,\n the system attempts to register the player automatically before evaluating\n eligibility. If automatic registration fails, the request fails with\n `INVALID_USER` (109).\n\n3. **Bonus snapshot.** The newly-created player bonus captures a snapshot of the\n catalogue bonus (`bonusSnapshot.id`, `bonusSnapshot.name`,\n `bonusSnapshot.bonusType`) at claim time. Subsequent edits to the catalogue bonus\n do **not** mutate existing player bonuses — partners always see the snapshot the\n player was awarded.\n\n4. **Action-history entry.** The claim is recorded in the bonus action history as a\n `ClaimedByExternalSystem` entry (`actionType: CLAIMED_BY_EXTERNAL_SYSTEM`), with\n the external request id captured for audit. The same entry is used by all\n partner-side claims regardless of bonus type.\n\n5. **Currency selection.** The player bonus is denominated in the player's currency\n at claim time. The bonus must support the player's currency (`bonus.currencies`\n contains the player currency); otherwise the bonus engine rejects the claim with\n `BONUS_NOT_AVAILABLE` (303).\n\n6. **Bonus tags affect availability.** `One Per Player` and `New Customer` tags are\n evaluated together with the catalogue eligibility rules. A bonus with\n `New Customer` tag is unclaimable for any player who has previously claimed any\n `New-Customer`-tagged bonus regardless of which one.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 307,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' has already been claimed by this player\"\n}"},{"id":"af94ff8f-4a21-4574-8b4a-9c83473b5a94","name":"fail — bonus not found (301)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/claim-bonus-for-player","description":"# Endpoint for Claiming a Bonus on Behalf of a Player\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/claim-bonus-for-player`\n\n## Description\n\nThis endpoint claims a specific **internal sportsbook free-bet** bonus on behalf of an\nexternal player. The exact effect depends on the bonus's `isAutoActivates` flag:\n\n- **`isAutoActivates: true`** - The freshly created player-bonus is also activated in\n the same call. The response carries `status: \"IN_PROGRESS\"` plus a populated\n `activatedAt` and `bonusGiven` (the awarded free-bet balance).\n- **`isAutoActivates: false`** - The player-bonus is created with `status: \"CLAIMED\"`.\n The partner must call [Activate Player Bonus](#endpoint-for-activating-a-player-bonus)\n within `timeForActivationInHours` hours to move the player-bonus to `IN_PROGRESS` —\n otherwise it expires (`expiredOnClaimAt`).\n\nThe action is recorded in the bonus action history as a `ClaimedByExternalSystem`\nentry — the same audit trail used by all partner-driven claims.\n\nIf the bonus is not available for this player (limit exceeded, claim rules not\nsatisfied, already-claimed, tag conflict, etc.) the call is rejected with one of the\ndomain-mapped error codes documented below.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Resolved automatically if unknown to Sumstats. Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus to claim — typically taken from\n a prior Find Available Bonuses response. Must reference an enabled, in-activity-window\n free-bet bonus that supports the player's currency. Cannot be blank.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The freshly-created player bonus. Same slim\n shape returned by Find Player Bonuses, Activate, and Cancel — see the\n [Find Player Bonuses](#endpoint-for-finding-player-bonuses) field reference for the\n field-by-field description. Notable fields after a successful claim:\n\n - **id** (string, required) - Player-bonus identifier (UUID v7).\n **Store this for reconciliation.**\n - **bonusId** (string, required) - Echo of the request `bonusId`.\n - **status** (enum, required) - `\"CLAIMED\"` if the catalogue bonus has\n `isAutoActivates: false`, otherwise `\"IN_PROGRESS\"`.\n - **createdAt** (long, required) - Claim timestamp (epoch millis, UTC).\n - **activatedAt** (long, optional) - Populated only when the bonus auto-activated.\n - **bonusGiven** (object, optional) - Populated when the bonus auto-activated:\n the awarded free-bet balance in the player's currency. `null` for `CLAIMED`.\n - **expiredOnClaimAt** (long, optional) - Activation deadline for `CLAIMED`\n status. `null` after auto-activation.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Auto-activated free bet\n\nWhen the underlying free-bet bonus has `isAutoActivates: true`, the player-bonus is\ncreated and activated in the same call. Note `status: \"IN_PROGRESS\"`, populated\n`activatedAt`, and populated `bonusGiven` (the awarded free-bet balance).\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n### Successful Response (200 OK) — Manual-claim free bet (CLAIMED)\n\nWhen the underlying free-bet bonus has `isAutoActivates: false`, the player-bonus\nstops at `CLAIMED`. Note `activatedAt: null`, `bonusGiven: null`, and a populated\n`expiredOnClaimAt` — the partner must call activate before that timestamp.\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CLAIMED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": null,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": false,\n \"bonusGiven\": null,\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- `bonusId` is blank or not a valid UUID.\n- `externalUserId` is blank.\n- Missing `brandId`.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\nMaps to the legacy `player_cannot_be_resolved` domain code. Occurs when the\n`externalUserId` cannot be resolved automatically.\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Bonus Not Found\n\nMaps to the legacy `bonus.not_found` domain code. Occurs when no bonus exists with\nthe given `bonusId` (or the bonus has been deleted).\n\n```json\n{\n \"errorCode\": 301,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' not found\"\n}\n```\n\n### 400 Bad Request - Bonus Disabled\n\nMaps to the legacy `bonus.disabled` domain code. Occurs when the bonus exists but\nthe operator has switched it off (`enabled: false`).\n\n```json\n{\n \"errorCode\": 302,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is disabled\"\n}\n```\n\n### 400 Bad Request - Bonus Not Available\n\nMaps to the legacy `bonus.not_available` domain code. Occurs when the bonus's\n`activityTime` window has expired or has not started yet.\n\n```json\n{\n \"errorCode\": 303,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is not available, activity time has expired\"\n}\n```\n\n### 400 Bad Request - Bonus User Limits Exceeded\n\nMaps to the legacy `bonus.user_limits_exceeded` domain code. Occurs when the\nplayer-scoped daily / weekly / total claim limit on the bonus would be exceeded.\n\n```json\n{\n \"errorCode\": 304,\n \"errorMessage\": \"User limits exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Bonus Total Limits Exceeded\n\nMaps to the legacy `bonus.total_limits_exceeded` domain code. Occurs when the\noperator-wide total claim limit on the bonus has been hit.\n\n```json\n{\n \"errorCode\": 305,\n \"errorMessage\": \"Total bonus claim limit exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Bonus Eligibility Claim Rules Not Satisfied\n\nMaps to the legacy `bonus.eligibility_claim_rules_not_satisfied` domain code. Occurs\nwhen the bonus has claim rules (deposit thresholds, country gating, age gating,\nprevious-bonus-completion gating, etc.) and the player does not satisfy at least one\nof them.\n\n```json\n{\n \"errorCode\": 306,\n \"errorMessage\": \"Eligibility claim rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Already Claimed\n\nMaps to the legacy `player_bonus.player_has_already_claimed_this_bonus` domain code.\nOccurs when the player has an existing player-bonus for this bonus that is in a\nstatus preventing re-claim (typically `CLAIMED` or `IN_PROGRESS`, sometimes also\n`COMPLETED` for one-off bonuses).\n\n```json\n{\n \"errorCode\": 307,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' has already been claimed by this player\"\n}\n```\n\n### 400 Bad Request - Bonus One-Per-Player Tag Violation\n\nMaps to the legacy `bonus_tag_validation.already_used_with_one_per_player_tag`\ndomain code. Occurs when the bonus has the `One Per Player` tag and the player has\npreviously claimed any bonus carrying the same tag.\n\n```json\n{\n \"errorCode\": 308,\n \"errorMessage\": \"Bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' was already used by player with the 'One Per Player' tag\"\n}\n```\n\n### 400 Bad Request - Bonus New-Customer Tag Violation\n\nMaps to the legacy `bonus_tag_validation.already_used_bonus_with_new_customer_tag`\ndomain code. Occurs when the bonus has the `New Customer` tag and the player has\npreviously claimed any bonus carrying the same tag.\n\n```json\n{\n \"errorCode\": 309,\n \"errorMessage\": \"Player has already claimed bonuses with the 'New Customer' tag — bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' cannot be claimed\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Idempotency.** The endpoint is **not** idempotent. A second `claim-bonus-for-player`\n call for the same `(externalUserId, bonusId)` pair returns\n `PLAYER_BONUS_ALREADY_CLAIMED` (307), not the previously-created `playerBonus`.\n Use Find Player Bonuses to fetch the existing player bonus when you need a\n re-read.\n\n2. **Player registration side-effect.** When `externalUserId` is unknown to Sumstats,\n the system attempts to register the player automatically before evaluating\n eligibility. If automatic registration fails, the request fails with\n `INVALID_USER` (109).\n\n3. **Bonus snapshot.** The newly-created player bonus captures a snapshot of the\n catalogue bonus (`bonusSnapshot.id`, `bonusSnapshot.name`,\n `bonusSnapshot.bonusType`) at claim time. Subsequent edits to the catalogue bonus\n do **not** mutate existing player bonuses — partners always see the snapshot the\n player was awarded.\n\n4. **Action-history entry.** The claim is recorded in the bonus action history as a\n `ClaimedByExternalSystem` entry (`actionType: CLAIMED_BY_EXTERNAL_SYSTEM`), with\n the external request id captured for audit. The same entry is used by all\n partner-side claims regardless of bonus type.\n\n5. **Currency selection.** The player bonus is denominated in the player's currency\n at claim time. The bonus must support the player's currency (`bonus.currencies`\n contains the player currency); otherwise the bonus engine rejects the claim with\n `BONUS_NOT_AVAILABLE` (303).\n\n6. **Bonus tags affect availability.** `One Per Player` and `New Customer` tags are\n evaluated together with the catalogue eligibility rules. A bonus with\n `New Customer` tag is unclaimable for any player who has previously claimed any\n `New-Customer`-tagged bonus regardless of which one.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 301,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' not found\"\n}"},{"id":"175b9e33-3ee9-4c23-a0b8-27f18ffce6d4","name":"fail — eligibility rules (306)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/claim-bonus-for-player","description":"# Endpoint for Claiming a Bonus on Behalf of a Player\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/claim-bonus-for-player`\n\n## Description\n\nThis endpoint claims a specific **internal sportsbook free-bet** bonus on behalf of an\nexternal player. The exact effect depends on the bonus's `isAutoActivates` flag:\n\n- **`isAutoActivates: true`** - The freshly created player-bonus is also activated in\n the same call. The response carries `status: \"IN_PROGRESS\"` plus a populated\n `activatedAt` and `bonusGiven` (the awarded free-bet balance).\n- **`isAutoActivates: false`** - The player-bonus is created with `status: \"CLAIMED\"`.\n The partner must call [Activate Player Bonus](#endpoint-for-activating-a-player-bonus)\n within `timeForActivationInHours` hours to move the player-bonus to `IN_PROGRESS` —\n otherwise it expires (`expiredOnClaimAt`).\n\nThe action is recorded in the bonus action history as a `ClaimedByExternalSystem`\nentry — the same audit trail used by all partner-driven claims.\n\nIf the bonus is not available for this player (limit exceeded, claim rules not\nsatisfied, already-claimed, tag conflict, etc.) the call is rejected with one of the\ndomain-mapped error codes documented below.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Resolved automatically if unknown to Sumstats. Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus to claim — typically taken from\n a prior Find Available Bonuses response. Must reference an enabled, in-activity-window\n free-bet bonus that supports the player's currency. Cannot be blank.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The freshly-created player bonus. Same slim\n shape returned by Find Player Bonuses, Activate, and Cancel — see the\n [Find Player Bonuses](#endpoint-for-finding-player-bonuses) field reference for the\n field-by-field description. Notable fields after a successful claim:\n\n - **id** (string, required) - Player-bonus identifier (UUID v7).\n **Store this for reconciliation.**\n - **bonusId** (string, required) - Echo of the request `bonusId`.\n - **status** (enum, required) - `\"CLAIMED\"` if the catalogue bonus has\n `isAutoActivates: false`, otherwise `\"IN_PROGRESS\"`.\n - **createdAt** (long, required) - Claim timestamp (epoch millis, UTC).\n - **activatedAt** (long, optional) - Populated only when the bonus auto-activated.\n - **bonusGiven** (object, optional) - Populated when the bonus auto-activated:\n the awarded free-bet balance in the player's currency. `null` for `CLAIMED`.\n - **expiredOnClaimAt** (long, optional) - Activation deadline for `CLAIMED`\n status. `null` after auto-activation.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Auto-activated free bet\n\nWhen the underlying free-bet bonus has `isAutoActivates: true`, the player-bonus is\ncreated and activated in the same call. Note `status: \"IN_PROGRESS\"`, populated\n`activatedAt`, and populated `bonusGiven` (the awarded free-bet balance).\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n### Successful Response (200 OK) — Manual-claim free bet (CLAIMED)\n\nWhen the underlying free-bet bonus has `isAutoActivates: false`, the player-bonus\nstops at `CLAIMED`. Note `activatedAt: null`, `bonusGiven: null`, and a populated\n`expiredOnClaimAt` — the partner must call activate before that timestamp.\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CLAIMED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": null,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": false,\n \"bonusGiven\": null,\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- `bonusId` is blank or not a valid UUID.\n- `externalUserId` is blank.\n- Missing `brandId`.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\nMaps to the legacy `player_cannot_be_resolved` domain code. Occurs when the\n`externalUserId` cannot be resolved automatically.\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Bonus Not Found\n\nMaps to the legacy `bonus.not_found` domain code. Occurs when no bonus exists with\nthe given `bonusId` (or the bonus has been deleted).\n\n```json\n{\n \"errorCode\": 301,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' not found\"\n}\n```\n\n### 400 Bad Request - Bonus Disabled\n\nMaps to the legacy `bonus.disabled` domain code. Occurs when the bonus exists but\nthe operator has switched it off (`enabled: false`).\n\n```json\n{\n \"errorCode\": 302,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is disabled\"\n}\n```\n\n### 400 Bad Request - Bonus Not Available\n\nMaps to the legacy `bonus.not_available` domain code. Occurs when the bonus's\n`activityTime` window has expired or has not started yet.\n\n```json\n{\n \"errorCode\": 303,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is not available, activity time has expired\"\n}\n```\n\n### 400 Bad Request - Bonus User Limits Exceeded\n\nMaps to the legacy `bonus.user_limits_exceeded` domain code. Occurs when the\nplayer-scoped daily / weekly / total claim limit on the bonus would be exceeded.\n\n```json\n{\n \"errorCode\": 304,\n \"errorMessage\": \"User limits exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Bonus Total Limits Exceeded\n\nMaps to the legacy `bonus.total_limits_exceeded` domain code. Occurs when the\noperator-wide total claim limit on the bonus has been hit.\n\n```json\n{\n \"errorCode\": 305,\n \"errorMessage\": \"Total bonus claim limit exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Bonus Eligibility Claim Rules Not Satisfied\n\nMaps to the legacy `bonus.eligibility_claim_rules_not_satisfied` domain code. Occurs\nwhen the bonus has claim rules (deposit thresholds, country gating, age gating,\nprevious-bonus-completion gating, etc.) and the player does not satisfy at least one\nof them.\n\n```json\n{\n \"errorCode\": 306,\n \"errorMessage\": \"Eligibility claim rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Already Claimed\n\nMaps to the legacy `player_bonus.player_has_already_claimed_this_bonus` domain code.\nOccurs when the player has an existing player-bonus for this bonus that is in a\nstatus preventing re-claim (typically `CLAIMED` or `IN_PROGRESS`, sometimes also\n`COMPLETED` for one-off bonuses).\n\n```json\n{\n \"errorCode\": 307,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' has already been claimed by this player\"\n}\n```\n\n### 400 Bad Request - Bonus One-Per-Player Tag Violation\n\nMaps to the legacy `bonus_tag_validation.already_used_with_one_per_player_tag`\ndomain code. Occurs when the bonus has the `One Per Player` tag and the player has\npreviously claimed any bonus carrying the same tag.\n\n```json\n{\n \"errorCode\": 308,\n \"errorMessage\": \"Bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' was already used by player with the 'One Per Player' tag\"\n}\n```\n\n### 400 Bad Request - Bonus New-Customer Tag Violation\n\nMaps to the legacy `bonus_tag_validation.already_used_bonus_with_new_customer_tag`\ndomain code. Occurs when the bonus has the `New Customer` tag and the player has\npreviously claimed any bonus carrying the same tag.\n\n```json\n{\n \"errorCode\": 309,\n \"errorMessage\": \"Player has already claimed bonuses with the 'New Customer' tag — bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' cannot be claimed\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Idempotency.** The endpoint is **not** idempotent. A second `claim-bonus-for-player`\n call for the same `(externalUserId, bonusId)` pair returns\n `PLAYER_BONUS_ALREADY_CLAIMED` (307), not the previously-created `playerBonus`.\n Use Find Player Bonuses to fetch the existing player bonus when you need a\n re-read.\n\n2. **Player registration side-effect.** When `externalUserId` is unknown to Sumstats,\n the system attempts to register the player automatically before evaluating\n eligibility. If automatic registration fails, the request fails with\n `INVALID_USER` (109).\n\n3. **Bonus snapshot.** The newly-created player bonus captures a snapshot of the\n catalogue bonus (`bonusSnapshot.id`, `bonusSnapshot.name`,\n `bonusSnapshot.bonusType`) at claim time. Subsequent edits to the catalogue bonus\n do **not** mutate existing player bonuses — partners always see the snapshot the\n player was awarded.\n\n4. **Action-history entry.** The claim is recorded in the bonus action history as a\n `ClaimedByExternalSystem` entry (`actionType: CLAIMED_BY_EXTERNAL_SYSTEM`), with\n the external request id captured for audit. The same entry is used by all\n partner-side claims regardless of bonus type.\n\n5. **Currency selection.** The player bonus is denominated in the player's currency\n at claim time. The bonus must support the player's currency (`bonus.currencies`\n contains the player currency); otherwise the bonus engine rejects the claim with\n `BONUS_NOT_AVAILABLE` (303).\n\n6. **Bonus tags affect availability.** `One Per Player` and `New Customer` tags are\n evaluated together with the catalogue eligibility rules. A bonus with\n `New Customer` tag is unclaimable for any player who has previously claimed any\n `New-Customer`-tagged bonus regardless of which one.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 306,\n \"errorMessage\": \"Eligibility claim rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}"},{"id":"18701320-e449-4059-8e1e-bb6f3aeda704","name":"fail — new-customer tag (309)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/claim-bonus-for-player","description":"# Endpoint for Claiming a Bonus on Behalf of a Player\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/claim-bonus-for-player`\n\n## Description\n\nThis endpoint claims a specific **internal sportsbook free-bet** bonus on behalf of an\nexternal player. The exact effect depends on the bonus's `isAutoActivates` flag:\n\n- **`isAutoActivates: true`** - The freshly created player-bonus is also activated in\n the same call. The response carries `status: \"IN_PROGRESS\"` plus a populated\n `activatedAt` and `bonusGiven` (the awarded free-bet balance).\n- **`isAutoActivates: false`** - The player-bonus is created with `status: \"CLAIMED\"`.\n The partner must call [Activate Player Bonus](#endpoint-for-activating-a-player-bonus)\n within `timeForActivationInHours` hours to move the player-bonus to `IN_PROGRESS` —\n otherwise it expires (`expiredOnClaimAt`).\n\nThe action is recorded in the bonus action history as a `ClaimedByExternalSystem`\nentry — the same audit trail used by all partner-driven claims.\n\nIf the bonus is not available for this player (limit exceeded, claim rules not\nsatisfied, already-claimed, tag conflict, etc.) the call is rejected with one of the\ndomain-mapped error codes documented below.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Resolved automatically if unknown to Sumstats. Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus to claim — typically taken from\n a prior Find Available Bonuses response. Must reference an enabled, in-activity-window\n free-bet bonus that supports the player's currency. Cannot be blank.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The freshly-created player bonus. Same slim\n shape returned by Find Player Bonuses, Activate, and Cancel — see the\n [Find Player Bonuses](#endpoint-for-finding-player-bonuses) field reference for the\n field-by-field description. Notable fields after a successful claim:\n\n - **id** (string, required) - Player-bonus identifier (UUID v7).\n **Store this for reconciliation.**\n - **bonusId** (string, required) - Echo of the request `bonusId`.\n - **status** (enum, required) - `\"CLAIMED\"` if the catalogue bonus has\n `isAutoActivates: false`, otherwise `\"IN_PROGRESS\"`.\n - **createdAt** (long, required) - Claim timestamp (epoch millis, UTC).\n - **activatedAt** (long, optional) - Populated only when the bonus auto-activated.\n - **bonusGiven** (object, optional) - Populated when the bonus auto-activated:\n the awarded free-bet balance in the player's currency. `null` for `CLAIMED`.\n - **expiredOnClaimAt** (long, optional) - Activation deadline for `CLAIMED`\n status. `null` after auto-activation.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Auto-activated free bet\n\nWhen the underlying free-bet bonus has `isAutoActivates: true`, the player-bonus is\ncreated and activated in the same call. Note `status: \"IN_PROGRESS\"`, populated\n`activatedAt`, and populated `bonusGiven` (the awarded free-bet balance).\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n### Successful Response (200 OK) — Manual-claim free bet (CLAIMED)\n\nWhen the underlying free-bet bonus has `isAutoActivates: false`, the player-bonus\nstops at `CLAIMED`. Note `activatedAt: null`, `bonusGiven: null`, and a populated\n`expiredOnClaimAt` — the partner must call activate before that timestamp.\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CLAIMED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": null,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": false,\n \"bonusGiven\": null,\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\nOccurs when request validation fails. Common causes:\n\n- `bonusId` is blank or not a valid UUID.\n- `externalUserId` is blank.\n- Missing `brandId`.\n\n**Example Error Response:**\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\nMaps to the legacy `player_cannot_be_resolved` domain code. Occurs when the\n`externalUserId` cannot be resolved automatically.\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Bonus Not Found\n\nMaps to the legacy `bonus.not_found` domain code. Occurs when no bonus exists with\nthe given `bonusId` (or the bonus has been deleted).\n\n```json\n{\n \"errorCode\": 301,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' not found\"\n}\n```\n\n### 400 Bad Request - Bonus Disabled\n\nMaps to the legacy `bonus.disabled` domain code. Occurs when the bonus exists but\nthe operator has switched it off (`enabled: false`).\n\n```json\n{\n \"errorCode\": 302,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is disabled\"\n}\n```\n\n### 400 Bad Request - Bonus Not Available\n\nMaps to the legacy `bonus.not_available` domain code. Occurs when the bonus's\n`activityTime` window has expired or has not started yet.\n\n```json\n{\n \"errorCode\": 303,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' is not available, activity time has expired\"\n}\n```\n\n### 400 Bad Request - Bonus User Limits Exceeded\n\nMaps to the legacy `bonus.user_limits_exceeded` domain code. Occurs when the\nplayer-scoped daily / weekly / total claim limit on the bonus would be exceeded.\n\n```json\n{\n \"errorCode\": 304,\n \"errorMessage\": \"User limits exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Bonus Total Limits Exceeded\n\nMaps to the legacy `bonus.total_limits_exceeded` domain code. Occurs when the\noperator-wide total claim limit on the bonus has been hit.\n\n```json\n{\n \"errorCode\": 305,\n \"errorMessage\": \"Total bonus claim limit exceeded for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Bonus Eligibility Claim Rules Not Satisfied\n\nMaps to the legacy `bonus.eligibility_claim_rules_not_satisfied` domain code. Occurs\nwhen the bonus has claim rules (deposit thresholds, country gating, age gating,\nprevious-bonus-completion gating, etc.) and the player does not satisfy at least one\nof them.\n\n```json\n{\n \"errorCode\": 306,\n \"errorMessage\": \"Eligibility claim rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Already Claimed\n\nMaps to the legacy `player_bonus.player_has_already_claimed_this_bonus` domain code.\nOccurs when the player has an existing player-bonus for this bonus that is in a\nstatus preventing re-claim (typically `CLAIMED` or `IN_PROGRESS`, sometimes also\n`COMPLETED` for one-off bonuses).\n\n```json\n{\n \"errorCode\": 307,\n \"errorMessage\": \"Bonus with id '0192f721-29ae-7aef-9688-7c8bc5508b88' has already been claimed by this player\"\n}\n```\n\n### 400 Bad Request - Bonus One-Per-Player Tag Violation\n\nMaps to the legacy `bonus_tag_validation.already_used_with_one_per_player_tag`\ndomain code. Occurs when the bonus has the `One Per Player` tag and the player has\npreviously claimed any bonus carrying the same tag.\n\n```json\n{\n \"errorCode\": 308,\n \"errorMessage\": \"Bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' was already used by player with the 'One Per Player' tag\"\n}\n```\n\n### 400 Bad Request - Bonus New-Customer Tag Violation\n\nMaps to the legacy `bonus_tag_validation.already_used_bonus_with_new_customer_tag`\ndomain code. Occurs when the bonus has the `New Customer` tag and the player has\npreviously claimed any bonus carrying the same tag.\n\n```json\n{\n \"errorCode\": 309,\n \"errorMessage\": \"Player has already claimed bonuses with the 'New Customer' tag — bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' cannot be claimed\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **Idempotency.** The endpoint is **not** idempotent. A second `claim-bonus-for-player`\n call for the same `(externalUserId, bonusId)` pair returns\n `PLAYER_BONUS_ALREADY_CLAIMED` (307), not the previously-created `playerBonus`.\n Use Find Player Bonuses to fetch the existing player bonus when you need a\n re-read.\n\n2. **Player registration side-effect.** When `externalUserId` is unknown to Sumstats,\n the system attempts to register the player automatically before evaluating\n eligibility. If automatic registration fails, the request fails with\n `INVALID_USER` (109).\n\n3. **Bonus snapshot.** The newly-created player bonus captures a snapshot of the\n catalogue bonus (`bonusSnapshot.id`, `bonusSnapshot.name`,\n `bonusSnapshot.bonusType`) at claim time. Subsequent edits to the catalogue bonus\n do **not** mutate existing player bonuses — partners always see the snapshot the\n player was awarded.\n\n4. **Action-history entry.** The claim is recorded in the bonus action history as a\n `ClaimedByExternalSystem` entry (`actionType: CLAIMED_BY_EXTERNAL_SYSTEM`), with\n the external request id captured for audit. The same entry is used by all\n partner-side claims regardless of bonus type.\n\n5. **Currency selection.** The player bonus is denominated in the player's currency\n at claim time. The bonus must support the player's currency (`bonus.currencies`\n contains the player currency); otherwise the bonus engine rejects the claim with\n `BONUS_NOT_AVAILABLE` (303).\n\n6. **Bonus tags affect availability.** `One Per Player` and `New Customer` tags are\n evaluated together with the catalogue eligibility rules. A bonus with\n `New Customer` tag is unclaimable for any player who has previously claimed any\n `New-Customer`-tagged bonus regardless of which one.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 309,\n \"errorMessage\": \"Player has already claimed bonuses with the 'New Customer' tag \\u2014 bonus '0192f721-29ae-7aef-9688-7c8bc5508b88' cannot be claimed\"\n}"}],"_postman_id":"6bf615c6-0848-495a-9ae2-c3b277bba532"},{"name":"Activate Player Bonus","id":"8f24f67f-e4e9-4b9c-9d48-41ee2da4a6fc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/activate-player-bonus","description":"

Endpoint for Activating a Player Bonus

Endpoint

POST /external-casino-client/v1/bonus/activate-player-bonus

Description

This endpoint moves a previously claimed internal sportsbook free-bet player\nbonus from CLAIMED to IN_PROGRESS so the player can start placing bets against\nthe free-bet balance. Use it when your side has decided to activate a bonus that was\nclaimed but not yet auto-activated (the bonus was claimed with\nisAutoActivates: false on its catalogue entry).

The activation is recorded in the bonus action history as an\nActivatedBySystemDetails entry (actionType: ACTIVATED_BY_SYSTEM) — the same\nSYSTEM initiator used by Sumstats's internal auto-activation logic. The player\nbonus's activatedAt is set to the activation timestamp; bonusGiven is populated\nwith the awarded free-bet balance in the player's currency.

For bonuses where isAutoActivates: true activation already happened on claim —\ncalling this endpoint for such a player bonus returns\nPLAYER_BONUS_ALREADY_ACTIVATED (312).

Request Body Description

Object:

brandId (integer, required) - Brand id provided by Sumstats. Must match the\nbrand encoded in the HTTP Basic credentials.
\n
brand (string, optional) - Deprecated alias for brandId. Accepted during the\nbrand migration window only.
\n
externalUserId (string, required) - External player id in the operator system.\nCannot be blank.
\n
bonusId (string, required) - UUID of the bonus whose CLAIMED player-bonus\nshould be activated. Must match an existing CLAIMED player-bonus for the player —\ni.e. the player must have previously called claim-bonus-for-player for the same\nbonus and not yet activated.
\n

Response Body Description

Object:

playerBonus (object, required) - The activated player bonus. Same slim shape\ndocumented under Find Player Bonuses.\nNotable fields after a successful activation:
\n
- status (enum, required) - \"IN_PROGRESS\".
- activatedAt (long, required) - Activation timestamp (epoch millis, UTC).
- bonusGiven (object, required) - Awarded free-bet balance in the player's\ncurrency.
- expiredAt (long, optional) - Set if the free-bet rule has a finite validity\n(bonusSize.rule.validityInHours > 0). Computed as activatedAt + validityInHours × 3600 × 1000.
- expiredOnClaimAt (long, optional) - Cleared on activation — null after\nthe bonus has been activated.
\n

Request Example

{\n  \"brandId\": 0,\n  \"externalUserId\": \"ext_987654321\",\n  \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n

Response Example

Successful Response (200 OK)

{\n    \"playerBonus\": {\n        \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n        \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n        \"bonusName\": [\n            {\n                \"locale\": \"en_US\",\n                \"translate\": \"500 TRY FREE BET\"\n            }\n        ],\n        \"bonusType\": \"INTERNAL_FREE_BET\",\n        \"status\": \"IN_PROGRESS\",\n        \"externalPlayerId\": \"ext_987654321\",\n        \"createdAt\": 1761721205143,\n        \"activatedAt\": 1761724805143,\n        \"finishedAt\": null,\n        \"expiredAt\": null,\n        \"expiredOnClaimAt\": 1762326005143,\n        \"isAutoActivates\": true,\n        \"bonusGiven\": {\n            \"amount\": \"50000\",\n            \"currency\": \"TRY\"\n        },\n        \"totalWagering\": null,\n        \"currency\": \"TRY\"\n    }\n}\n

Error Responses

400 Bad Request - Request Validation Error

{\n    \"errorCode\": 3,\n    \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n

400 Bad Request - Invalid User

{\n    \"errorCode\": 109,\n    \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n

400 Bad Request - Player Bonus Not Found

Occurs when no CLAIMED player bonus matches the (externalUserId, bonusId)\npair. Common causes:

The player never claimed this bonus.
The previously-claimed player bonus was already activated, cancelled, or expired.

{\n    \"errorCode\": 310,\n    \"errorMessage\": \"Player bonus not found for externalUserId='ext_987654321' and bonusId='0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n

400 Bad Request - Player Bonus Already Activated

Maps to the legacy player_bonus.already_activated domain code. Occurs when the\nplayer bonus is already IN_PROGRESS (or terminal — COMPLETED, CANCELLED,\nEXPIRED, LOST).

{\n    \"errorCode\": 312,\n    \"errorMessage\": \"Player bonus '0192f730-ceb0-78d2-a4ba-156107b9dbf8' has already been activated\"\n}\n

400 Bad Request - Bonus Eligibility Activate Rules Not Satisfied

Maps to the legacy bonus.activate_rules_not_completely_satisfied domain code.\nOccurs when the bonus has activate-time rules (e.g. required deposits, identity\nverification) that are not yet satisfied at activation time.

{\n    \"errorCode\": 313,\n    \"errorMessage\": \"Eligibility activate rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n

401 Unauthorized - Invalid Credentials

{\n    \"errorCode\": 2,\n    \"errorMessage\": \"Invalid credentials\"\n}\n

500 Internal Server Error - Unknown Error

{\n    \"errorCode\": 1,\n    \"errorMessage\": \"Unknown error\"\n}\n

Important Notes

No-op for auto-activating bonuses. When the underlying bonus has\nisAutoActivates: true, calling activate after a successful claim returns\nPLAYER_BONUS_ALREADY_ACTIVATED (312). Partners can skip the activate step\nentirely for these bonuses — branch on the catalogue-side isAutoActivates flag.
\n
Activation initiator. The action is recorded with ActivatePlayerBonusInitiator = SYSTEM, matching the value used by Sumstats's internal auto-activation logic.\nThis is intentional — the partner integration is treated as a system actor, not\nas an operator user.
\n
Activate-time rules. A free-bet bonus may have separate activate-time rules\n(eligibility.activateRules) on top of claim-time rules. For example, a bonus\nmay be claimable on registration but require a qualifying deposit before it can\nbe activated. The BONUS_ELIGIBILITY_ACTIVATE_RULES_NOT_SATISFIED (313) error\nsurfaces this case.
\n
Activation deadline. If the bonus is CLAIMED past its expiredOnClaimAt\ntimestamp, activation fails with PLAYER_BONUS_NOT_FOUND (310) because the\nengine transitions the player bonus to EXPIRED automatically.
\n

Authentication

Authorization: Basic base64(username:password)\nContent-Type: application/json\n

Use the brandId body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request brandId matches.

\n","urlObject":{"path":["external-casino-client","v1","bonus","activate-player-bonus"],"host":["{apiUrl}"],"query":[],"variable":[]}},"response":[{"id":"07bf4e9a-e34e-4c1a-a3d9-2918d04b8f75","name":"success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/activate-player-bonus","description":"# Endpoint for Activating a Player Bonus\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/activate-player-bonus`\n\n## Description\n\nThis endpoint moves a previously claimed **internal sportsbook free-bet** player\nbonus from `CLAIMED` to `IN_PROGRESS` so the player can start placing bets against\nthe free-bet balance. Use it when your side has decided to activate a bonus that was\nclaimed but not yet auto-activated (the bonus was claimed with\n`isAutoActivates: false` on its catalogue entry).\n\nThe activation is recorded in the bonus action history as an\n`ActivatedBySystemDetails` entry (`actionType: ACTIVATED_BY_SYSTEM`) — the same\n`SYSTEM` initiator used by Sumstats's internal auto-activation logic. The player\nbonus's `activatedAt` is set to the activation timestamp; `bonusGiven` is populated\nwith the awarded free-bet balance in the player's currency.\n\nFor bonuses where `isAutoActivates: true` activation already happened on claim —\ncalling this endpoint for such a player bonus returns\n`PLAYER_BONUS_ALREADY_ACTIVATED` (312).\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus whose `CLAIMED` player-bonus\n should be activated. Must match an existing `CLAIMED` player-bonus for the player —\n i.e. the player must have previously called `claim-bonus-for-player` for the same\n bonus and not yet activated.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The activated player bonus. Same slim shape\n documented under [Find Player Bonuses](#endpoint-for-finding-player-bonuses).\n Notable fields after a successful activation:\n\n - **status** (enum, required) - `\"IN_PROGRESS\"`.\n - **activatedAt** (long, required) - Activation timestamp (epoch millis, UTC).\n - **bonusGiven** (object, required) - Awarded free-bet balance in the player's\n currency.\n - **expiredAt** (long, optional) - Set if the free-bet rule has a finite validity\n (`bonusSize.rule.validityInHours` > 0). Computed as `activatedAt +\n validityInHours × 3600 × 1000`.\n - **expiredOnClaimAt** (long, optional) - Cleared on activation — `null` after\n the bonus has been activated.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Example\n\n### Successful Response (200 OK)\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Player Bonus Not Found\n\nOccurs when no `CLAIMED` player bonus matches the (`externalUserId`, `bonusId`)\npair. Common causes:\n\n- The player never claimed this bonus.\n- The previously-claimed player bonus was already activated, cancelled, or expired.\n\n```json\n{\n \"errorCode\": 310,\n \"errorMessage\": \"Player bonus not found for externalUserId='ext_987654321' and bonusId='0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Already Activated\n\nMaps to the legacy `player_bonus.already_activated` domain code. Occurs when the\nplayer bonus is already `IN_PROGRESS` (or terminal — `COMPLETED`, `CANCELLED`,\n`EXPIRED`, `LOST`).\n\n```json\n{\n \"errorCode\": 312,\n \"errorMessage\": \"Player bonus '0192f730-ceb0-78d2-a4ba-156107b9dbf8' has already been activated\"\n}\n```\n\n### 400 Bad Request - Bonus Eligibility Activate Rules Not Satisfied\n\nMaps to the legacy `bonus.activate_rules_not_completely_satisfied` domain code.\nOccurs when the bonus has activate-time rules (e.g. required deposits, identity\nverification) that are not yet satisfied at activation time.\n\n```json\n{\n \"errorCode\": 313,\n \"errorMessage\": \"Eligibility activate rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **No-op for auto-activating bonuses.** When the underlying bonus has\n `isAutoActivates: true`, calling activate after a successful claim returns\n `PLAYER_BONUS_ALREADY_ACTIVATED` (312). Partners can skip the activate step\n entirely for these bonuses — branch on the catalogue-side `isAutoActivates` flag.\n\n2. **Activation initiator.** The action is recorded with `ActivatePlayerBonusInitiator\n = SYSTEM`, matching the value used by Sumstats's internal auto-activation logic.\n This is intentional — the partner integration is treated as a system actor, not\n as an operator user.\n\n3. **Activate-time rules.** A free-bet bonus may have separate activate-time rules\n (`eligibility.activateRules`) on top of claim-time rules. For example, a bonus\n may be claimable on registration but require a qualifying deposit before it can\n be activated. The `BONUS_ELIGIBILITY_ACTIVATE_RULES_NOT_SATISFIED` (313) error\n surfaces this case.\n\n4. **Activation deadline.** If the bonus is `CLAIMED` past its `expiredOnClaimAt`\n timestamp, activation fails with `PLAYER_BONUS_NOT_FOUND` (310) because the\n engine transitions the player bonus to `EXPIRED` automatically.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}"},{"id":"2bbb5a8e-cb34-4816-87c3-01c529b4c2c2","name":"fail — already activated (312)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/activate-player-bonus","description":"# Endpoint for Activating a Player Bonus\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/activate-player-bonus`\n\n## Description\n\nThis endpoint moves a previously claimed **internal sportsbook free-bet** player\nbonus from `CLAIMED` to `IN_PROGRESS` so the player can start placing bets against\nthe free-bet balance. Use it when your side has decided to activate a bonus that was\nclaimed but not yet auto-activated (the bonus was claimed with\n`isAutoActivates: false` on its catalogue entry).\n\nThe activation is recorded in the bonus action history as an\n`ActivatedBySystemDetails` entry (`actionType: ACTIVATED_BY_SYSTEM`) — the same\n`SYSTEM` initiator used by Sumstats's internal auto-activation logic. The player\nbonus's `activatedAt` is set to the activation timestamp; `bonusGiven` is populated\nwith the awarded free-bet balance in the player's currency.\n\nFor bonuses where `isAutoActivates: true` activation already happened on claim —\ncalling this endpoint for such a player bonus returns\n`PLAYER_BONUS_ALREADY_ACTIVATED` (312).\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus whose `CLAIMED` player-bonus\n should be activated. Must match an existing `CLAIMED` player-bonus for the player —\n i.e. the player must have previously called `claim-bonus-for-player` for the same\n bonus and not yet activated.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The activated player bonus. Same slim shape\n documented under [Find Player Bonuses](#endpoint-for-finding-player-bonuses).\n Notable fields after a successful activation:\n\n - **status** (enum, required) - `\"IN_PROGRESS\"`.\n - **activatedAt** (long, required) - Activation timestamp (epoch millis, UTC).\n - **bonusGiven** (object, required) - Awarded free-bet balance in the player's\n currency.\n - **expiredAt** (long, optional) - Set if the free-bet rule has a finite validity\n (`bonusSize.rule.validityInHours` > 0). Computed as `activatedAt +\n validityInHours × 3600 × 1000`.\n - **expiredOnClaimAt** (long, optional) - Cleared on activation — `null` after\n the bonus has been activated.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Example\n\n### Successful Response (200 OK)\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Player Bonus Not Found\n\nOccurs when no `CLAIMED` player bonus matches the (`externalUserId`, `bonusId`)\npair. Common causes:\n\n- The player never claimed this bonus.\n- The previously-claimed player bonus was already activated, cancelled, or expired.\n\n```json\n{\n \"errorCode\": 310,\n \"errorMessage\": \"Player bonus not found for externalUserId='ext_987654321' and bonusId='0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Already Activated\n\nMaps to the legacy `player_bonus.already_activated` domain code. Occurs when the\nplayer bonus is already `IN_PROGRESS` (or terminal — `COMPLETED`, `CANCELLED`,\n`EXPIRED`, `LOST`).\n\n```json\n{\n \"errorCode\": 312,\n \"errorMessage\": \"Player bonus '0192f730-ceb0-78d2-a4ba-156107b9dbf8' has already been activated\"\n}\n```\n\n### 400 Bad Request - Bonus Eligibility Activate Rules Not Satisfied\n\nMaps to the legacy `bonus.activate_rules_not_completely_satisfied` domain code.\nOccurs when the bonus has activate-time rules (e.g. required deposits, identity\nverification) that are not yet satisfied at activation time.\n\n```json\n{\n \"errorCode\": 313,\n \"errorMessage\": \"Eligibility activate rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **No-op for auto-activating bonuses.** When the underlying bonus has\n `isAutoActivates: true`, calling activate after a successful claim returns\n `PLAYER_BONUS_ALREADY_ACTIVATED` (312). Partners can skip the activate step\n entirely for these bonuses — branch on the catalogue-side `isAutoActivates` flag.\n\n2. **Activation initiator.** The action is recorded with `ActivatePlayerBonusInitiator\n = SYSTEM`, matching the value used by Sumstats's internal auto-activation logic.\n This is intentional — the partner integration is treated as a system actor, not\n as an operator user.\n\n3. **Activate-time rules.** A free-bet bonus may have separate activate-time rules\n (`eligibility.activateRules`) on top of claim-time rules. For example, a bonus\n may be claimable on registration but require a qualifying deposit before it can\n be activated. The `BONUS_ELIGIBILITY_ACTIVATE_RULES_NOT_SATISFIED` (313) error\n surfaces this case.\n\n4. **Activation deadline.** If the bonus is `CLAIMED` past its `expiredOnClaimAt`\n timestamp, activation fails with `PLAYER_BONUS_NOT_FOUND` (310) because the\n engine transitions the player bonus to `EXPIRED` automatically.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 312,\n \"errorMessage\": \"Player bonus '0192f730-ceb0-78d2-a4ba-156107b9dbf8' has already been activated\"\n}"},{"id":"a9131992-b854-48e2-9c63-39a096063b3d","name":"fail — activate rules (313)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/activate-player-bonus","description":"# Endpoint for Activating a Player Bonus\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/activate-player-bonus`\n\n## Description\n\nThis endpoint moves a previously claimed **internal sportsbook free-bet** player\nbonus from `CLAIMED` to `IN_PROGRESS` so the player can start placing bets against\nthe free-bet balance. Use it when your side has decided to activate a bonus that was\nclaimed but not yet auto-activated (the bonus was claimed with\n`isAutoActivates: false` on its catalogue entry).\n\nThe activation is recorded in the bonus action history as an\n`ActivatedBySystemDetails` entry (`actionType: ACTIVATED_BY_SYSTEM`) — the same\n`SYSTEM` initiator used by Sumstats's internal auto-activation logic. The player\nbonus's `activatedAt` is set to the activation timestamp; `bonusGiven` is populated\nwith the awarded free-bet balance in the player's currency.\n\nFor bonuses where `isAutoActivates: true` activation already happened on claim —\ncalling this endpoint for such a player bonus returns\n`PLAYER_BONUS_ALREADY_ACTIVATED` (312).\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus whose `CLAIMED` player-bonus\n should be activated. Must match an existing `CLAIMED` player-bonus for the player —\n i.e. the player must have previously called `claim-bonus-for-player` for the same\n bonus and not yet activated.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The activated player bonus. Same slim shape\n documented under [Find Player Bonuses](#endpoint-for-finding-player-bonuses).\n Notable fields after a successful activation:\n\n - **status** (enum, required) - `\"IN_PROGRESS\"`.\n - **activatedAt** (long, required) - Activation timestamp (epoch millis, UTC).\n - **bonusGiven** (object, required) - Awarded free-bet balance in the player's\n currency.\n - **expiredAt** (long, optional) - Set if the free-bet rule has a finite validity\n (`bonusSize.rule.validityInHours` > 0). Computed as `activatedAt +\n validityInHours × 3600 × 1000`.\n - **expiredOnClaimAt** (long, optional) - Cleared on activation — `null` after\n the bonus has been activated.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Example\n\n### Successful Response (200 OK)\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Player Bonus Not Found\n\nOccurs when no `CLAIMED` player bonus matches the (`externalUserId`, `bonusId`)\npair. Common causes:\n\n- The player never claimed this bonus.\n- The previously-claimed player bonus was already activated, cancelled, or expired.\n\n```json\n{\n \"errorCode\": 310,\n \"errorMessage\": \"Player bonus not found for externalUserId='ext_987654321' and bonusId='0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Already Activated\n\nMaps to the legacy `player_bonus.already_activated` domain code. Occurs when the\nplayer bonus is already `IN_PROGRESS` (or terminal — `COMPLETED`, `CANCELLED`,\n`EXPIRED`, `LOST`).\n\n```json\n{\n \"errorCode\": 312,\n \"errorMessage\": \"Player bonus '0192f730-ceb0-78d2-a4ba-156107b9dbf8' has already been activated\"\n}\n```\n\n### 400 Bad Request - Bonus Eligibility Activate Rules Not Satisfied\n\nMaps to the legacy `bonus.activate_rules_not_completely_satisfied` domain code.\nOccurs when the bonus has activate-time rules (e.g. required deposits, identity\nverification) that are not yet satisfied at activation time.\n\n```json\n{\n \"errorCode\": 313,\n \"errorMessage\": \"Eligibility activate rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **No-op for auto-activating bonuses.** When the underlying bonus has\n `isAutoActivates: true`, calling activate after a successful claim returns\n `PLAYER_BONUS_ALREADY_ACTIVATED` (312). Partners can skip the activate step\n entirely for these bonuses — branch on the catalogue-side `isAutoActivates` flag.\n\n2. **Activation initiator.** The action is recorded with `ActivatePlayerBonusInitiator\n = SYSTEM`, matching the value used by Sumstats's internal auto-activation logic.\n This is intentional — the partner integration is treated as a system actor, not\n as an operator user.\n\n3. **Activate-time rules.** A free-bet bonus may have separate activate-time rules\n (`eligibility.activateRules`) on top of claim-time rules. For example, a bonus\n may be claimable on registration but require a qualifying deposit before it can\n be activated. The `BONUS_ELIGIBILITY_ACTIVATE_RULES_NOT_SATISFIED` (313) error\n surfaces this case.\n\n4. **Activation deadline.** If the bonus is `CLAIMED` past its `expiredOnClaimAt`\n timestamp, activation fails with `PLAYER_BONUS_NOT_FOUND` (310) because the\n engine transitions the player bonus to `EXPIRED` automatically.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 313,\n \"errorMessage\": \"Eligibility activate rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}"},{"id":"0f6c2f65-12c4-44b8-9d76-ce397f059edc","name":"fail — player bonus not found (310)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/activate-player-bonus","description":"# Endpoint for Activating a Player Bonus\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/activate-player-bonus`\n\n## Description\n\nThis endpoint moves a previously claimed **internal sportsbook free-bet** player\nbonus from `CLAIMED` to `IN_PROGRESS` so the player can start placing bets against\nthe free-bet balance. Use it when your side has decided to activate a bonus that was\nclaimed but not yet auto-activated (the bonus was claimed with\n`isAutoActivates: false` on its catalogue entry).\n\nThe activation is recorded in the bonus action history as an\n`ActivatedBySystemDetails` entry (`actionType: ACTIVATED_BY_SYSTEM`) — the same\n`SYSTEM` initiator used by Sumstats's internal auto-activation logic. The player\nbonus's `activatedAt` is set to the activation timestamp; `bonusGiven` is populated\nwith the awarded free-bet balance in the player's currency.\n\nFor bonuses where `isAutoActivates: true` activation already happened on claim —\ncalling this endpoint for such a player bonus returns\n`PLAYER_BONUS_ALREADY_ACTIVATED` (312).\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus whose `CLAIMED` player-bonus\n should be activated. Must match an existing `CLAIMED` player-bonus for the player —\n i.e. the player must have previously called `claim-bonus-for-player` for the same\n bonus and not yet activated.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The activated player bonus. Same slim shape\n documented under [Find Player Bonuses](#endpoint-for-finding-player-bonuses).\n Notable fields after a successful activation:\n\n - **status** (enum, required) - `\"IN_PROGRESS\"`.\n - **activatedAt** (long, required) - Activation timestamp (epoch millis, UTC).\n - **bonusGiven** (object, required) - Awarded free-bet balance in the player's\n currency.\n - **expiredAt** (long, optional) - Set if the free-bet rule has a finite validity\n (`bonusSize.rule.validityInHours` > 0). Computed as `activatedAt +\n validityInHours × 3600 × 1000`.\n - **expiredOnClaimAt** (long, optional) - Cleared on activation — `null` after\n the bonus has been activated.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Example\n\n### Successful Response (200 OK)\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"IN_PROGRESS\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": null,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Player Bonus Not Found\n\nOccurs when no `CLAIMED` player bonus matches the (`externalUserId`, `bonusId`)\npair. Common causes:\n\n- The player never claimed this bonus.\n- The previously-claimed player bonus was already activated, cancelled, or expired.\n\n```json\n{\n \"errorCode\": 310,\n \"errorMessage\": \"Player bonus not found for externalUserId='ext_987654321' and bonusId='0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Already Activated\n\nMaps to the legacy `player_bonus.already_activated` domain code. Occurs when the\nplayer bonus is already `IN_PROGRESS` (or terminal — `COMPLETED`, `CANCELLED`,\n`EXPIRED`, `LOST`).\n\n```json\n{\n \"errorCode\": 312,\n \"errorMessage\": \"Player bonus '0192f730-ceb0-78d2-a4ba-156107b9dbf8' has already been activated\"\n}\n```\n\n### 400 Bad Request - Bonus Eligibility Activate Rules Not Satisfied\n\nMaps to the legacy `bonus.activate_rules_not_completely_satisfied` domain code.\nOccurs when the bonus has activate-time rules (e.g. required deposits, identity\nverification) that are not yet satisfied at activation time.\n\n```json\n{\n \"errorCode\": 313,\n \"errorMessage\": \"Eligibility activate rules are not satisfied for bonus '0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **No-op for auto-activating bonuses.** When the underlying bonus has\n `isAutoActivates: true`, calling activate after a successful claim returns\n `PLAYER_BONUS_ALREADY_ACTIVATED` (312). Partners can skip the activate step\n entirely for these bonuses — branch on the catalogue-side `isAutoActivates` flag.\n\n2. **Activation initiator.** The action is recorded with `ActivatePlayerBonusInitiator\n = SYSTEM`, matching the value used by Sumstats's internal auto-activation logic.\n This is intentional — the partner integration is treated as a system actor, not\n as an operator user.\n\n3. **Activate-time rules.** A free-bet bonus may have separate activate-time rules\n (`eligibility.activateRules`) on top of claim-time rules. For example, a bonus\n may be claimable on registration but require a qualifying deposit before it can\n be activated. The `BONUS_ELIGIBILITY_ACTIVATE_RULES_NOT_SATISFIED` (313) error\n surfaces this case.\n\n4. **Activation deadline.** If the bonus is `CLAIMED` past its `expiredOnClaimAt`\n timestamp, activation fails with `PLAYER_BONUS_NOT_FOUND` (310) because the\n engine transitions the player bonus to `EXPIRED` automatically.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 310,\n \"errorMessage\": \"Player bonus not found for externalUserId='ext_987654321' and bonusId='0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}"}],"_postman_id":"8f24f67f-e4e9-4b9c-9d48-41ee2da4a6fc"},{"name":"Cancel Player Bonus","id":"37ec56b3-bc9c-49c6-9d4a-a9b06f0491d1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/cancel-player-bonus","description":"

Endpoint for Cancelling a Player Bonus

Endpoint

POST /external-casino-client/v1/bonus/cancel-player-bonus

Description

This endpoint cancels an active internal sportsbook free-bet player bonus\nidentified by the external player id and the bonus id. Use it when your side decides\nto revoke a previously claimed (or in-progress) free bet — for example after a fraud\nsignal, a duplicate-account match, or a partner-side policy change.

The cancellation is recorded in the bonus action history as a\nCancelledBySystemDetails entry (actionType: CANCELLED_BY_SYSTEM) with the calling\nbrandId captured in the action reason field for audit traceability — no\noperator id is involved. The player bonus moves to status: \"CANCELLED\",\nfinishedAt is set to the cancellation timestamp, and the bonus engine notifies the\npayment service to claw back any awarded free-bet balance from the bonus wallet.

Already-completed, already-cancelled, expired, or lost player bonuses cannot be\ncancelled and surface as PLAYER_BONUS_NOT_CANCELLABLE (311). The integration\npre-filters to CLAIMED and IN_PROGRESS statuses, so this error is normally only\nseen in a tight TOCTOU race where the player bonus completes between filter and\nvalidate.

Request Body Description

Object:

brandId (integer, required) - Brand id provided by Sumstats. Must match the\nbrand encoded in the HTTP Basic credentials. Captured in the action history\nreason field for traceability.
\n
brand (string, optional) - Deprecated alias for brandId. Accepted during the\nbrand migration window only.
\n
externalUserId (string, required) - External player id in the operator system.\nCannot be blank.
\n
bonusId (string, required) - UUID of the bonus whose active player-bonus should\nbe cancelled. Must match a CLAIMED or IN_PROGRESS player-bonus for the player.\nCannot be blank.
\n

Response Body Description

Object:

playerBonus (object, required) - The cancelled player bonus. Same slim shape\ndocumented under Find Player Bonuses.\nNotable fields after a successful cancel:
\n
- status (enum, required) - \"CANCELLED\".
- finishedAt (long, required) - Cancellation timestamp (epoch millis, UTC).
- bonusGiven (object, optional) - Reflects the free-bet balance at\ncancellation time; the actual claw-back happens asynchronously via the\npayment-service notification. For player bonuses cancelled while in CLAIMED\n(no money credited yet), this is null.
\n

Request Example

{\n  \"brandId\": 0,\n  \"externalUserId\": \"ext_987654321\",\n  \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n

Response Examples

Successful Response (200 OK) — Cancel of an in-progress free bet

{\n    \"playerBonus\": {\n        \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n        \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n        \"bonusName\": [\n            {\n                \"locale\": \"en_US\",\n                \"translate\": \"500 TRY FREE BET\"\n            }\n        ],\n        \"bonusType\": \"INTERNAL_FREE_BET\",\n        \"status\": \"CANCELLED\",\n        \"externalPlayerId\": \"ext_987654321\",\n        \"createdAt\": 1761721205143,\n        \"activatedAt\": 1761724805143,\n        \"finishedAt\": 1761728405143,\n        \"expiredAt\": null,\n        \"expiredOnClaimAt\": 1762326005143,\n        \"isAutoActivates\": true,\n        \"bonusGiven\": {\n            \"amount\": \"50000\",\n            \"currency\": \"TRY\"\n        },\n        \"totalWagering\": null,\n        \"currency\": \"TRY\"\n    }\n}\n

Successful Response (200 OK) — Cancel of a claimed (not-yet-activated) free bet

When the player bonus is CLAIMED (no money credited yet), bonusGiven is null\nand there is no claw-back side effect. finishedAt is set; activatedAt stays\nnull.

{\n    \"playerBonus\": {\n        \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n        \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n        \"bonusName\": [\n            {\n                \"locale\": \"en_US\",\n                \"translate\": \"500 TRY FREE BET\"\n            }\n        ],\n        \"bonusType\": \"INTERNAL_FREE_BET\",\n        \"status\": \"CANCELLED\",\n        \"externalPlayerId\": \"ext_987654321\",\n        \"createdAt\": 1761721205143,\n        \"activatedAt\": null,\n        \"finishedAt\": 1761725005143,\n        \"expiredAt\": null,\n        \"expiredOnClaimAt\": 1762326005143,\n        \"isAutoActivates\": false,\n        \"bonusGiven\": null,\n        \"totalWagering\": null,\n        \"currency\": \"TRY\"\n    }\n}\n

Error Responses

400 Bad Request - Request Validation Error

{\n    \"errorCode\": 3,\n    \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n

400 Bad Request - Invalid User

{\n    \"errorCode\": 109,\n    \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n

400 Bad Request - Player Bonus Not Found

Occurs when no active player bonus (CLAIMED or IN_PROGRESS) matches the\n(externalUserId, bonusId) pair. Common causes:

The player never claimed this bonus.
The previously-claimed player bonus already finished (COMPLETED, CANCELLED,\nEXPIRED, LOST).

{\n    \"errorCode\": 310,\n    \"errorMessage\": \"Active player bonus not found for externalUserId='ext_987654321', bonusId='0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n

400 Bad Request - Player Bonus Not Cancellable

Maps to the legacy player_bonus.already_cancelled / player_bonus.already_finished\ndomain codes. Occurs in a TOCTOU race between filter and validate when the player\nbonus completes between the find-cancellable lookup and the aggregate-side\nvalidation.

{\n    \"errorCode\": 311,\n    \"errorMessage\": \"Player bonus '0192f730-ceb0-78d2-a4ba-156107b9dbf8' cannot be cancelled: already finished\"\n}\n

401 Unauthorized - Invalid Credentials

{\n    \"errorCode\": 2,\n    \"errorMessage\": \"Invalid credentials\"\n}\n

500 Internal Server Error - Unknown Error

{\n    \"errorCode\": 1,\n    \"errorMessage\": \"Unknown error\"\n}\n

Important Notes

System-initiated cancel — no operator id. The cancellation is attributed to\nthe integration as CANCELLED_BY_SYSTEM, not to a specific operator. The\ncalling brandId is captured in the action reason for traceability. Internal\nadmin-side filtering on operator id will not surface these cancels — use the\naction type filter instead.
\n
Async claw-back. When the player bonus is IN_PROGRESS and has bonusGiven\npopulated, the cancel triggers a payment-service notification to claw back the\nfree-bet balance from the bonus wallet. The notification is processed\nasynchronously — the response returns as soon as the bonus aggregate's\nCANCELLED event is committed, not after the wallet update. Partners observing\nwallet-side state may see a small eventual-consistency window.
\n
Multiple active player bonuses for the same bonusId. When the player has\nmultiple CLAIMED/IN_PROGRESS player bonuses for the same bonus (rare —\nusually prevented by the catalogue-side claim limits), the integration cancels\nthe first matching entry. The contract is intentionally simple — partners\nthat need to target a specific player-bonus instance should call admin-side APIs.
\n
Idempotency. The endpoint is not idempotent. A second cancel call for an\nalready-cancelled player bonus returns PLAYER_BONUS_NOT_FOUND (310) (since the\nintegration filters by CLAIMED/IN_PROGRESS), not a success.
\n

Authentication

Authorization: Basic base64(username:password)\nContent-Type: application/json\n

Use the brandId body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request brandId matches.

\n","urlObject":{"path":["external-casino-client","v1","bonus","cancel-player-bonus"],"host":["{apiUrl}"],"query":[],"variable":[]}},"response":[{"id":"8d0abffa-58f3-4448-b239-3cf49b7e136b","name":"success — Cancel of an in-progress free bet","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/cancel-player-bonus","description":"# Endpoint for Cancelling a Player Bonus\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/cancel-player-bonus`\n\n## Description\n\nThis endpoint cancels an active **internal sportsbook free-bet** player bonus\nidentified by the external player id and the bonus id. Use it when your side decides\nto revoke a previously claimed (or in-progress) free bet — for example after a fraud\nsignal, a duplicate-account match, or a partner-side policy change.\n\nThe cancellation is recorded in the bonus action history as a\n`CancelledBySystemDetails` entry (`actionType: CANCELLED_BY_SYSTEM`) with the calling\n`brandId` captured in the action `reason` field for audit traceability — **no\noperator id is involved**. The player bonus moves to `status: \"CANCELLED\"`,\n`finishedAt` is set to the cancellation timestamp, and the bonus engine notifies the\npayment service to claw back any awarded free-bet balance from the bonus wallet.\n\nAlready-completed, already-cancelled, expired, or lost player bonuses cannot be\ncancelled and surface as `PLAYER_BONUS_NOT_CANCELLABLE` (311). The integration\npre-filters to `CLAIMED` and `IN_PROGRESS` statuses, so this error is normally only\nseen in a tight TOCTOU race where the player bonus completes between filter and\nvalidate.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials. Captured in the action history\n `reason` field for traceability.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus whose active player-bonus should\n be cancelled. Must match a `CLAIMED` or `IN_PROGRESS` player-bonus for the player.\n Cannot be blank.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The cancelled player bonus. Same slim shape\n documented under [Find Player Bonuses](#endpoint-for-finding-player-bonuses).\n Notable fields after a successful cancel:\n\n - **status** (enum, required) - `\"CANCELLED\"`.\n - **finishedAt** (long, required) - Cancellation timestamp (epoch millis, UTC).\n - **bonusGiven** (object, optional) - Reflects the free-bet balance at\n cancellation time; the actual claw-back happens asynchronously via the\n payment-service notification. For player bonuses cancelled while in `CLAIMED`\n (no money credited yet), this is `null`.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Cancel of an in-progress free bet\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CANCELLED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": 1761728405143,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n### Successful Response (200 OK) — Cancel of a claimed (not-yet-activated) free bet\n\nWhen the player bonus is `CLAIMED` (no money credited yet), `bonusGiven` is `null`\nand there is no claw-back side effect. `finishedAt` is set; `activatedAt` stays\n`null`.\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CANCELLED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": null,\n \"finishedAt\": 1761725005143,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": false,\n \"bonusGiven\": null,\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Player Bonus Not Found\n\nOccurs when no active player bonus (`CLAIMED` or `IN_PROGRESS`) matches the\n(`externalUserId`, `bonusId`) pair. Common causes:\n\n- The player never claimed this bonus.\n- The previously-claimed player bonus already finished (`COMPLETED`, `CANCELLED`,\n `EXPIRED`, `LOST`).\n\n```json\n{\n \"errorCode\": 310,\n \"errorMessage\": \"Active player bonus not found for externalUserId='ext_987654321', bonusId='0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Not Cancellable\n\nMaps to the legacy `player_bonus.already_cancelled` / `player_bonus.already_finished`\ndomain codes. Occurs in a TOCTOU race between filter and validate when the player\nbonus completes between the find-cancellable lookup and the aggregate-side\nvalidation.\n\n```json\n{\n \"errorCode\": 311,\n \"errorMessage\": \"Player bonus '0192f730-ceb0-78d2-a4ba-156107b9dbf8' cannot be cancelled: already finished\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **System-initiated cancel — no operator id.** The cancellation is attributed to\n the integration as `CANCELLED_BY_SYSTEM`, **not** to a specific operator. The\n calling `brandId` is captured in the action `reason` for traceability. Internal\n admin-side filtering on operator id will not surface these cancels — use the\n action type filter instead.\n\n2. **Async claw-back.** When the player bonus is `IN_PROGRESS` and has `bonusGiven`\n populated, the cancel triggers a payment-service notification to claw back the\n free-bet balance from the bonus wallet. The notification is processed\n asynchronously — the response returns as soon as the bonus aggregate's\n `CANCELLED` event is committed, not after the wallet update. Partners observing\n wallet-side state may see a small eventual-consistency window.\n\n3. **Multiple active player bonuses for the same bonusId.** When the player has\n multiple `CLAIMED`/`IN_PROGRESS` player bonuses for the same bonus (rare —\n usually prevented by the catalogue-side claim limits), the integration cancels\n the **first matching** entry. The contract is intentionally simple — partners\n that need to target a specific player-bonus instance should call admin-side APIs.\n\n4. **Idempotency.** The endpoint is **not** idempotent. A second cancel call for an\n already-cancelled player bonus returns `PLAYER_BONUS_NOT_FOUND` (310) (since the\n integration filters by `CLAIMED`/`IN_PROGRESS`), not a success.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CANCELLED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": 1761728405143,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}"},{"id":"98348dc2-765c-4596-93c8-e2f74095a5a8","name":"success — Cancel of a CLAIMED free bet","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/cancel-player-bonus","description":"# Endpoint for Cancelling a Player Bonus\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/cancel-player-bonus`\n\n## Description\n\nThis endpoint cancels an active **internal sportsbook free-bet** player bonus\nidentified by the external player id and the bonus id. Use it when your side decides\nto revoke a previously claimed (or in-progress) free bet — for example after a fraud\nsignal, a duplicate-account match, or a partner-side policy change.\n\nThe cancellation is recorded in the bonus action history as a\n`CancelledBySystemDetails` entry (`actionType: CANCELLED_BY_SYSTEM`) with the calling\n`brandId` captured in the action `reason` field for audit traceability — **no\noperator id is involved**. The player bonus moves to `status: \"CANCELLED\"`,\n`finishedAt` is set to the cancellation timestamp, and the bonus engine notifies the\npayment service to claw back any awarded free-bet balance from the bonus wallet.\n\nAlready-completed, already-cancelled, expired, or lost player bonuses cannot be\ncancelled and surface as `PLAYER_BONUS_NOT_CANCELLABLE` (311). The integration\npre-filters to `CLAIMED` and `IN_PROGRESS` statuses, so this error is normally only\nseen in a tight TOCTOU race where the player bonus completes between filter and\nvalidate.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials. Captured in the action history\n `reason` field for traceability.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus whose active player-bonus should\n be cancelled. Must match a `CLAIMED` or `IN_PROGRESS` player-bonus for the player.\n Cannot be blank.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The cancelled player bonus. Same slim shape\n documented under [Find Player Bonuses](#endpoint-for-finding-player-bonuses).\n Notable fields after a successful cancel:\n\n - **status** (enum, required) - `\"CANCELLED\"`.\n - **finishedAt** (long, required) - Cancellation timestamp (epoch millis, UTC).\n - **bonusGiven** (object, optional) - Reflects the free-bet balance at\n cancellation time; the actual claw-back happens asynchronously via the\n payment-service notification. For player bonuses cancelled while in `CLAIMED`\n (no money credited yet), this is `null`.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Cancel of an in-progress free bet\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CANCELLED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": 1761728405143,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n### Successful Response (200 OK) — Cancel of a claimed (not-yet-activated) free bet\n\nWhen the player bonus is `CLAIMED` (no money credited yet), `bonusGiven` is `null`\nand there is no claw-back side effect. `finishedAt` is set; `activatedAt` stays\n`null`.\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CANCELLED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": null,\n \"finishedAt\": 1761725005143,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": false,\n \"bonusGiven\": null,\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Player Bonus Not Found\n\nOccurs when no active player bonus (`CLAIMED` or `IN_PROGRESS`) matches the\n(`externalUserId`, `bonusId`) pair. Common causes:\n\n- The player never claimed this bonus.\n- The previously-claimed player bonus already finished (`COMPLETED`, `CANCELLED`,\n `EXPIRED`, `LOST`).\n\n```json\n{\n \"errorCode\": 310,\n \"errorMessage\": \"Active player bonus not found for externalUserId='ext_987654321', bonusId='0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Not Cancellable\n\nMaps to the legacy `player_bonus.already_cancelled` / `player_bonus.already_finished`\ndomain codes. Occurs in a TOCTOU race between filter and validate when the player\nbonus completes between the find-cancellable lookup and the aggregate-side\nvalidation.\n\n```json\n{\n \"errorCode\": 311,\n \"errorMessage\": \"Player bonus '0192f730-ceb0-78d2-a4ba-156107b9dbf8' cannot be cancelled: already finished\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **System-initiated cancel — no operator id.** The cancellation is attributed to\n the integration as `CANCELLED_BY_SYSTEM`, **not** to a specific operator. The\n calling `brandId` is captured in the action `reason` for traceability. Internal\n admin-side filtering on operator id will not surface these cancels — use the\n action type filter instead.\n\n2. **Async claw-back.** When the player bonus is `IN_PROGRESS` and has `bonusGiven`\n populated, the cancel triggers a payment-service notification to claw back the\n free-bet balance from the bonus wallet. The notification is processed\n asynchronously — the response returns as soon as the bonus aggregate's\n `CANCELLED` event is committed, not after the wallet update. Partners observing\n wallet-side state may see a small eventual-consistency window.\n\n3. **Multiple active player bonuses for the same bonusId.** When the player has\n multiple `CLAIMED`/`IN_PROGRESS` player bonuses for the same bonus (rare —\n usually prevented by the catalogue-side claim limits), the integration cancels\n the **first matching** entry. The contract is intentionally simple — partners\n that need to target a specific player-bonus instance should call admin-side APIs.\n\n4. **Idempotency.** The endpoint is **not** idempotent. A second cancel call for an\n already-cancelled player bonus returns `PLAYER_BONUS_NOT_FOUND` (310) (since the\n integration filters by `CLAIMED`/`IN_PROGRESS`), not a success.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CANCELLED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": null,\n \"finishedAt\": 1761725005143,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": false,\n \"bonusGiven\": null,\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}"},{"id":"a3bce8ef-1dd0-4046-99a2-8e36529ef612","name":"fail — player bonus not found (310)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/cancel-player-bonus","description":"# Endpoint for Cancelling a Player Bonus\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/cancel-player-bonus`\n\n## Description\n\nThis endpoint cancels an active **internal sportsbook free-bet** player bonus\nidentified by the external player id and the bonus id. Use it when your side decides\nto revoke a previously claimed (or in-progress) free bet — for example after a fraud\nsignal, a duplicate-account match, or a partner-side policy change.\n\nThe cancellation is recorded in the bonus action history as a\n`CancelledBySystemDetails` entry (`actionType: CANCELLED_BY_SYSTEM`) with the calling\n`brandId` captured in the action `reason` field for audit traceability — **no\noperator id is involved**. The player bonus moves to `status: \"CANCELLED\"`,\n`finishedAt` is set to the cancellation timestamp, and the bonus engine notifies the\npayment service to claw back any awarded free-bet balance from the bonus wallet.\n\nAlready-completed, already-cancelled, expired, or lost player bonuses cannot be\ncancelled and surface as `PLAYER_BONUS_NOT_CANCELLABLE` (311). The integration\npre-filters to `CLAIMED` and `IN_PROGRESS` statuses, so this error is normally only\nseen in a tight TOCTOU race where the player bonus completes between filter and\nvalidate.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials. Captured in the action history\n `reason` field for traceability.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus whose active player-bonus should\n be cancelled. Must match a `CLAIMED` or `IN_PROGRESS` player-bonus for the player.\n Cannot be blank.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The cancelled player bonus. Same slim shape\n documented under [Find Player Bonuses](#endpoint-for-finding-player-bonuses).\n Notable fields after a successful cancel:\n\n - **status** (enum, required) - `\"CANCELLED\"`.\n - **finishedAt** (long, required) - Cancellation timestamp (epoch millis, UTC).\n - **bonusGiven** (object, optional) - Reflects the free-bet balance at\n cancellation time; the actual claw-back happens asynchronously via the\n payment-service notification. For player bonuses cancelled while in `CLAIMED`\n (no money credited yet), this is `null`.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Cancel of an in-progress free bet\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CANCELLED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": 1761728405143,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n### Successful Response (200 OK) — Cancel of a claimed (not-yet-activated) free bet\n\nWhen the player bonus is `CLAIMED` (no money credited yet), `bonusGiven` is `null`\nand there is no claw-back side effect. `finishedAt` is set; `activatedAt` stays\n`null`.\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CANCELLED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": null,\n \"finishedAt\": 1761725005143,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": false,\n \"bonusGiven\": null,\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Player Bonus Not Found\n\nOccurs when no active player bonus (`CLAIMED` or `IN_PROGRESS`) matches the\n(`externalUserId`, `bonusId`) pair. Common causes:\n\n- The player never claimed this bonus.\n- The previously-claimed player bonus already finished (`COMPLETED`, `CANCELLED`,\n `EXPIRED`, `LOST`).\n\n```json\n{\n \"errorCode\": 310,\n \"errorMessage\": \"Active player bonus not found for externalUserId='ext_987654321', bonusId='0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Not Cancellable\n\nMaps to the legacy `player_bonus.already_cancelled` / `player_bonus.already_finished`\ndomain codes. Occurs in a TOCTOU race between filter and validate when the player\nbonus completes between the find-cancellable lookup and the aggregate-side\nvalidation.\n\n```json\n{\n \"errorCode\": 311,\n \"errorMessage\": \"Player bonus '0192f730-ceb0-78d2-a4ba-156107b9dbf8' cannot be cancelled: already finished\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **System-initiated cancel — no operator id.** The cancellation is attributed to\n the integration as `CANCELLED_BY_SYSTEM`, **not** to a specific operator. The\n calling `brandId` is captured in the action `reason` for traceability. Internal\n admin-side filtering on operator id will not surface these cancels — use the\n action type filter instead.\n\n2. **Async claw-back.** When the player bonus is `IN_PROGRESS` and has `bonusGiven`\n populated, the cancel triggers a payment-service notification to claw back the\n free-bet balance from the bonus wallet. The notification is processed\n asynchronously — the response returns as soon as the bonus aggregate's\n `CANCELLED` event is committed, not after the wallet update. Partners observing\n wallet-side state may see a small eventual-consistency window.\n\n3. **Multiple active player bonuses for the same bonusId.** When the player has\n multiple `CLAIMED`/`IN_PROGRESS` player bonuses for the same bonus (rare —\n usually prevented by the catalogue-side claim limits), the integration cancels\n the **first matching** entry. The contract is intentionally simple — partners\n that need to target a specific player-bonus instance should call admin-side APIs.\n\n4. **Idempotency.** The endpoint is **not** idempotent. A second cancel call for an\n already-cancelled player bonus returns `PLAYER_BONUS_NOT_FOUND` (310) (since the\n integration filters by `CLAIMED`/`IN_PROGRESS`), not a success.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 310,\n \"errorMessage\": \"Active player bonus not found for externalUserId='ext_987654321', bonusId='0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}"},{"id":"e71815d5-8732-4981-b027-142ed9f9c677","name":"fail — not cancellable (311)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/bonus/cancel-player-bonus","description":"# Endpoint for Cancelling a Player Bonus\n\n## Endpoint\n\n**POST** `/external-casino-client/v1/bonus/cancel-player-bonus`\n\n## Description\n\nThis endpoint cancels an active **internal sportsbook free-bet** player bonus\nidentified by the external player id and the bonus id. Use it when your side decides\nto revoke a previously claimed (or in-progress) free bet — for example after a fraud\nsignal, a duplicate-account match, or a partner-side policy change.\n\nThe cancellation is recorded in the bonus action history as a\n`CancelledBySystemDetails` entry (`actionType: CANCELLED_BY_SYSTEM`) with the calling\n`brandId` captured in the action `reason` field for audit traceability — **no\noperator id is involved**. The player bonus moves to `status: \"CANCELLED\"`,\n`finishedAt` is set to the cancellation timestamp, and the bonus engine notifies the\npayment service to claw back any awarded free-bet balance from the bonus wallet.\n\nAlready-completed, already-cancelled, expired, or lost player bonuses cannot be\ncancelled and surface as `PLAYER_BONUS_NOT_CANCELLABLE` (311). The integration\npre-filters to `CLAIMED` and `IN_PROGRESS` statuses, so this error is normally only\nseen in a tight TOCTOU race where the player bonus completes between filter and\nvalidate.\n\n## Request Body Description\n\n**Object:**\n\n- **brandId** (integer, required) - Brand id provided by Sumstats. Must match the\n brand encoded in the HTTP Basic credentials. Captured in the action history\n `reason` field for traceability.\n\n- **brand** (string, optional) - Deprecated alias for `brandId`. Accepted during the\n brand migration window only.\n\n- **externalUserId** (string, required) - External player id in the operator system.\n Cannot be blank.\n\n- **bonusId** (string, required) - UUID of the bonus whose active player-bonus should\n be cancelled. Must match a `CLAIMED` or `IN_PROGRESS` player-bonus for the player.\n Cannot be blank.\n\n## Response Body Description\n\n**Object:**\n\n- **playerBonus** (object, required) - The cancelled player bonus. Same slim shape\n documented under [Find Player Bonuses](#endpoint-for-finding-player-bonuses).\n Notable fields after a successful cancel:\n\n - **status** (enum, required) - `\"CANCELLED\"`.\n - **finishedAt** (long, required) - Cancellation timestamp (epoch millis, UTC).\n - **bonusGiven** (object, optional) - Reflects the free-bet balance at\n cancellation time; the actual claw-back happens asynchronously via the\n payment-service notification. For player bonuses cancelled while in `CLAIMED`\n (no money credited yet), this is `null`.\n\n## Request Example\n\n```json\n{\n \"brandId\": 0,\n \"externalUserId\": \"ext_987654321\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\"\n}\n```\n\n## Response Examples\n\n### Successful Response (200 OK) — Cancel of an in-progress free bet\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CANCELLED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": 1761724805143,\n \"finishedAt\": 1761728405143,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": true,\n \"bonusGiven\": {\n \"amount\": \"50000\",\n \"currency\": \"TRY\"\n },\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n### Successful Response (200 OK) — Cancel of a claimed (not-yet-activated) free bet\n\nWhen the player bonus is `CLAIMED` (no money credited yet), `bonusGiven` is `null`\nand there is no claw-back side effect. `finishedAt` is set; `activatedAt` stays\n`null`.\n\n```json\n{\n \"playerBonus\": {\n \"id\": \"0192f730-ceb0-78d2-a4ba-156107b9dbf8\",\n \"bonusId\": \"0192f721-29ae-7aef-9688-7c8bc5508b88\",\n \"bonusName\": [\n {\n \"locale\": \"en_US\",\n \"translate\": \"500 TRY FREE BET\"\n }\n ],\n \"bonusType\": \"INTERNAL_FREE_BET\",\n \"status\": \"CANCELLED\",\n \"externalPlayerId\": \"ext_987654321\",\n \"createdAt\": 1761721205143,\n \"activatedAt\": null,\n \"finishedAt\": 1761725005143,\n \"expiredAt\": null,\n \"expiredOnClaimAt\": 1762326005143,\n \"isAutoActivates\": false,\n \"bonusGiven\": null,\n \"totalWagering\": null,\n \"currency\": \"TRY\"\n }\n}\n```\n\n## Error Responses\n\n### 400 Bad Request - Request Validation Error\n\n```json\n{\n \"errorCode\": 3,\n \"errorMessage\": \"'bonusId' is not a valid UUID: 'foo'\"\n}\n```\n\n### 400 Bad Request - Invalid User\n\n```json\n{\n \"errorCode\": 109,\n \"errorMessage\": \"External player 'ext_987654321' could not be resolved\"\n}\n```\n\n### 400 Bad Request - Player Bonus Not Found\n\nOccurs when no active player bonus (`CLAIMED` or `IN_PROGRESS`) matches the\n(`externalUserId`, `bonusId`) pair. Common causes:\n\n- The player never claimed this bonus.\n- The previously-claimed player bonus already finished (`COMPLETED`, `CANCELLED`,\n `EXPIRED`, `LOST`).\n\n```json\n{\n \"errorCode\": 310,\n \"errorMessage\": \"Active player bonus not found for externalUserId='ext_987654321', bonusId='0192f721-29ae-7aef-9688-7c8bc5508b88'\"\n}\n```\n\n### 400 Bad Request - Player Bonus Not Cancellable\n\nMaps to the legacy `player_bonus.already_cancelled` / `player_bonus.already_finished`\ndomain codes. Occurs in a TOCTOU race between filter and validate when the player\nbonus completes between the find-cancellable lookup and the aggregate-side\nvalidation.\n\n```json\n{\n \"errorCode\": 311,\n \"errorMessage\": \"Player bonus '0192f730-ceb0-78d2-a4ba-156107b9dbf8' cannot be cancelled: already finished\"\n}\n```\n\n### 401 Unauthorized - Invalid Credentials\n\n```json\n{\n \"errorCode\": 2,\n \"errorMessage\": \"Invalid credentials\"\n}\n```\n\n### 500 Internal Server Error - Unknown Error\n\n```json\n{\n \"errorCode\": 1,\n \"errorMessage\": \"Unknown error\"\n}\n```\n\n## Important Notes\n\n1. **System-initiated cancel — no operator id.** The cancellation is attributed to\n the integration as `CANCELLED_BY_SYSTEM`, **not** to a specific operator. The\n calling `brandId` is captured in the action `reason` for traceability. Internal\n admin-side filtering on operator id will not surface these cancels — use the\n action type filter instead.\n\n2. **Async claw-back.** When the player bonus is `IN_PROGRESS` and has `bonusGiven`\n populated, the cancel triggers a payment-service notification to claw back the\n free-bet balance from the bonus wallet. The notification is processed\n asynchronously — the response returns as soon as the bonus aggregate's\n `CANCELLED` event is committed, not after the wallet update. Partners observing\n wallet-side state may see a small eventual-consistency window.\n\n3. **Multiple active player bonuses for the same bonusId.** When the player has\n multiple `CLAIMED`/`IN_PROGRESS` player bonuses for the same bonus (rare —\n usually prevented by the catalogue-side claim limits), the integration cancels\n the **first matching** entry. The contract is intentionally simple — partners\n that need to target a specific player-bonus instance should call admin-side APIs.\n\n4. **Idempotency.** The endpoint is **not** idempotent. A second cancel call for an\n already-cancelled player bonus returns `PLAYER_BONUS_NOT_FOUND` (310) (since the\n integration filters by `CLAIMED`/`IN_PROGRESS`), not a success.\n\n## Authentication\n\nThis endpoint requires HTTP Basic authentication. Per-brand credentials are issued by\nSumstats Support and configured via the operator dashboard. Calls also pass an IP\nwhitelist — requests originating outside the allow-listed IPs are rejected at the\ngateway with HTTP 403.\n\n```http\nAuthorization: Basic base64(username:password)\nContent-Type: application/json\n```\n\nUse the `brandId` body field together with the credentials — Sumstats resolves the brand\nfrom the credentials and validates that the request `brandId` matches.\n"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 311,\n \"errorMessage\": \"Player bonus '0192f730-ceb0-78d2-a4ba-156107b9dbf8' cannot be cancelled: already finished\"\n}"}],"_postman_id":"37ec56b3-bc9c-49c6-9d4a-a9b06f0491d1"}],"id":"51b93457-2ea9-4302-a12b-94d1ce7cac9b","description":"

Requests sent from Casino to Aggregator Provider for the internal sportsbook free-bet Bonus integration. Use these endpoints to discover available free bets, claim/activate/cancel them on behalf of an external player, and inspect a player's current free-bet bonuses. See the Bonus API folder description above for shared conventions (auth, real schema values, polymorphic payloads, MoneyBag, error code families).

\n","_postman_id":"51b93457-2ea9-4302-a12b-94d1ce7cac9b"}],"id":"d2450151-9b90-486e-8d02-3e7f48290cc6","description":"

Bonus API

Aggregator-bound Bonus integration purpose-built for INTERNAL_FREE_BET bonuses on the sportsbook product (InternalFreeBetSportsbookCriteria payload) — discover free bets available for a player, claim/activate/cancel them on behalf of an external player, and inspect the player's current free-bet state.

\n
Scope. This integration covers internal sportsbook free-bet bonuses only. Other bonus types (CUSTOM, FIRST_DEPOSIT, EXTERNAL_FREE_BET, EXTERNAL_FREE_SPINS_WITH_WAGERING, INTERNAL_FREE_SPINS_WITH_WAGERING, CASHBACK) and non-sportsbook free-bet criteria (casino, live-casino, games, virtual) may exist in the operator catalogue but are out of scope for this contract — partners should filter responses to bonusType: \"INTERNAL_FREE_BET\" with bonusSize.rule.productRules[0].criteria.__payloadKind: \"InternalFreeBetSportsbookCriteria\" client-side. winSize and wagering are always null for free bets.
\n

Authentication & Network

All endpoints share the HTTP Basic auth + per-brand IP whitelist used by the rest of the External Casino Client surface. Per-brand credentials are issued by Sumstats Support and configured via the operator dashboard. Calls from non-allowlisted IPs are rejected at the gateway with HTTP 403.

Each request must carry:

Authorization: Basic base64(username:password)
Content-Type: application/json
brandId in the request body matching the brand encoded in the credentials.

Endpoints are exposed under https://ecp-api-<env>.<domain>/external-casino-client/v1/bonus/....

Modeling notes

Find Available Bonuses returns a slim free-bet catalogue object with the polymorphic bonusSize payload intact, so partners can render the offer faithfully. UI-only fields (descriptions, preview images, full T&Cs), operator metadata (operatorId, ruleIds, removedAt, updatedAt), and share-limits routing are dropped.
Find Player Bonuses / Claim / Activate / Cancel return a slim playerBonus shape with bonusSnapshot collapsed into bonusId + bonusName + bonusType and bonusGiven projected to plain {amount, currency} in the player's currency. totalWagering is always null for free bets.
Cancel attributes the action to the integration as CANCELLED_BY_SYSTEM — no operator id involved. The calling brandId is captured in the action reason field for audit trails.

Real schema values

Sportsbook fields use real values from the generated SportsbookSchema:

betRule.betTypes — BetHashType enum, JSON-serialised lowercase via Jackson @JsonProperty. Possible values: \"single\", \"parlay\" (accumulator), \"system\". Note: \"accumulator\" is not a real value — the schema name for accumulator bets is parlay.
filters[].markets — MarketType enum from the generated SportsbookSchema, JSON-serialised as the lowercase enum name. Examples: score_1x2, score_ou, score_dc, score_both_to_score_yes_no, score_ht_ft, score_winning_margin, score_exact_number, corner_1x2, yellow_card_1x2, red_card_1x2. The set of valid market types is generated from the operator's sportsbook configuration.
sportId, categoryId, tournamentId, eventId — operator-defined UUIDs, not system enums. Partners must map these via their own catalogue synchronisation with the operator.

Polymorphic payloads

Several response objects are polymorphic (sealed) hierarchies discriminated by an explicit __payloadKind string field. For the INTERNAL_FREE_BET sportsbook bonuses this integration handles, the relevant unions are:

bonusSize — always FreeBetSize.
bonusSize.amount (free-bet balance) — MonetarySize (fixed) or PercentageSize (rare for free bets).
bonusSize.rule.productRules[].criteria — always InternalFreeBetSportsbookCriteria for this contract.
bonusSize.rule.freeBetUseType — FreeBetAllBalanceUseType (stake = full free-bet balance) or FreeBetPartialBalanceUseType (stake mixes free-bet + real money).

Partners must discriminate on __payloadKind — adding new payload kinds is the standard evolution path.

MoneyBag shape

Examples in this document use only the system amount in a single currency:

{\n  \"system\": { \"amount\": \"50000\", \"currency\": \"TRY\" },\n  \"additional\": []\n}\n

system carries the amount in the bonus's currency. additional is the array of per-currency overrides for cross-currency bonuses — when the player's currency matches an entry's currency, the entry's amount is used directly; otherwise the system amount is converted via the operator's currency-pair rates. Single-currency bonuses (the common case) emit an empty additional array, as in all examples here. The amount is a string in raw integer minor-unit form (\"50000\" = 500.00 TRY) — partners should not assume floating-point representation.

Error code conventions

Errors share the common ECP envelope { \"errorCode\": <int>, \"errorMessage\": <string> }. Bonus-specific codes occupy the 300-range:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Code	Constant	Family
301	BONUS_NOT_FOUND	Bonus catalogue
302	BONUS_DISABLED	Bonus catalogue
303	BONUS_NOT_AVAILABLE	Bonus catalogue
304	BONUS_USER_LIMITS_EXCEEDED	Limits
305	BONUS_TOTAL_LIMITS_EXCEEDED	Limits
306	BONUS_ELIGIBILITY_CLAIM_RULES_NOT_SATISFIED	Eligibility
307	PLAYER_BONUS_ALREADY_CLAIMED	Player bonus
308	BONUS_ONE_PER_PLAYER_TAG_VIOLATION	Tags
309	BONUS_NEW_CUSTOMER_TAG_VIOLATION	Tags
310	PLAYER_BONUS_NOT_FOUND	Player bonus
311	PLAYER_BONUS_NOT_CANCELLABLE	Player bonus
312	PLAYER_BONUS_ALREADY_ACTIVATED	Player bonus
313	BONUS_ELIGIBILITY_ACTIVATE_RULES_NOT_SATISFIED	Eligibility

Common ECP-level codes (2 INVALID_CREDENTIALS, 3 BAD_REQUEST, 4 DESERIALIZATION_ERROR, 109 INVALID_USER, 1 UNKNOWN) apply to all endpoints.

\n","_postman_id":"d2450151-9b90-486e-8d02-3e7f48290cc6"},{"name":"Error Response","item":[],"id":"37151abb-1eec-40c7-882f-90471da920b5","description":"

Error response from Casino to Aggregator Provider and vice versa is the same

Status Code: not 200

Response Body Description:

Object:

errorCode (integer, required)
\n
errorMessage (string, reqiured)
\n

Error Codes:

Code	Reason
1	INTERNAL_SERVER_ERROR
2	INVALID_CREDENTIALS
3	BAD_REQUEST
4	DESERIALIZATION_ERROR
5	NETWORK_ERROR
6	TIMEOUT_ERROR
101	PROVIDER_NOT_ACTIVE
102	PROVIDER_ERROR
103	GAME_NOT_ACTIVE
104	GAME_NOT_FOUND
105	GAME_DEMO_NOT_SUPPORTED
106	USER_INSUFFICIENT_BALANCE
107	USER_CREATION_FAILED
109	INVALID_USER
110	DISABLED_USER
111	CURRENCY_NOT_SUPPORTED
112	USER_SESSION_EXPIRED
113	ROUND_HISTORY_NOT_SUPPORTED
114	FREE_SPINS_NOT_SUPPORTED
115	ROUND_NOT_FOUND
116	TRANSACTION_NOT_FOUND
117	PROVIDER_NOT_FOUND
118	LOBBY_DISABLED
201	ROLLED_BACK_TRANSACTION_NOT_FOUND
202	INVALID_ROLLED_BACK_TRANSACTION_TYPE
203	AFFILIATE_NOT_FOUND
204	AFFILIATE_LINK_NOT_FOUND
205	MISSING_TRACKING_CODE
206	INVALID_TRACKING_CODE_TOKEN
207	UNSUPPORTED_TRACKING_CODE_VERSION
208	MALFORMED_TRACKING_CODE
209	EXPIRED_TRACKING_CODE
250	DOMAIN_UPDATING_FAILED

Response Example:

{\n  \"errorCode\": 2,\n  \"errorMessage\": \"Invalid credentials\"\n}\n\n

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"8833b7d6-e08c-417d-a484-7e36436b22cd"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"037d69a1-416b-4c64-859c-80a1883d8b8e"}}],"_postman_id":"37151abb-1eec-40c7-882f-90471da920b5"},{"name":"General clarifications","item":[],"id":"78ddc1bc-a249-4151-b8b9-a27c4e170bcc","description":"

All responses to transaction callbacks must be idempotent
\n
Rollback transaction callback can be both for bet and win transactions
\n
Rollback transaction can be sent before transaction to rollback.
In this case rollback should be accepted and if transaction to rollback came later, it should be accepted too and response should be successful.
For both callbacks no balance changes must be processed
\n
Average response time should be no more than 500 ms for good user experience. Request will be aborted if there is no response more than 5 seconds
\n
In case of loss win with 0 amount will be sent
\n
End round callback doesn't produce any transaction. It is notification about round end
\n
Bets can be with amount 0
\n
Bets with 0 amount are retriable
\n
Bets with 0 amount must be always accepted
\n
Bets with not 0 amount are not retriable. Failed bet will cause rollback on bet
\n
Wins and Rollbacks are retriable
\n
Wins and Rollbacks must be always accepted
\n
If game has empty betValues, then it doesn't support free spins
\n

\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"93d3f271-30ef-43e6-b196-7fae9c7dacad"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"093cb173-e237-4cd5-adc6-cc45dd5ceee1"}}],"_postman_id":"78ddc1bc-a249-4151-b8b9-a27c4e170bcc"},{"name":"Domains API","item":[{"name":"Aggregator API","item":[{"name":"Update domain","id":"c0455d25-d76a-42b1-aae9-aba29abd39a4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"domain\": {\n \"type\": \"EXTERNAL\",\n \"name\": \"example.com\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/domains/target/update","description":"

Endpoint for Updating Casino Domain

Endpoint

POST /external-casino-client/v1/domains/target/update

Description

This endpoint allows external casino systems to change the current domain value of a casino. Traffic is redirected to this domain, which serves as the target for incoming traffic across various system components.

Request Body Description

Object:

brandId (integer, required) - Brand id provided by aggregator provider. Must be a valid brand identifier.
\n
domain (string, required) - Domain to update.
\n
- type (enum, required) - Domain type. Valid values:
  \n
  - EXTERNAL - External type.
  \n
- name (string, required) - Domain name. Must be a valid domain name (for example example.com).
  \n
\n

Response Body Description

Object:

brandId (integer, required) - Brand id provided by aggregator provider.
\n
domain (object, required) - Updated domain. This is the domain that was successfully updated in the system.
\n
- type (enum, required) - Domain type.
  \n
- name (string, required) - Updated domain name.
  \n
\n

\n","urlObject":{"path":["external-casino-client","v1","domains","target","update"],"host":["{apiUrl}"],"query":[],"variable":[]}},"response":[{"id":"5a18d450-225f-41f5-b66c-f3cbc3999507","name":"success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"domain\": {\n \"type\": \"EXTERNAL\",\n \"name\": \"example.com\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/domains/target/update"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"brandId\": 0,\n \"domain\": \"example.com\"\n}"},{"id":"1bc2a25d-44f0-4c0e-b2b5-0e73b397330e","name":"fail","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"brandId\": 0,\n \"domain\": {\n \"type\": \"EXTERNAL\",\n \"name\": \"example.com\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{apiUrl}/external-casino-client/v1/domains/target/update"},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"errorCode\": 250,\n \"errorMessage\": \"Failed to update domain\"\n}"}],"_postman_id":"c0455d25-d76a-42b1-aae9-aba29abd39a4"}],"id":"eb06b2b9-0a35-4e68-a8f6-88314e9653eb","_postman_id":"eb06b2b9-0a35-4e68-a8f6-88314e9653eb","description":""}],"id":"40b0ff50-1a68-4bdf-ac3b-a048f138f799","_postman_id":"40b0ff50-1a68-4bdf-ac3b-a048f138f799","description":""}],"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"9092af26-aa99-4c41-91b7-7f3a52947bfc"}},{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":[""],"id":"ebf2b095-7f7b-4f73-ac3d-504f0d588229"}}],"variable":[{"key":"apiUrl","value":"{apiUrl}"},{"key":"username","value":"{username}"},{"key":"password","value":"{password}"},{"key":"callbackUrl","value":"{callbackUrl}"}]}

Changelog

Introduction

Formats

Money

Date And Time

Locale

Security

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Request Body Description:

Response Body Description:

Transaction Details

Object

Example payload

Bet Structure

Object

Reading picksPerSelection

Outcome

Object

Sports

Pagination

cursor (object, optional)

where (object, optional)

order (array, optional)

page (response object)

Iterating forward

Request Body Description:

whereFieldPaths

orderByFieldPaths

Response Body Description:

Request Body Description:

whereFieldPaths

orderByFieldPaths

Response Body Description:

Request Body Description:

whereFieldPaths

orderByFieldPaths

Response Body Description:

Endpoint for Customer Registration

Endpoint

Description

Request Body Description

Response Body Description

Request Example

Reading `picksPerSelection`

`cursor` (object, optional)

`where` (object, optional)

`order` (array, optional)

`page` (response object)

`whereFieldPaths`

`orderByFieldPaths`

`whereFieldPaths`

`orderByFieldPaths`

`whereFieldPaths`

`orderByFieldPaths`

1. Tracking Codes (`TRACKING_CODE`)

2. Link Codes (`LINK_CODE`)