Tracking Sports Betting Events

Send sports ticket events with full lifecycle coverage: open, win, lose, cashout, refund, cancel and pending.

All API requests require an API Key passed via the X-API-Key header. Obtain yours at Dashboard → Settings → API Keys.

X-API-Key: your_api_key_here

Event Types

Sports events follow a full ticket lifecycle. All events are sent to POST /api/v1/sport. The Kafka topic is fixed: atlas.events.raw.sportsbook.

Event	When to Send	selections
open	Ticket placed. Full snapshot of all selections.	Required — send all selections
win	One or more selections resolved as won.	Required — send only the selections that changed
lose	One or more selections resolved as lost.	Required — send only the selections that changed
cashout	Ticket closed early by the player.	Required — send only the selections that changed
refund	Ticket refunded after acceptance (operator-side reversal, e.g., event voided).	Required — send the selections impacted
cancel	Ticket cancelled before resolution (e.g., declined by trading, market suspended).	Required — send the selections impacted
pending	Ticket awaiting resolution (held for risk review, awaiting settlement, etc.).	Required — send the current snapshot

A ticket can have multiple selections (parlay/multiple bet). Sending a win, lose, or cashout event with only the changed selections allows the ticket to remain open until all selections resolve. The ticket_status reflects the overall ticket state, while each selection_status reflects individual outcomes.

All events for the same ticket share the same bet_id.

Track Ticket Open

curl -X POST https://events.atlas.io/api/v1/sport \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "org_abc123",
    "brand_id": "brand_xyz",
    "event": "open",
    "user_id": "user_12345",
    "currency": "BRL",
    "bet_id": "bet_abc_001",
    "bet_dt": "2026-03-11T14:30:00Z",
    "ticket_status": "open",
    "bet_type": "MULTIPLE",
    "bet_timing": "PREMATCH",
    "bet_platform": "MOBILE",
    "bet_virtual": false,
    "bet_amount": 50.00,
    "bet_amount_bonus": 0.00,
    "bet_odds": 3.50,
    "before_balance": 250.00,
    "after_balance": 200.00,
    "selections": [
      {
        "selection_id": "sel_001",
        "selection_status": "open",
        "selection_choice": "Vasco",
        "selection_sport_type": "Soccer",
        "selection_league": "Brasileirão Série A",
        "selection_competitors": ["Flamengo", "Vasco"],
        "selection_home_team": "Flamengo",
        "selection_away_team": "Vasco",
        "selection_market": "1x2",
        "selection_odds": 2.90,
        "selection_is_live": false,
        "selection_virtual": false,
        "sport_match_id": "flamengo_vs_vasco_20260311"
      }
    ]
  }'

Track Ticket Win

curl -X POST https://events.atlas.io/api/v1/sport \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "org_abc123",
    "brand_id": "brand_xyz",
    "event": "win",
    "user_id": "user_12345",
    "currency": "BRL",
    "bet_id": "bet_abc_001",
    "bet_dt": "2026-03-11T16:00:00Z",
    "ticket_status": "win",
    "bet_amount": 50.00,
    "bet_odds": 3.50,
    "win_amount": 175.00,
    "before_balance": 200.00,
    "after_balance": 375.00,
    "selections": [
      { "selection_id": "sel_001", "selection_status": "win" },
      { "selection_id": "sel_002", "selection_status": "win" }
    ]
  }'

Track Ticket Lose

curl -X POST https://events.atlas.io/api/v1/sport \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "org_abc123",
    "brand_id": "brand_xyz",
    "event": "lose",
    "user_id": "user_12345",
    "currency": "BRL",
    "bet_id": "bet_abc_002",
    "bet_dt": "2026-03-11T16:00:00Z",
    "ticket_status": "lose",
    "bet_amount": 50.00,
    "bet_odds": 2.10,
    "win_amount": 0.00,
    "before_balance": 200.00,
    "after_balance": 200.00,
    "selections": [
      { "selection_id": "sel_003", "selection_status": "lose" }
    ]
  }'

Track Ticket Cashout

curl -X POST https://events.atlas.io/api/v1/sport \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "org_abc123",
    "brand_id": "brand_xyz",
    "event": "cashout",
    "user_id": "user_12345",
    "currency": "BRL",
    "bet_id": "bet_abc_003",
    "bet_dt": "2026-03-11T15:45:00Z",
    "ticket_status": "cashout",
    "bet_amount": 50.00,
    "bet_odds": 3.50,
    "win_amount": 30.00,
    "before_balance": 200.00,
    "after_balance": 230.00,
    "selections": [
      { "selection_id": "sel_004", "selection_status": "cashout" }
    ]
  }'

Request Fields

Envelope Fields (all events)

org_id · string · required

Organization identifier.

brand_id · string · required

Brand identifier.

event · string · required

Event type. Allowed values: open, win, lose, cashout, refund, cancel, pending.

ip · string

Player IP address at event time.

geolocation_lat · number

Player latitude at event time.

geolocation_long · number

Player longitude at event time.

is_test · boolean

Marks the event as operator test traffic. When true, the event is accepted (202) but rerouted to an audit-only store — it never appears in analytics, dashboards or risk scoring. Defaults to false when omitted.

Ticket Fields

user_id · string · required

Your internal user identifier. Must be consistent for the player.

currency · string · required

ISO 4217 currency code (for example: BRL).

bet_id · string · required

Ticket identifier used to correlate open, win, lose and cashout events.

bet_dt · string · required

ISO 8601 timestamp for the event in the ticket lifecycle.

ticket_status · string · required

Current ticket status. Allowed values: open, win, lose, cashout, cancel, reject, refund.

bet_type · string

Allowed values: SINGLE, MULTIPLE, SYSTEM.

bet_amount · number

Bet amount (real + bonus according to your accounting model).

bet_amount_bonus · number

Bonus portion of the stake.

bet_odds · number

Combined odds for the ticket.

bet_platform · string

Allowed values: WEB, MOBILE, APP.

bet_timing · string

Allowed values: LIVE, PREMATCH.

bet_virtual · boolean

Indicates whether this is a virtual sports ticket.

win_amount · number

Amount won. 0 or omit for open. 0 for a losing ticket.

before_balance · number

Balance before ticket update.

after_balance · number

Balance after ticket update.

Selection Fields

selections · array · required

Always required (min 1). For open, send the full snapshot of all selections. For win, lose, and cashout, send only the selections that changed status.

selections[].selection_id · string · required

Stable selection identifier inside the ticket.

selections[].selection_status · string · required

Current status of the selection. Allowed values: open, win, lose, cashout, cancel, refund, partial_win, partial_lose.

selections[].selection_choice · string

Chosen option inside the market (for market 1x2, the choice can be Vasco).

selections[].selection_sport_type · string

Sport category (for example Soccer, Basketball).

selections[].selection_league · string

League or competition name.

selections[].selection_competitors · array

Competitor names as provided by your trading feed.

selections[].selection_home_team · string

Home team name.

selections[].selection_away_team · string

Away team name.

selections[].selection_market · string

Market name (for example 1x2, Handicap, Total Goals).

selections[].selection_odds · number

Odds for this selection.

selections[].selection_is_live · boolean

Indicates whether selection was in-play.

selections[].selection_virtual · boolean

Indicates whether selection belongs to a virtual event.

selections[].sport_match_id · string

Match identifier in your sportsbook feed.

selections[].selection_event_name · string

Optional event name for the selection in your feed model.

GGR Calculation (Sports)

Sports Turnover = sum(open.bet_amount)
Sports GGR = sum(open.bet_amount) - sum(win.win_amount)