> For the complete documentation index, see [llms.txt](https://scorpioplay.gitbook.io/scorpio-play-casino-api-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://scorpioplay.gitbook.io/scorpio-play-casino-api-doc/api-reference/openapi/v1-bonus-call-register.md).

# /v1/bonus-call/register

## Register a bonus call

<mark style="color:$success;">`POST`</mark> `/v1/bonus-call/register`

Initiates a bonus call session for a user. This endpoint validates eligibility, executes the bonus logic, and returns an issue ID which can be used for tracking or further management.

When registering a bonus call, you need to configure the `gameCode` field, you can define whether the bonus event should be triggered for specific games or for all games under the selected provider.

If `gameCode` is configured as an array of game codes, the bonus event will be triggered when the player enters any one of the specified games. Multiple game codes can be added to the array, allowing the bonus to be activated by different games within the same provider.

Example:

<pre class="language-json"><code class="lang-json"><strong>gameCode: ["vs20olympx", "vswaysdogs", "vs20fruitsw"]
</strong></code></pre>

In this example, the bonus event will be triggered when the player enters either `vssuef` or `fblsoe`.

If `gameCode` is configured as `"all"`, the bonus event will be triggered when the player enters any game under the selected provider, without applying any game-specific filtering.

Example:

```json
gameCode: "all"
```

This option is recommended when the bonus should apply globally to all games provided by the selected provider.

{% hint style="info" %}
Once a bonus call is completed in one of the selected games, it will not be triggered again for other selected games.
{% endhint %}

**Headers**

| Name          | Value                |
| ------------- | -------------------- |
| Authorization | `Bearer <API_TOKEN>` |
| Content-Type  | `application/json`   |
| Accept        | `application/json`   |

**Request Body**

<table><thead><tr><th width="163">Field</th><th width="116">Data Type</th><th width="364">Meaning</th><th>Mandatory</th></tr></thead><tbody><tr><td>issueId</td><td>string</td><td>Unique ID for the issue or request</td><td>Optional</td></tr><tr><td>providerId</td><td>number</td><td>Game provider ID</td><td>Required</td></tr><tr><td>gameCode</td><td>string[]/<br>string</td><td><p>Specifies which games can trigger the bonus event.</p><ul><li>If an array of game codes is provided, the bonus will be triggered when the player enters any one of the specified games.</li><li>If the value is <code>"all"</code>, the bonus will be triggered when the player enters any game under the selected provider.</li></ul></td><td>Required</td></tr><tr><td>playerExternalId</td><td>string</td><td>Player’s unique ID on the operator side</td><td>Required</td></tr><tr><td>currency</td><td>string</td><td>Currency code (e.g., USD)</td><td>Required</td></tr><tr><td>bonusType</td><td>number</td><td>Type of bonus (1 = regular bonus call, 2 = free spin bonus)<br>Free spin bonus(bonusType=2) is available for only Pragmatic Play and EGT Digital</td><td>Required</td></tr><tr><td>callAmount</td><td>number</td><td>Amount related to the bonus call.<br>If bonusType = 1, the player will surely win this amount by any means.<br>And if bonusType = 2, this amount is a max win amount, the player can not win more than this callAmount.</td><td>Required</td></tr><tr><td>expireAt</td><td>string</td><td>Expire timestamp with ISO string.<br>(YYYY-MM-DD HH:mm:ss)<br>For example, 2026-12-01 23:59:59</td><td>Required</td></tr><tr><td>metaData</td><td>object</td><td>Object containing detailed bonus information.<br>If bonusType = 2, this  is required.</td><td>Optional</td></tr><tr><td>metaData.spinAmount</td><td>number</td><td>Number of free bonus spins. Min: 10, Max: 100</td><td>Required</td></tr><tr><td>metaData.baseBetAmount</td><td>number</td><td>Base bet amount.<br>Example: for a 2 USD free spin, use <code>baseBetAmount: 2</code></td><td>Required</td></tr></tbody></table>

**Response**

```json
{
  "success": true,
  "message": "OK",
  "data": {
    "issueId": "issueId_001"
  }
}
```

<table><thead><tr><th width="119">Field</th><th width="115">Data Type</th><th>Meaning</th></tr></thead><tbody><tr><td>success</td><td>boolean</td><td>Indicates whether the API call succeeded</td></tr><tr><td>message</td><td>string</td><td>Textual confirmation of the API call</td></tr><tr><td>data</td><td>object</td><td>Object containing the result of the request</td></tr><tr><td>issueId</td><td>string</td><td>Unique ID for the issue or request (inside data)</td></tr></tbody></table>