API Integration (v2 - FlashWins)

API integration setup

When you choose Use your own widget (API mode), you build the front-end and read campaign data from the public FlowsPlay Game API. The Appearance and Text tabs do not apply, because you control the look yourself.

Prizes are still awarded and credited server-side. The API gives you the data to render the experience: which campaign is running, how many prizes are left, the time window, and the player's opt-in status.

Base API URL

https://api.flowsplay.world/game/v2/

All FlashWins endpoints are version 2.0. The paths below are relative to this base.

Site ID

Every call needs your siteId, available in the FlowsPlay admin panel under Site Settings. Other identifiers you will use:

Identifier	What it is
`flashWinId`	The campaign's public ID.
`gameId`	The game the player is in.
`sessionId`	A player session identifier, used for front-end opt-in calls.
`playerId`	The player's account identifier, used for secured server-to-server opt-in calls.
`brandId`	Optional, for brand-scoped campaigns.

Authentication

Front-end calls (campaign data and session-based opt-in) need no API key. They are designed to be called directly from the front-end.
Server-to-server calls (player-id opt-in) require your site API key in the x-api-key header.

Sequence overview

The player opens a game. Call 1 to fetch the active campaign and its remaining prizes.
If the campaign requires opt-in, call 2 to check the player's status, and 3 to opt them in.
Render your widget from the campaign data, and poll 1 at a steady interval to keep the prize count and timer current.

1. Fetch FlashWins information for a game

GET /sites/{siteId}/flashwins/games/{gameId}

Returns the active campaign for that game, with the data needed to render your widget.

Field	Meaning
`flashWinId`	The campaign ID.
`open`	Whether the campaign is currently open.
`startTime` / `endTime`	Window start and end, as Unix timestamps.
`currency`	The base currency of the prizes.
`requiresOptIn`	Whether the player must opt in.
`remainingPrizes`	Total prizes still available.
`prizes`	Each prize: type (Cash or Bonus), amount, quantity, and remaining.
`status`	The campaign status.

For brand-scoped campaigns, use the brand variant:

GET /sites/{siteId}/flashwins/games/{gameId}/brand/{brandId}

2. Get player opt-in status

From the front-end, using the session ID (no API key):

GET /sites/{siteId}/flashwins/{flashWinId}/players/sessions/{sessionId}/optinstatus

From your server, using the player ID (requires the API key):

GET /sites/{siteId}/flashwins/{flashWinId}/players/{playerId}/optinstatus

Returns the player's current choice:

{ "isOptedIn": true }

3. Update player opt-in status

From the front-end (session ID) or your server (player ID):

PATCH /sites/{siteId}/flashwins/{flashWinId}/players/sessions/{sessionId}/optinstatus
PATCH /sites/{siteId}/flashwins/{flashWinId}/players/{playerId}/optinstatus

Send the player's choice in the body:

{ "isOptedIn": true }

Brand-scoped variants add /brand/{brandId} before /optinstatus.

4. Appearance and stylesheet (optional)

If you want Flows-managed styling for an otherwise custom widget, two endpoints return the configured appearance and a stylesheet. If you style your own widget, you do not need these.

GET /sites/{siteId}/flashwins/{flashWinId}/appearance?locale={locale}
GET /sites/{siteId}/flashwins/{flashWinId}/style.css

Notes

Prizes are awarded and credited server-side on the qualifying spin. To show the Win state in your own widget, subscribe to the push event service. See Receive FlashWins Events.
Full request and response schemas are in the Swagger reference.

Additional resources

Swagger documentation: https://api.flowsplay.world/game/swagger/index.html