Skip to content

Advisory bets

An advisory bet is one in which risk management is not applied. The bookmaker assumes responsibility for risk management and the calculation of results for such bets. This API works fast, with near-zero latency. The bookmaker must notify DATA.BET when a bet has been won, lost, canceled, or cashed out. Advisory bet API consists of two endpoints: one for bet placement and another for bet update. Bet update MUST be sent of every bet state change. Any change to selection status, cash-out, bet status is considered as bet state change as it may influence bet settlement. advisory_bet_flow

How to work with API

Whenever a player places a bet, the bookmaker has to call a REST API method (POST /bets/advisory) to send it to DATA.BET and receive some restrictions that are advised to be applied to that bet. If the bet was declined, then the bookmaker has to notify DATA.BET by sending that update to another REST API method (PUT /bets/advisory/{bet_id}) where {bet_id} has to be replaced with bookmakers bet_id sent to the first method (POST /bets/advisory).

For all further bet state changes the bet MUST be sent to update the REST API method (PUT /bets/advisory/{bet_id}) with the full bet state, the bet will be replaced with actual state in PUT request,

Please, take into account - PUT api fully replace the bet state

For example, if the previous version of the bet has a selection for sport-event ID 1 and the bet in the PUT request has only a selection for sport-event ID 2, the selection for sport-event ID 1 will be removed from the bet.

Response body from the update MAY be ignored, but status code SHOULD be taken into account and retry performed on error (be careful not to fall into the loop if some parameters were invalid. In that case report the problem to your account manager and specify bet id).

Use cases and examples

Single bet on DATA.BET event. Accepted by the bookmaker Bookmaker sends the bet to the API with the following body (please refer to the docs of Bet type for the meaning of each field API swagger or the swagger document we gave you):

Request 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "bet_id": "m7k6BN4yRaibEtlPYxmvSGOiUXEEF9IAAAxiqwAQ",
  "site_id": "demo.data.bet",
  "type": {
    "code": 0,
    "system_sizes": [
      1
    ]
  },
  "stake": {
    "value": "5.25",
    "currency_code": "USD"
  },
  "selections": [
    {
      "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
      "market_id": "20",
      "odd_id": "1",
      "value": "2.31"
    }
  ],
  "foreign_selections": [],
  "player_id": "1",
  "client_ip": "138.68.173.29",
  "country_code": "GB",
  "created_at": "2019-07-24T15:55:20+00:00"
}

Here you can see the best info and the list of the restrictions DATA.BET advises to apply. You MAY ignore it and make decisions on your own.

Response 
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
{
  "bet": {
    "id": "m7k6BN4yRaibEtlPYxmvSGOiUXEEF9IAAAxiqwAQ",
    "status": {
      "code": 1,
      "reason": ""
    },
    "type": {
      "code": 0,
      "system_sizes": [
        1
      ]
    },
    "stake": {
      "value": "5.25",
      "currency_code": "USD"
    },
    "refund": {
      "value": "5.25",
      "currency_code": "USD"
    },
    "selections": [
      {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
        "market_id": "20",
        "odd_id": "1",
        "value": "2.31"
      }
    ],
    "foreign_selections": [],
    "foreign_cash_out_orders": [],
    "player_info": {
      "client_ip": "138.68.173.29",
      "country_code": "GB"
    },
    "created_at": "2019-07-24T15:55:20+00:00",
    "cash_out_orders": {}
  },
  "restrictions": [
    {
      "type": "bet_type",
      "context": {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
        "bet_type": 0
      }
    },
    {
      "type": "max_bet",
      "context": {
        "max_bet": "10.00",
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472"
      }
    },
    {
      "type": "bet_interval",
      "context": {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
        "time_to_wait": "10.00"
      }
    },
    {
      "type": "selection_value",
      "context": {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
        "market_id": "20",
        "odd_id": "1",
        "value": "2.71"
      }
    },
    {
      "type": "sport_event_status",
      "context": {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
        "status": 1
      }
    },
    {
      "type": "sport_event_existence",
      "context": {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472"
      }
    },
    {
      "type": "market_status",
      "context": {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
        "market_id": "20",
        "status": 1
      }
    },
    {
      "type": "market_existence",
      "context": {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
        "market_id": "20"
      }
    },
    {
      "type": "odd_status",
      "context": {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
        "market_id": "20",
        "odd_id": "1",
        "status": 1,
        "is_active": true
      }
    },
    {
      "type": "odd_existence",
      "context": {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
        "market_id": "20",
        "odd_id": "1"
      }
    },
    {
      "type": "sport_event_bet_stop",
      "context": {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472"
      }
    },
    {
      "type": "market_defective",
      "context": {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
        "market_id": "20"
      }
    }
  ]
}

Express

DATA.BET events only

(multi bet, accumulator) bet on DATA.BET events only In this case, everything is the same as for a single bet except the bet_type, which should be 1 (accumulator bet), system_sizes MUST be set equal to the number of selections. The main difference is shown below:

Request 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
"type": {
    "code": 1,// Was 0, now 1
    "system_sizes": [
      2 // **MUST** be equal to the number of selections
    ]
  }
...
"selections": [
    {
      "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
      "market_id": "20",
      "odd_id": "1",
      "value": "2.31"
    },
    {
      "sport_event_id": "37d9527e-dcb0-11ee-b550-970237045c41",
      "market_id": "1",
      "odd_id": "3",
      "value": "5.01"
    }
]
A split bet

Express bet on DATA.BET and non-DATA.BET events The bet looks pretty much the same as the only DATA.BET express, but here a new field foreign_selections is introduced, where all of the selections are made on non-DATA.BET events MUST be sent. The required fields are id and value, but it’s highly recommended to pass other fields also.

  • sport_event_title - is a string title of the sports event the user sees (for example NaVi - Fnatic);
  • sport - the name of the sport or DATA.BETs’ sport_id if the bookmaker was able to map it;
  • market_name - for example: winner or total maps;
  • odd_name - for example: Over 1.5.
Request 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
...
  "selections": [
    {
      "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
      "market_id": "20",
      "odd_id": "1",
      "value": "2.31"
    }
  ],
  "foreign_selections": [
    {
      "id": "some-id-of-the-non-databet-sport-event",
      "value": "2.31",
      "sport_event_title": "string",
      "sport": "football",
      "market_name": "string",
      "odd_name": "string"
    }
  ]
...
}

System bet

A system bet is very similar to the express bet, except for the system_size field and the type. In the system_size field user selected sizes MUST be passed. The maximum digit in the array is the number for selections. Minimum - is 2. For example, if a user makes a bet on 4 selections, he/she can choose system size from 2 to 4. The appropriate virtual expresses/multi bets would be generated based on that number (expresses with 2, 3, or/and 4 selections).

Request 
1
2
3
4
5
6
"type": {
  "code": 2,// Was 1, now 2
  "system_sizes": [
    2, 3
  ]
}

Cash-out

When a user makes a cash-out, then the REST API (PUT /bets/advisory/{bet_id}) MUST be called with the bet update document that contains cash-out order info provided in the foreign_cash_out_orders field.

Please, take a look at the amount and the refund_amount fields.

  • Amount means the part (expressed in money) of the stake a player cashed out. This is not the amount he gets. The cumulative value of all amount values of the cash-out orders can’t be greater than the bet stake.
  • Refund amount - is how much the player will receive on his balance. The cumulative value of all refund_amount values can be more than the bet stake in case the selection value was higher at the cash-out moment than the selection value in the bet.
Cash-outs statuses

pending Intermediate status, when there is a cash-out request but it has not yet been validated.
accepted The cash-out is successful
declined The cash-out is rejected

Please, take into account

a cash-out status field that can have one of three values: pending, accepted, or declined. DATA.BET requires to send only accepted cash-out, so the bookmaker MAY skip sending updates of the cash-out if it was declined, but the bookmaker hasn't sent cash-out in the pending state. Sending pending state is optional, but if it was sent then the bookmaker MUST send accepted or declined state after that.

Please, take into account

the API expects that a full update document is always sent, no matter what field has changed.

Full cash-out

To notify about the full cash-out the bookmaker MUST send an order in the foreign_cash-out_orders list with the accepted status and amount that MUST be the same as the stake amount in the bet.

Partial cash-out

A player can make a partial cash-out, in that case, the bookmaker MUST send an order with the cached out part of the bet in the amount field and the amount given back to the player in the refund_amount field.

It is possible to send several partial cash-outs with one limitation: the total cash-out amount cannot be more than the bet stake.

Request 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
  "selections": [
    {
      "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
      "market_id": "20",
      "odd_id": "1",
      "status": 1,
      "status_reason": "string"
    }
  ],
  "foreign_selections": [
    {
      "id": "string",
      "value": "2.31",
      "sport_event_title": "string",
      "sport": "football",
      "market_name": "string",
      "odd_name": "string",
      "status": 1,
      "status_reason": "string"
    }
  ],
  "foreign_cash_out_orders": [
    {
      "id": "string",
      "amount": "string",
      "refund_amount": "string",
      "status": {
        "code": "accepted",
        "reason": ""
      },
      "created_at": "string"
    }
  ],
  "status": {
    "code": 1,
    "reason": ""
  }
}

Bet settlement

When a bet is settled the bookmaker MUST send the update with the new status, update request looks pretty much the same as for the cash-out update. Please refer to the swagger documentation that was sent to see possible statuses. - Schemas section: BetStatusCode. Here are the most important statuses:

3 - Settled. This means that a bet can be calculated to make a payout to the player or it was lost.
4 - Unsettled. This means that some of the bets’ selections were moved to the not resulted state and the current bet status is not finally defined.
5 - Refunded. This means that the bet was placed successfully, and accepted by the bookmaker but then money for that bet was returned to the player due to the selection cancellation. For example, a player placed a bet on a sports event that was canceled.
6 - Refunded manually. Quite similar to the refund, but the bet was canceled by the decision of the bookmaker. For example - the player asked to cancel his bet because it was mistaken or something like that. The selection the bet was placed on is still valid.