checkUserResults(play_id)
Purpose
Returns the results for a specific user play after the draw has been completed.
This is how users find out if they matched numbers and won money.
Endpoint
GET /api/check-results/{play_id}
Authorization
- Required Scope:
user.read
- Token: Bearer Token from user session
Parameters
| Name |
Type |
Required |
Description |
| play_id |
string |
✅ |
The unique play submitted by the user |
Response: Success (200 OK)
{
"play_id": "play_12345",
"game": "powerball",
"draw_date": "2025-06-25",
"matched_numbers": [5, 23, 34],
"special_match": false,
"prize_tier": "tier_4",
"payout": 100.00,
"status": "won"
}
Status Values
| Value |
Meaning |
| won |
Prize awarded |
| lost |
No prize |
| void |
Play was invalidated |
| pending |
Draw has not occurred yet |
Error States
| HTTP Code |
Error Key |
Description |
| 404 |
play_not_found |
Play ID does not exist |
| 403 |
unauthorized |
User cannot access this play |
| 409 |
draw_pending |
Draw hasn’t occurred yet, results not ready |
Integration Notes
- Results are only returned after the draw lock time.
- Used to trigger UI elements like prize banners and CTA for redemption.
- A webhook can be optionally used to notify users of winning plays.
Prize Handling
- Winning plays may auto-route to
initiatePayout() if < $600.
- Over-threshold wins will require triggering
submitKYC().