Multibet API

Introduction

This document describes technologies available for customers wishing to integrate with Multibet API directly. It explains the overall architecture, integration points and requirements.

Table of Contents

Conceptual Diagram

API Domain Names

Authentication

All calls to the API must be authenticated and provide an API key. Each request must include the following headers:

Getting an access token

To obtain an Access Token, you must make a client_credentials POST request to the Genius Sports Authentication server https://uat.auth.geniussports.com/oauth/token with the following request body:

{
  "grant_type" : "client_credentials",
  "audience": "https://api.geniussports.com",
  "client_id": <client-id>,
  "client_secret": <client_secret>
}

Your <client-id> and <client-secret> will be provided to you during the onboarding process.

Example token request:

curl --request POST \
--url https://uat.auth.geniussports.com/oauth/token \
--header 'content-type: application/json' \
--data '{"client_id":"<client-id>","client_secret":"<client-secret>","audience":"https://api.geniussports.com","grant_type":"client_credentials"}'

Example token response:

{
  "access_token": "<access-token>",
  "token_type": "Bearer"
}

Getting an API key

Your <api-key> will be provided to you during the onboarding process.

Calling the API

Once you have an <access-token> and your <api-key> you can pass these as headers to the API:

curl --request GET \
  --url https://multibet.api.geniussports.com/v2/sports/10/fixtures/1/results?legs=TotalGoals_Over_3.5 \
  --header 'authorization: Bearer <access-token> \'
  --header 'x-api-key: <api-key>'

Rate Limiting

All calls to the API are rate limited. A 429 Too Many Requests error will be returned from the API in cases where you are exceeding the rate limit. Rate limits are determined on an individual basis.

Resources

Genius Sports provides four pull API endpoints:

• Fixtures - Returns fixtures that are available to be used in Multibet

• Markets-types - Provides a list of markets and selections that are available to bet upon

• Prices - The price of a particular multibet

• Results - The result of a particular multibet

Fixtures

Returns list of fixtures that are available to be used in Multibet. FixtureId is required to call the remaining three endpoints: Markets-types, Prices, Results

API Domain Names

Authentication

You should go through all steps in “Getting an access token” section and authenticate using the Coverage API <api-key>

Getting an API key

Your <api-key> for using Coverage API will be provided to you during the onboarding process.

Calling the API

Once you have an <access-token> and your <api-key> you can pass these as headers to the API:

curl --request GET \
  --url https://coverage.api.geniussports.com/api/MultibetPreMatchCoverage/event/{fixtureId} \
  --header 'Authorization: Bearer <access-token> \'
  --header 'x-api-key: <api-key>'

Fixtures Resources

Multibet Pre-Match coverage by sport and date range

Returns data about a particular fixture that will show this fixture is available for use in Multibet Pre-Match.
Path

GET MultibetPreMatchCoverage/range/sport/{sportId}/from/{from}/to/{to}

{sportId} should be replaced by the relevant Genius Sports ids. Only fixtures starting after this date {from} and only fixtures starting before this {to} will be returned. Format: yyyy-MM-dd E.g. 2023-07-15

Example: https://coverage.api.geniussports.com/api/MultibetPreMatchCoverage/range/sport/10/from/2023-07-13/to/2023-07-15

Response Body

[
    {
        "betgeniusFixtureId": 123456,
        "sourceFixtureId": "123456",
        "source": "GeniusSportsMultibetPreMatch",
        "sportId": 10,
        "available": true,
        "coverageType": 4
    },
    {
        "betgeniusFixtureId": 1234567,
        "sourceFixtureId": "1234567",
        "source": "GeniusSportsMultibetPreMatch",
        "sportId": 10,
        "available": false,
        "coverageType": 4
    },
    {
        "betgeniusFixtureId": 12345678,
        "sourceFixtureId": "12345678",
        "source": "GeniusSportsMultibetPreMatch",
        "sportId": 10,
        "available": true,
        "coverageType": 4
    }
]

Multibet Pre-Match coverage by fixture

Returns data about a particular fixture that will show this fixture is available for use in Multibet Pre-Match.
Path

GET MultibetPreMatchCoverage/event/{fixtureId}

{fixtureId} should be replaced by the relevant Genius Sports ids.

Example: https://coverage.api.geniussports.com/api/MultibetPreMatchCoverage/event/123456

Response Body

[
    {
        "betgeniusFixtureId": 123456,
        "sourceFixtureId": "123456",
        "source": "GeniusSportsMultibetPreMatch",
        "sportId": 10,
        "available": true,
        "coverageType": 4
    }
]

Multibet In-Play coverage by sport and date range

Returns data about a particular fixture that will show this fixture is available for use in Multibet In-Play.
Path

GET MultibetInPlayCoverage/range/sport/{sportId}/from/{from}/to/{to}

{sportId} should be replaced by the relevant Genius Sports ids. Only fixtures starting after this date {from} and only fixtures starting before this {to} will be returned. Format: yyyy-MM-dd E.g. 2023-07-15

Example: https://coverage.api.geniussports.com/api/MultibetInPlayCoverage/range/sport/10/from/2023-07-13/to/2023-07-15

Response Body

[
    {
        "betgeniusFixtureId": 123456,
        "sourceFixtureId": "123456",
        "source": "GeniusSportsMultibetInPlay",
        "sportId": 10,
        "available": true,
        "coverageType": 4
    },
    {
        "betgeniusFixtureId": 1234567,
        "sourceFixtureId": "1234567",
        "source": "GeniusSportsMultibetInPlay",
        "sportId": 10,
        "available": false,
        "coverageType": 4
    },
    {
        "betgeniusFixtureId": 12345678,
        "sourceFixtureId": "12345678",
        "source": "GeniusSportsMultibetInPlay",
        "sportId": 10,
        "available": true,
        "coverageType": 4
    }
]

Multibet In-Play coverage by fixture

Returns data about a particular fixture that will show this fixture is available for use in Multibet In-Play.
Path

GET MultibetInPlayCoverage/event/{fixtureId}

{fixtureId} should be replaced by the relevant Genius Sports ids.

Example: https://coverage.api.geniussports.com/api/MultibetInPlayCoverage/event/123456

Response Body

[
    {
        "betgeniusFixtureId": 123456,
        "sourceFixtureId": "123456",
        "source": "GeniusSportsMultibetInPlay",
        "sportId": 10,
        "available": true,
        "coverageType": 3
    }
]

Market-types

Returns a list of available markets to bet upon for a particular fixture. The available markets is sport specific and will also be affected by the current state of the fixture and what bets are already included in the multibet. For instance it wouldn’t be possible to bet upon a first quarter market during the second quarter of a fixture.

Path

GET sports/{sportId}/fixtures/{fixtureId}/market-types?legs={legs}

{sportId} and {fixtureId} should be replaced by the relevant Genius Sports ids.

Example: https://multibet.api.geniussports.com/v2/sports/10/fixtures/123456/market-types?legs=WinMatchRegularTime_Home,HalfTimeTotalGoals_Over_2.5

Request URL Parameters

Response Body

{
    "markets": [
        {
            "marketType": "Win Match Regular Time",
            "selections": [
                {
                    "id": "WinMatchRegularTime_Home",
                    "name": "Home"
                },
                {
                    "id": "WinMatchRegularTime_Draw",
                    "name": "Draw"
                },
                {
                    "id": "WinMatchRegularTime_Away",
                    "name": "Away"
                }
            ]
        },
        {
            "marketType": "Half Time Total Goals",
            "handicap": {
                "minimum": 1,
                "maximum": 20,
                "step": 1,
                "default": 1
            },
            "selections": [
                {
                    "id": "HalfTimeTotalGoals_Over_{HANDICAP}",
                    "name": "Over"
                },
                {
                    "id": "HalfTimeTotalGoals_Under_{HANDICAP}",
                    "name": "Under"
                }
            ]
        }
    ]
}

Prices

Returns the price of the selected multibet.

Path

GET sports/{sportId}/fixtures/{fixtureId}/prices

Example: https://multibet.api.geniussports.com/v2/sports/10/fixtures/123456/prices?legs=WinMatchRegularTime_Home,HalfTimeTotalGoals_Over_2.5

{sportId} and {fixtureId} should be replaced by the relevant Genius Sports ids.

Request URL Parameters

Response Body

{
    "decimalPrice": 1.66,
    "probability": 0.5656463943226999,
    "suspended": false
}

Results

Path

GET sports/{sportId}/fixtures/{fixtureId}/results

{sportId} and {fixtureId} should be replaced by the relevant Genius Sports ids.

Example: https://multibet.api.geniussports.com/v2/sports/10/fixtures/123456/results?legs=WinMatchRegularTime_Home,HalfTimeTotalGoals_Over_2.5

Request URL Parameters

Response Body

{
    "result": "lose",
    "legResults": [
        {
            "leg": "MatchResult_Home",
            "legResult": "win"
        },
        {
            "leg": "TotalGoals_Over_20.5",
            "legResult": "lose"
        }
    ]
}

Type Definitions

Market

A market contains selections that can be bet upon that will correspond to legs within a multibet.

Handicap

Used for Handicap and Over/Under markets to specify the available lines that can be bet upon. Handicaps are taken from the perspective of the Home team.

Index

Index markets relate to betting on a particular instance of an event that can happen multiple times during a fixture, e.g. betting on which team will score the Next Goalscorer. In this example at the start of the match the Primary field of the index would start at 1 (for the First Goalscorer) and then increment to 2 for the Second Goalscorer etc.

Selection

Leg Id

For simplicity and compactness we encode the id of legs as a string.

Rules

• Characters are restricted to those that do not require URL encoding

• No white space allowed

• Pascal case notation is used for marketType and selection

• Underscore “_” is used as a separator between the different fields within a leg and is guaranteed not to be used within fields

• Hyphen is used for dividing range values

• Comma “,” is used as a separator between leg ids in the URL and is guaranteed not to be used within fields

Examples

Whenever an API method requires legs to be passed in by the caller the Leg Id should be used.

Result

Results are passed as extensible enums (x-extensible-enum) which are encoded as strings within the JSON.

LegResult

A leg result encapsulates the result for a single leg within a multibet.

HTTP Status Codes and Error Handing

Appendix A - End to End Example

This example demonstrates the flow of the Multibet API calls for an Football fixture 123456. For simplicity the amount of available markets is limited to two (Match Result and Half-time Total Goals).

1️⃣ User opens the widget. Initial call is made to get the list of the available markets.

GET sports/10/fixtures/123456/market-types

{
    "markets": [
        {
            "marketType": "Win Match Regular Time",
            "selections": [
                {
                    "id": "WinMatchRegularTime_Home",
                    "name": "Home"
                },
                {
                    "id": "WinMatchRegularTime_Draw",
                    "name": "Draw"
                },
                {
                    "id": "WinMatchRegularTime_Away",
                    "name": "Away"
                }
            ]
        },
        {
            "marketType": "Half Time Total Goals",
            "handicap": {
                "minimum": 1,
                "maximum": 20,
                "step": 1,
                "default": 1
            },
            "selections": [
                {
                    "id": "HalfTimeTotalGoals_Over_{HANDICAP}",
                    "name": "Over"
                },
                {
                    "id": "HalfTimeTotalGoals_Under_{HANDICAP}",
                    "name": "Under"
                }
            ]
        }
    ]
}

2️⃣ User adds a leg (Match Result - Home) to the bet. Call is made to get a price for the current bet.

GET sports/10/fixtures/123456/prices?legs=WinMatchRegularTime_Home

{
    "decimalPrice": 1.66,
    "probability": 0.5656463943226999,
    "suspended": false
}

3️⃣ User wants to add another leg. Call is made to get the list of the available markets. Match Result market will not be included in the response because it is already used in one of the legs.

GET sports/10/fixtures/123456/market-types?legs=WinMatchRegularTime_Home

{
    "markets": [
        {
            "marketType": "Half Time Total Goals",
            "handicap": {
                "minimum": 1,
                "maximum": 20,
                "step": 1,
                "default": 1
            },
            "selections": [
                {
                    "id": "HalfTimeTotalGoals_Over_{HANDICAP}",
                    "name": "Over"
                },
                {
                    "id": "HalfTimeTotalGoals_Under_{HANDICAP}",
                    "name": "Under"
                }
            ]
        }
    ]
}

4️⃣ User adds a second leg (Half-time Total Goals - Over 2.5) to the bet. Call is made to get a price for the current bet.

GET sports/10/fixtures/123456/prices?legs=WinMatchRegularTime_Home,HalfTimeTotalGoals_Over_2.5

{
    "decimalPrice": 1.77,
    "probability": 0.4656463943226999,
    "suspended": false
}

5️⃣ Result is requested for the bet.

GET sports/10/fixtures/123456/results?legs=WinMatchRegularTime_Home,HalfTimeTotalGoals_Over_2.5

{
    "result": "lose",
    "legResults": [
        {
            "leg": "MatchResult_Home",
            "legResult": "win"
        },
        {
            "leg": "HalfTimeTotalGoals_Over_2.5",
            "legResult": "lose"
        }
    ]
}