> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igamingace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bonus Call Register

The register endpoint starts a bonus campaign for a specific player. You specify whether it's a Free Spin Bonus (predefined free spins) or a Regular Bonus Call (a guaranteed winning amount). Only one active bonus call can run per player at a time. Once the bonus completes in one of the configured games, it will not be triggered again for any other game in the same registration.

## Request

**Endpoint:** `POST /v1/bonus-call/register`

**Headers**

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

### Request body

<ParamField body="platformId" type="string" required>
  Your own unique identifier for this bonus request.
</ParamField>

<ParamField body="providerId" type="number" required>
  The numeric ID of the game provider under which the bonus will be active.
</ParamField>

<ParamField body="gameId" type="number" required>
  Specifies which games can trigger the bonus event.
</ParamField>

<ParamField body="playerId" type="string" required>
  The player's unique identifier in your system.
</ParamField>

<ParamField body="bonusType" type="number" required>
  The type of bonus to register.

  * `1` — Free Spin Bonus. The player receives a set number of free spins; `callAmount` acts as the maximum win cap. Available for Pragmatic Play only.
  * `2` — Regular Bonus Call. The player is guaranteed to win the `callAmount` by the end of the campaign. This Regular Bonus is not active at the moment. Only Free Spin Bonus is available at the moment.
</ParamField>

<ParamField body="callAmount" type="number" required>
  The monetary value associated with the bonus.

  * For `bonusType = 1`: the maximum amount the player can win across all free spins.
  * For `bonusType = 2`: the player will win exactly this amount.
</ParamField>

<ParamField body="expireAt" type="string" required>
  The timestamp at which the bonus expires, in `YYYY-MM-DD HH:mm:ss` format (e.g., `"2026-12-01 23:59:59"`).
</ParamField>

<ParamField body="metaData" type="object">
  Additional configuration for the bonus. Required when `bonusType = 1`.

  <Expandable title="metaData fields">
    <ParamField body="metaData.spinAmount" type="number" required>
      Number of free spins to award. Minimum: `1`, Maximum: `100`.
    </ParamField>

    <ParamField body="metaData.baseBetAmount" type="number" required>
      Base bet amount. Example: for a 2 USD free spin, use `baseBetAmount: 2`
    </ParamField>
  </Expandable>
</ParamField>

### Example request

```bash theme={null}
curl --request POST \
  --url https://api.igamingace.com/v1/bonus-call/register \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "issueId": "promo_oct_001",
    "providerId": 1,
    "gameId": 655,
    "playerId": "player_88888",
    "bonusType": 1,
    "callAmount": 500,
    "expireAt": "2026-12-01 23:59:59",
    "metaData": {
      "spinAmount": 20,
      "baseBetAmount": 2
    }
  }'
```

<Note>
  For a Regular Bonus Call (`bonusType = 2`), you can omit `metaData` entirely. For a Free Spin Bonus (`bonusType = 1`), both `metaData.spinAmount` and `metaData.baseBetAmount` are required.
</Note>

***

## Response

On success, the API returns the `issueId` you should store to track or cancel the bonus later.

<ResponseField name="success" type="bool">
  `true` when the API call was processed without errors.
</ResponseField>

<ResponseField name="message" type="string">
  A short confirmation string, typically `"OK"`.
</ResponseField>

<ResponseField name="data" type="object">
  The result payload.

  <Expandable title="data fields">
    <ResponseField name="data.issueId" type="long">
      The unique identifier for the registered bonus call. Store this value — you need it to check status or cancel the bonus.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example response

```json theme={null}
{
  "success": true,
  "message": "OK",
  "data": {
    "issueId": 10001
  }
}
```