Databird API

Program endpoints, webhooks, and account management

Databird API

Databird (Account Management) serves as the central gateway for the frontend. It receives webhooks from Feedbird, aggregates program data, and serves it to the frontend via GET endpoints. It also handles all account management operations and proxies bet placement requests to Betbird.

Base URL

All endpoints are relative to the base URL:

{your-base-url}/v1/{endpoint}

Overview

Databird provides:

Program endpoints (GET): Serves aggregated program data to the frontend
Webhook endpoints (POST): Receives program data updates from Feedbird
Account management: Handles authentication, deposits, withdrawals, and transactions
Request proxying: Proxies bet placement requests to Betbird after validation

Note: Account management endpoints (authentication, deposits, withdrawals) are handled by Databird but are outside the scope of this API documentation.

Program APIs

These program endpoints are provided by Databird and serve program/feed data to the frontend. Databird receives this data from Feedbird via webhooks and aggregates it before serving to clients. The frontend polls these endpoints from Databird (not directly from Feedbird).

Get Live Events

Retrieve currently live sporting events with available markets and competitions.

Endpoint: GET /v1/program/events/live

Query Parameters

Parameter	Type	Required	Description
widget	boolean	No	Widget mode flag
limitPerSport	number	No	Maximum number of events per sport (default: 10)
oneSectionResult	boolean	No	Return single section result
isLoggedIn	number	No	User login status (0 or 1)
licenseRegion	string	No	License region code (e.g., "DE")
language	string	No	Language code (e.g., "de")
maxMarkets	number	No	Maximum number of markets per event (default: 5)

Response Schema

The response contains a LIVE_WIDGET object with:

availableMarkets (object): Map of sport IDs to available market types
sportCompetitionMap (object): Map of sport IDs to competition arrays
events (object): Map of event IDs to event details

Each event object contains:

Event metadata (name, start time, teams, etc.)
Market information
Odds and betting options
Live status indicators

Example Request

{
    "url": "{your-base-url}/v1/program/events/live",
    "method": "GET",
    "queryString": "widget=true&limitPerSport=10&oneSectionResult=true&isLoggedIn=0&licenseRegion=DE&language=de&maxMarkets=5"
}

Example Response

The response is a large JSON object. Here's a sample structure:

{
    "LIVE_WIDGET": {
        "availableMarkets": {
            "soccer": [
                "standard",
                "standard-rest",
                "points-more-less-rest",
                "next-point",
                "handicap",
                "score-both",
                "section-points-more-less",
                "double-chance",
                "head-to-head"
            ],
            "basketball": [
                "standard",
                "points-more-less-than",
                "handicap",
                "handicap-halftime",
                "points-more-less-halftime",
                "halftime-win"
            ],
            "volleyball": [
                "standard",
                "section-win",
                "points-more-less-than",
                "handicap"
            ]
        },
        "sportCompetitionMap": {
            "soccer": [
                {
                    "groupId": 3973301,
                    "groupIdString": "3973301",
                    "name": "Premier League ",
                    "icon": "soccer",
                    "sort": 1,
                    "parentName": "Hong Kong",
                    "regionIcon": "hk-flag",
                    "groupInfo": "Hong Kong / Premier League ",
                    "hasSeasonEvents": false,
                    "sportRadarGroupId": 3973
                }
            ]
        }
    }
}

Get Hour Events

Retrieve events scheduled for a specific hour window.

Endpoint: GET /v1/program/events/hourEvents/{hour}

Path Parameters

Parameter	Type	Required	Description
hour	number	Yes	Hour offset (e.g., 2 for events in 2 hours)

Query Parameters

Parameter	Type	Required	Description
oneSectionResult	boolean	No	Return single section result
language	string	No	Language code (e.g., "de")
isLoggedIn	number	No	User login status (0 or 1)
licenseRegion	string	No	License region code (e.g., "DE")
maxMarkets	number	No	Maximum number of markets per event (default: 5)
cacheKey	string	No	Cache key for response caching

Response Schema

Similar to Get Live Events, but returns an UPCOMING object instead of LIVE_WIDGET.

Example Request

{
    "url": "{your-base-url}/v1/program/events/hourEvents/2",
    "method": "GET",
    "queryString": "oneSectionResult=true&language=de&isLoggedIn=0&licenseRegion=DE&maxMarkets=5&cacheKey=_XBacrtVjQwdrffZbCuJuU6XOBl0xiTm4UP6yi2wwKI%3D"
}

Example Response

The response structure is similar to live events but with UPCOMING as the root key:

{
    "UPCOMING": {
        "availableMarkets": {
            "soccer": [
                "standard",
                "points-more-less-than",
                "handicap",
                "score-both",
                "section-points-more-less",
                "double-chance",
                "head-to-head",
                "first-scorer",
                "section-win",
                "score-both-halftime"
            ]
        },
        "sportCompetitionMap": {
            "soccer": [
                {
                    "groupId": 144301,
                    "groupIdString": "144301",
                    "name": "A-League",
                    "icon": "soccer",
                    "sort": 1,
                    "parentName": "Australien",
                    "regionIcon": "as-flag",
                    "groupInfo": "Australien / A-League",
                    "hasSeasonEvents": false,
                    "sportRadarGroupId": 144
                }
            ]
        }
    }
}

Get Recommended Events

Retrieve recommended sporting events based on popularity and relevance.

Endpoint: GET /v1/program/recommendedEvents

Query Parameters

Parameter	Type	Required	Description
limitPerSport	number	No	Maximum number of events per sport (default: 15)
language	string	No	Language code (e.g., "de")
oneSectionResult	boolean	No	Return single section result
maxMarkets	number	No	Maximum number of markets per event (default: 5)

Response Schema

Returns a RECOMMENDED object with similar structure to live events, containing:

availableMarkets (object): Available market types per sport
sportCompetitionMap (object): Map of competitions per sport
competitionEventMap (object): Map of event IDs per competition
events (object): Detailed event information

Example Request

{
    "url": "{your-base-url}/v1/program/recommendedEvents",
    "method": "GET",
    "queryString": "limitPerSport=15&language=de&oneSectionResult=true&maxMarkets=5"
}

Example Response

{
    "RECOMMENDED": {
        "availableMarkets": {
            "soccer": [
                "standard",
                "points-more-less-than",
                "handicap",
                "score-both",
                "section-points-more-less",
                "double-chance",
                "head-to-head",
                "first-scorer",
                "section-win",
                "score-both-halftime"
            ]
        },
        "sportCompetitionMap": {
            "soccer": [
                {
                    "groupId": 42301,
                    "groupIdString": "42301",
                    "name": "Bundesliga",
                    "icon": "bundesliga",
                    "sort": 1,
                    "parentName": "Deutschland",
                    "regionIcon": "gm-flag",
                    "groupInfo": "Deutschland / Bundesliga",
                    "hasSeasonEvents": false,
                    "sportRadarGroupId": 42
                }
            ]
        },
        "competitionEventMap": {
            "33301": ["682870610"],
            "42301": ["682869710", "682869810", "682869610"]
        }
    }
}

Retrieve the complete navigation tree structure for sports, regions, and competitions.

Endpoint: GET /v1/program/navigationTree/all

Query Parameters

This endpoint does not require any query parameters.

Response Schema

Returns a hierarchical tree structure with:

Root node with metadata (counts, meta information)
children (array): Array of child nodes
Each node contains:
- groupId (string|null): Group identifier
- icon (string|null): Icon identifier
- title (string|null): Display title
- titleKey (string|null): Localization key
- sportId (string): Sport identifier (for sport nodes)
- meta (object): Metadata including event counts, live counts, etc. Contains:
  - outrights (number): Number of outright bets available
  - events (number): Number of events
  - live (number): Number of live events
  - today (number): Number of events today
  - 3hrs (number): Number of events in next 3 hours
  - 48hrs (number): Number of events in next 48 hours
- count (number): Total count of items
- children (array): Nested children nodes

The tree structure typically follows: Root → Sports → Regions → Competitions → Events

Example Request

{
    "url": "{your-base-url}/v1/program/navigationTree/all"
}

Example Response

{
    "groupId": null,
    "icon": null,
    "title": null,
    "titleKey": null,
    "childIndex": 0,
    "meta": {
        "outrights": 127,
        "events": 1448,
        "live": 17,
        "today": 807,
        "3hrs": 46,
        "48hrs": 1208
    },
    "count": 1575,
    "children": [
        {
            "groupId": "1101",
            "icon": "soccer",
            "title": "Fußball",
            "titleKey": null,
            "sportId": "soccer",
            "childIndex": 0,
            "meta": {
                "outrights": 49,
                "events": 953,
                "live": 5,
                "today": 476,
                "3hrs": 35,
                "48hrs": 746
            },
            "count": 1002,
            "children": [
                {
                    "groupId": "32201",
                    "icon": "sp-flag",
                    "title": "Spanien",
                    "titleKey": null,
                    "childIndex": 0,
                    "meta": {
                        "outrights": 3,
                        "events": 56,
                        "live": 0,
                        "today": 21,
                        "3hrs": 0,
                        "48hrs": 42
                    },
                    "count": 59,
                    "children": []
                }
            ]
        }
    ]
}

Get Top Competitions

Retrieve the most popular competitions across different sports.

Endpoint: GET /v1/program/top-competitions

Query Parameters

This endpoint does not require any query parameters.

Response Schema

Returns an array of competition objects, each containing:

groupId (string): Competition group identifier
groupName (string): Competition name
parentGroupName (string): Parent region/group name
icon (string): Icon identifier
eventCount (number): Number of events in this competition
regionGroupId (string): Region group identifier
sportGroupId (string): Sport group identifier

Example Request

{
    "url": "{your-base-url}/v1/program/top-competitions"
}

Example Response

[
    {
        "groupId": "virtual_footballBundesliga",
        "groupName": "Bundesliga",
        "parentGroupName": "Deutschland",
        "icon": "bundesliga",
        "eventCount": 19,
        "regionGroupId": "30201",
        "sportGroupId": "1101"
    },
    {
        "groupId": "virtual_footballLaLiga",
        "groupName": "La Liga",
        "parentGroupName": "Spanien",
        "icon": "soccer",
        "eventCount": 23,
        "regionGroupId": "32201",
        "sportGroupId": "1101"
    },
    {
        "groupId": "virtual_footballPremierLeague",
        "groupName": "Premier League",
        "parentGroupName": "England",
        "icon": "soccer",
        "eventCount": 22,
        "regionGroupId": "1201",
        "sportGroupId": "1101"
    },
    {
        "groupId": "virtual_footballBundesliga2",
        "groupName": "2. Bundesliga",
        "parentGroupName": "Deutschland",
        "icon": "bundesliga-2",
        "eventCount": 17,
        "regionGroupId": "30201",
        "sportGroupId": "1101"
    },
    {
        "groupId": "virtual_footballSerieA",
        "groupName": "Serie A",
        "parentGroupName": "Italien",
        "icon": "soccer",
        "eventCount": 22,
        "regionGroupId": "31201",
        "sportGroupId": "1101"
    }
]

Get Top Combos

Retrieve the most popular betting combinations across different sports.

Endpoint: GET /v1/program/top-combos

Query Parameters

This endpoint does not require any query parameters.

Response Schema

Returns an object containing:

availableSports (array[string]): List of sports available for combinations
combis (object): Map of combination IDs to combination details
- Each combination contains:
  - combiId (string): Unique combination identifier
  - weight (number): Popularity weight
  - betsPlaced (number): Number of bets placed
  - maxOdds (number): Maximum odds for the combination
combiMarketsMap (object): Map of combination IDs to market identifiers
markets (object): Map of market identifiers to market details
sportCombisMap (object): Map of sport IDs to combination ID arrays
sports (array[string]): List of sports

Example Request

{
    "url": "{your-base-url}/v1/program/top-combos"
}

Example Response

{
    "availableSports": [
        "soccer"
    ],
    "combis": {
        "99129d92-31e1-3b61-8f99-97a70ee4a5ba": {
            "combiId": "99129d92-31e1-3b61-8f99-97a70ee4a5ba",
            "weight": 1050,
            "betsPlaced": 850,
            "maxOdds": 2.97
        },
        "6f5d22cd-42bb-3571-8ac4-261730a3e214": {
            "combiId": "6f5d22cd-42bb-3571-8ac4-261730a3e214",
            "weight": 1004,
            "betsPlaced": 751,
            "maxOdds": 16.18
        }
    },
    "combiMarketsMap": {
        "99129d92-31e1-3b61-8f99-97a70ee4a5ba": [
            "72414005710_195848823010",
            "72414046710_195848957910",
            "72414145110_195849283710"
        ]
    },
    "markets": {
        "72389530710_195779504510": {
            "name": "Fortuna Düsseldorf - 1. FC Magdeburg",
            "market": "Tipp: ",
            "resultNamePostfix": "Fortuna Düsseldorf",
            "odd": 2.2,
            "resultId": 195779504510,
            "eventId": 682821310,
            "eventStartTime": "heute, 13:00",
            "sportId": "soccer",
            "sportRadarMatchId": 61514868,
            "type": "standard",
            "team1Id": 2588,
            "team2Id": 2591,
            "resultTeamId": 2588,
            "resultTypeId": "standard"
        }
    },
    "sportCombisMap": {
        "soccer": [
            "99129d92-31e1-3b61-8f99-97a70ee4a5ba",
            "6f5d22cd-42bb-3571-8ac4-261730a3e214"
        ]
    },
    "sports": [
        "soccer"
    ]
}

Get Single Event

Retrieve detailed information for a specific event including all available markets and odds.

Endpoint: GET /v1/program/events/{eventId}

Path Parameters

Parameter	Type	Required	Description
eventId	number	Yes	The event identifier

Query Parameters

Parameter	Type	Required	Description
language	string	No	Language code (e.g., "de")
maxMarkets	number	No	Maximum number of markets per event (default: all)
isLoggedIn	number	No	User login status (0 or 1)
licenseRegion	string	No	License region code (e.g., "DE")

Response Schema

Returns a detailed event object containing:

eventId (number): Event identifier
name (string): Event name (e.g., "Team A vs Team B")
startTime (string): Event start time/date
sportId (string): Sport identifier
competitionId (string): Competition/group identifier
status (string): Event status (upcoming, live, finished, cancelled)
markets (object): Map of market IDs to market details
teams (array): Array of team/participant information
live (boolean): Whether the event is currently live
score (object|null): Current score (if live). When present, contains:
- home (number): Home team score
- away (number): Away team score
- period (string|null): Current period/half (e.g., "1st Half", "2nd Half", "Full Time")
- status (string): Score status (e.g., "live", "halftime", "finished")
metadata (object): Additional event metadata containing:
- venue (string|null): Venue name
- round (string|null): Round/matchday information
- referee (string|null): Referee name
- attendance (number|null): Attendance number

Example Request

{
    "url": "{your-base-url}/v1/program/events/682869710",
    "method": "GET",
    "queryString": "language=de&maxMarkets=20&isLoggedIn=0&licenseRegion=DE"
}

Example Response

{
    "eventId": 682869710,
    "name": "Borussia Dortmund - VfB Stuttgart",
    "startTime": "2024-01-15T15:30:00Z",
    "sportId": "soccer",
    "competitionId": "42301",
    "status": "upcoming",
    "live": false,
    "score": null,
    "teams": [
        {
            "teamId": 2588,
            "name": "Borussia Dortmund",
            "shortName": "BVB"
        },
        {
            "teamId": 2591,
            "name": "VfB Stuttgart",
            "shortName": "VfB"
        }
    ],
    "metadata": {
        "venue": "Signal Iduna Park",
        "round": "Matchday 18",
        "referee": "M. Schmidt",
        "attendance": null
    },
    "markets": {
        "195848960510": {
            "marketId": "195848960510",
            "name": "Über/Unter (3,5): Über 3,5",
            "type": "points-more-less-than",
            "odd": 2.25,
            "status": "active"
        }
    }
}

Example Response (Live Event with Score):

{
    "eventId": 682869710,
    "name": "Borussia Dortmund - VfB Stuttgart",
    "startTime": "2024-01-15T15:30:00Z",
    "sportId": "soccer",
    "competitionId": "42301",
    "status": "live",
    "live": true,
    "score": {
        "home": 2,
        "away": 1,
        "period": "2nd Half",
        "status": "live"
    },
    "teams": [
        {
            "teamId": 2588,
            "name": "Borussia Dortmund",
            "shortName": "BVB"
        },
        {
            "teamId": 2591,
            "name": "VfB Stuttgart",
            "shortName": "VfB"
        }
    ],
    "metadata": {
        "venue": "Signal Iduna Park",
        "round": "Matchday 18",
        "referee": "M. Schmidt",
        "attendance": 81365
    },
    "markets": {
        "195848960510": {
            "marketId": "195848960510",
            "name": "Über/Unter (3,5): Über 3,5",
            "type": "points-more-less-than",
            "odd": 2.25,
            "status": "active"
        }
    }
}

Get Events by Competition

Retrieve all events for a specific competition/group.

Endpoint: GET /v1/program/competitions/{groupId}/events

Path Parameters

Parameter	Type	Required	Description
groupId	string	Yes	The competition/group identifier

Query Parameters

Parameter	Type	Required	Description
language	string	No	Language code (e.g., "de")
maxMarkets	number	No	Maximum number of markets per event (default: 5)
isLoggedIn	number	No	User login status (0 or 1)
licenseRegion	string	No	License region code (e.g., "DE")
liveOnly	boolean	No	Return only live events (default: false)
upcomingOnly	boolean	No	Return only upcoming events (default: false)

Response Schema

Returns an object containing:

competition (object): Competition details. Contains:
- groupId (string): Competition group identifier
- name (string): Competition name
- sportId (string): Sport identifier
- regionId (string|null): Region identifier
- icon (string|null): Icon identifier
- parentName (string|null): Parent region/group name
events (object): Map of event IDs to event details
eventIds (array): Array of event IDs in this competition

Example Request

{
    "url": "{your-base-url}/v1/program/competitions/42301/events",
    "method": "GET",
    "queryString": "language=de&maxMarkets=5&isLoggedIn=0&licenseRegion=DE&upcomingOnly=true"
}

Example Response

{
    "competition": {
        "groupId": "42301",
        "name": "Bundesliga",
        "sportId": "soccer",
        "regionId": "30201",
        "icon": "bundesliga",
        "parentName": "Deutschland"
    },
    "events": {
        "682869710": {
            "eventId": 682869710,
            "name": "Borussia Dortmund - VfB Stuttgart",
            "startTime": "2024-01-15T15:30:00Z",
            "status": "upcoming"
        }
    },
    "eventIds": ["682869710", "682869810", "682869610"]
}

Get Events by Sport

Retrieve all events for a specific sport.

Endpoint: GET /v1/program/sports/{sportId}/events

Path Parameters

Parameter	Type	Required	Description
sportId	string	Yes	The sport identifier (e.g., "soccer", "basketball")

Query Parameters

Parameter	Type	Required	Description
language	string	No	Language code (e.g., "de")
maxMarkets	number	No	Maximum number of markets per event (default: 5)
isLoggedIn	number	No	User login status (0 or 1)
licenseRegion	string	No	License region code (e.g., "DE")
liveOnly	boolean	No	Return only live events (default: false)
limit	number	No	Maximum number of events to return

Response Schema

Returns an object containing:

sport (object): Sport details. Contains:
- sportId (string): Sport identifier (e.g., "soccer", "basketball")
- name (string): Sport name
- icon (string|null): Icon identifier
events (object): Map of event IDs to event details
eventIds (array): Array of event IDs

Example Request

{
    "url": "{your-base-url}/v1/program/sports/soccer/events",
    "method": "GET",
    "queryString": "language=de&maxMarkets=5&isLoggedIn=0&licenseRegion=DE&liveOnly=false&limit=50"
}

Example Response

{
    "sport": {
        "sportId": "soccer",
        "name": "Fußball",
        "icon": "soccer"
    },
    "events": {
        "682869710": {
            "eventId": 682869710,
            "name": "Borussia Dortmund - VfB Stuttgart",
            "startTime": "2024-01-15T15:30:00Z",
            "status": "upcoming"
        }
    },
    "eventIds": ["682869710", "682869810", "682869610"]
}

Get Events by Date

Retrieve events scheduled for a specific date or date range.

Endpoint: GET /v1/program/events/byDate

Query Parameters

Parameter	Type	Required	Description
date	string	Yes	Date in YYYY-MM-DD format
endDate	string	No	End date for date range (YYYY-MM-DD format)
language	string	No	Language code (e.g., "de")
maxMarkets	number	No	Maximum number of markets per event (default: 5)
sportId	string	No	Filter by sport ID
competitionId	string	No	Filter by competition ID

Response Schema

Returns an object containing:

date (string): The requested date
events (object): Map of event IDs to event details
eventIds (array): Array of event IDs for the date(s)

Example Request

{
    "url": "{your-base-url}/v1/program/events/byDate",
    "method": "GET",
    "queryString": "date=2024-01-15&language=de&maxMarkets=5&sportId=soccer"
}

Search Events

Search for events by name, team, or other criteria.

Endpoint: GET /v1/program/events/search

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	Search query
sportId	string	No	Filter by sport ID
competitionId	string	No	Filter by competition ID
language	string	No	Language code (e.g., "de")
limit	number	No	Maximum number of results (default: 20)

Response Schema

Returns an object containing:

query (string): The search query
results (array): Array of matching event objects
total (number): Total number of matching events

Example Request

{
    "url": "{your-base-url}/v1/program/events/search",
    "method": "GET",
    "queryString": "q=Dortmund&sportId=soccer&language=de&limit=10"
}

Get All Markets for Event

Retrieve all available markets for a specific event.

Endpoint: GET /v1/program/events/{eventId}/markets

Path Parameters

Parameter	Type	Required	Description
eventId	number	Yes	The event identifier

Query Parameters

Parameter	Type	Required	Description
language	string	No	Language code (e.g., "de")
marketType	string	No	Filter by market type
isLoggedIn	number	No	User login status (0 or 1)

Response Schema

Returns an object containing:

eventId (number): Event identifier
markets (object): Map of market IDs to market details
marketTypes (array): Array of available market types for this event

Example Request

{
    "url": "{your-base-url}/v1/program/events/682869710/markets",
    "method": "GET",
    "queryString": "language=de&marketType=standard&isLoggedIn=0"
}

Get Event Statistics

Retrieve statistics and additional information for a specific event.

Endpoint: GET /v1/program/events/{eventId}/statistics

Path Parameters

Parameter	Type	Required	Description
eventId	number	Yes	The event identifier

Query Parameters

Parameter	Type	Required	Description
language	string	No	Language code (e.g., "de")

Response Schema

Returns an object containing:

eventId (number): Event identifier
statistics (object): Event statistics (if available). Contains:
- home (object): Home team statistics with fields like possession, shots, shotsOnTarget, corners, fouls, etc.
- away (object): Away team statistics with same structure as home
- match (object|null): Match-level statistics (e.g., totalGoals, totalCards)
lineups (object|null): Team lineups (if available). When present, contains:
- home (object): Home team lineup with formation (string), players (array of player objects)
- away (object): Away team lineup with same structure as home
- formation (object|null): Formation information with home and away formation strings
venue (object|null): Venue information. When present, contains:
- name (string): Venue name
- city (string|null): City name
- capacity (number|null): Venue capacity
- country (string|null): Country name
referee (string|null): Referee information
weather (object|null): Weather conditions (if available). When present, contains:
- temperature (number|null): Temperature in Celsius
- condition (string|null): Weather condition (e.g., "Clear", "Rainy", "Cloudy")
- windSpeed (number|null): Wind speed in km/h
- humidity (number|null): Humidity percentage

Example Request

{
    "url": "{your-base-url}/v1/program/events/682869710/statistics",
    "method": "GET",
    "queryString": "language=de"
}

Example Response

{
    "eventId": 682869710,
    "statistics": {
        "home": {
            "possession": 58,
            "shots": 12,
            "shotsOnTarget": 5,
            "corners": 7,
            "fouls": 8,
            "yellowCards": 2,
            "redCards": 0
        },
        "away": {
            "possession": 42,
            "shots": 8,
            "shotsOnTarget": 3,
            "corners": 4,
            "fouls": 11,
            "yellowCards": 3,
            "redCards": 0
        },
        "match": {
            "totalGoals": 3,
            "totalCards": 5
        }
    },
    "lineups": {
        "home": {
            "formation": "4-3-3",
            "players": [
                {
                    "playerId": 12345,
                    "name": "Player Name",
                    "position": "GK",
                    "number": 1
                }
            ]
        },
        "away": {
            "formation": "4-2-3-1",
            "players": [
                {
                    "playerId": 67890,
                    "name": "Player Name",
                    "position": "GK",
                    "number": 1
                }
            ]
        },
        "formation": {
            "home": "4-3-3",
            "away": "4-2-3-1"
        }
    },
    "venue": {
        "name": "Signal Iduna Park",
        "city": "Dortmund",
        "capacity": 81365,
        "country": "Germany"
    },
    "referee": "M. Schmidt",
    "weather": {
        "temperature": 12,
        "condition": "Clear",
        "windSpeed": 8,
        "humidity": 65
    }
}

Example Response (Minimal Data):

{
    "eventId": 682869710,
    "statistics": {
        "home": {
            "possession": 58,
            "shots": 12,
            "shotsOnTarget": 5
        },
        "away": {
            "possession": 42,
            "shots": 8,
            "shotsOnTarget": 3
        },
        "match": null
    },
    "lineups": null,
    "venue": {
        "name": "Signal Iduna Park",
        "city": "Dortmund",
        "capacity": null,
        "country": null
    },
    "referee": null,
    "weather": null
}

Get Market Types for Sport

Retrieve all available market types for a specific sport.

Endpoint: GET /v1/program/sports/{sportId}/marketTypes

Path Parameters

Parameter	Type	Required	Description
sportId	string	Yes	The sport identifier (e.g., "soccer", "basketball")

Query Parameters

Parameter	Type	Required	Description
language	string	No	Language code (e.g., "de")

Response Schema

Returns an object containing:

sportId (string): Sport identifier
marketTypes (array): Array of market type objects, each containing:
- type (string): Market type identifier
- name (string): Display name
- description (string): Description of the market type
- available (boolean): Whether this market type is currently available

Example Request

{
    "url": "{your-base-url}/v1/program/sports/soccer/marketTypes",
    "method": "GET",
    "queryString": "language=de"
}

Example Response

{
    "sportId": "soccer",
    "marketTypes": [
        {
            "type": "standard",
            "name": "Match Winner",
            "description": "Bet on the match outcome",
            "available": true
        },
        {
            "type": "points-more-less-than",
            "name": "Over/Under",
            "description": "Bet on total goals scored",
            "available": true
        },
        {
            "type": "handicap",
            "name": "Handicap",
            "description": "Bet with handicap applied",
            "available": true
        }
    ]
}

Webhook Endpoints

Feedbird pushes program data updates to Databird via webhook endpoints. These endpoints require HMAC signature authentication and support idempotency to ensure reliable data delivery.

Webhook Security

HMAC Signature Authentication

All webhook requests must include an HMAC-SHA256 signature in the X-Webhook-Signature header.

Header Format:

X-Webhook-Signature: sha256=<hex-encoded-hmac>

Signature Generation:

Create a string by concatenating the request body (raw JSON string)
Compute HMAC-SHA256 using the shared secret key
Hex-encode the result
Format as sha256=<hex-encoded-hmac>

Example (Node.js):

const crypto = require('crypto');
const secret = 'your-shared-secret-key';
const body = JSON.stringify(payload);
const signature = crypto
  .createHmac('sha256', secret)
  .update(body)
  .digest('hex');
const header = `sha256=${signature}`;

Verification: Databird verifies the signature by:

Extracting the signature from X-Webhook-Signature header
Computing HMAC-SHA256 of the request body using the shared secret
Comparing the computed signature with the provided signature
Rejecting requests with invalid signatures (returns 401 Unauthorized)

Idempotency

All webhook requests must include an idempotency key to prevent duplicate processing.

Header:

Idempotency-Key: <uuid-v4>

Behavior:

Requests with the same Idempotency-Key return the same response
Idempotency keys expire after 24 hours
Duplicate requests within the expiration window return the cached response without reprocessing

Example:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Webhook Endpoints

Live Events Webhook

Receive updates for currently live sporting events.

Endpoint: POST /v1/webhooks/program/liveEvents

Headers

Header	Type	Required	Description
X-Webhook-Signature	string	Yes	HMAC-SHA256 signature (format: `sha256=<hex>`)
Idempotency-Key	string	Yes	UUID v4 for idempotency
Content-Type	string	Yes	Must be `application/json`

Request Body

The payload structure matches the response from GET /v1/program/events/live:

{
  "LIVE_WIDGET": {
    "availableMarkets": {
      "soccer": ["standard", "points-more-less-than", "handicap"]
    },
    "sportCompetitionMap": {
      "soccer": [
        {
          "groupId": 42301,
          "name": "Bundesliga",
          "icon": "bundesliga"
        }
      ]
    },
    "events": {
      "682869710": {
        "eventId": 682869710,
        "name": "Borussia Dortmund - VfB Stuttgart",
        "startTime": "2024-01-15T15:30:00Z",
        "status": "live"
      }
    }
  },
  "timestamp": "2024-01-15T14:30:00Z"
}

Response Schema

Returns a confirmation object:

success (boolean): Whether the webhook was processed successfully
processedAt (string): Timestamp when the data was processed
eventCount (number): Number of events processed
errors (array): Array of error messages if processing failed

Example Request

curl -X POST "{your-base-url}/v1/webhooks/program/liveEvents" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=abc123..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "LIVE_WIDGET": {
      "availableMarkets": {...},
      "events": {...}
    },
    "timestamp": "2024-01-15T14:30:00Z"
  }'

Example Response

{
  "success": true,
  "processedAt": "2024-01-15T14:30:01Z",
  "eventCount": 15,
  "errors": []
}

Error Responses

401 Unauthorized - Invalid HMAC signature:

{
  "error": "Invalid signature",
  "code": "INVALID_SIGNATURE"
}

409 Conflict - Duplicate idempotency key:

{
  "success": true,
  "processedAt": "2024-01-15T14:30:00Z",
  "eventCount": 15,
  "cached": true
}

400 Bad Request - Invalid payload:

{
  "error": "Invalid payload structure",
  "code": "INVALID_PAYLOAD",
  "errors": ["Missing required field: LIVE_WIDGET"]
}

Hour Events Webhook

Receive updates for events scheduled for specific hour windows.

Endpoint: POST /v1/webhooks/program/hourEvents

Headers

Same as Live Events Webhook.

Request Body

The payload structure matches the response from GET /v1/program/events/hourEvents/{hour}:

{
  "UPCOMING": {
    "availableMarkets": {...},
    "sportCompetitionMap": {...},
    "events": {...}
  },
  "hour": 2,
  "timestamp": "2024-01-15T14:30:00Z"
}

Response Schema

Same as Live Events Webhook.

Recommended Events Webhook

Receive updates for recommended sporting events.

Endpoint: POST /v1/webhooks/program/recommendedEvents

Headers

Same as Live Events Webhook.

Request Body

The payload structure matches the response from GET /v1/program/recommendedEvents:

{
  "RECOMMENDED": {
    "availableMarkets": {...},
    "sportCompetitionMap": {...},
    "competitionEventMap": {...},
    "events": {...}
  },
  "timestamp": "2024-01-15T14:30:00Z"
}

Response Schema

Same as Live Events Webhook.

Receive updates for the navigation tree structure.

Endpoint: POST /v1/webhooks/program/navigationTree

Headers

Same as Live Events Webhook.

Request Body

The payload structure matches the response from GET /v1/program/navigationTree/all:

{
  "groupId": null,
  "meta": {
    "outrights": 127,
    "events": 1448,
    "live": 17,
    "today": 807,
    "3hrs": 46,
    "48hrs": 1208
  },
  "count": 1575,
  "children": [...],
  "timestamp": "2024-01-15T14:30:00Z"
}

Response Schema

Same as Live Events Webhook.

Top Competitions Webhook

Receive updates for top competitions.

Endpoint: POST /v1/webhooks/program/topCompetitions

Headers

Same as Live Events Webhook.

Request Body

The payload structure matches the response from GET /v1/program/top-competitions:

{
  "competitions": [
    {
      "groupId": "42301",
      "groupName": "Bundesliga",
      "parentGroupName": "Deutschland",
      "icon": "bundesliga",
      "eventCount": 19
    }
  ],
  "timestamp": "2024-01-15T14:30:00Z"
}

Response Schema

Same as Live Events Webhook.

Top Combos Webhook

Receive updates for top betting combinations.

Endpoint: POST /v1/webhooks/program/topCombos

Headers

Same as Live Events Webhook.

Request Body

The payload structure matches the response from GET /v1/program/top-combos:

{
  "availableSports": ["soccer"],
  "combis": {...},
  "combiMarketsMap": {...},
  "markets": {...},
  "sportCombisMap": {...},
  "sports": ["soccer"],
  "timestamp": "2024-01-15T14:30:00Z"
}

Response Schema

Same as Live Events Webhook.

Webhook Retry Logic

Feedbird should implement exponential backoff retry logic:

Initial retry: Wait 1 second
Subsequent retries: Double the wait time (2s, 4s, 8s, 16s, 32s)
Maximum retries: 5 attempts
Retry conditions: Retry on 5xx errors, network failures, and timeouts
Do not retry: 4xx errors (except 409 Conflict with different idempotency key)

Example Retry Logic:

async function sendWebhookWithRetry(url, payload, signature, idempotencyKey) {
  const maxRetries = 5;
  let waitTime = 1000; // 1 second
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Webhook-Signature': signature,
          'Idempotency-Key': idempotencyKey
        },
        body: JSON.stringify(payload)
      });
      
      if (response.ok) {
        return await response.json();
      }
      
      // Don't retry on 4xx errors (except 409)
      if (response.status >= 400 && response.status < 500 && response.status !== 409) {
        throw new Error(`Client error: ${response.status}`);
      }
      
      // Retry on 5xx errors
      if (response.status >= 500) {
        throw new Error(`Server error: ${response.status}`);
      }
    } catch (error) {
      if (attempt === maxRetries - 1) {
        throw error;
      }
      
      // Wait before retry
      await new Promise(resolve => setTimeout(resolve, waitTime));
      waitTime *= 2; // Exponential backoff
    }
  }
}

Webhook Best Practices

Always include timestamp: Include a timestamp field in the payload for replay attack prevention
Use unique idempotency keys: Generate a new UUID v4 for each webhook request
Validate payload before sending: Ensure payload structure matches expected schema
Monitor webhook delivery: Track success/failure rates and implement alerting
Handle errors gracefully: Log errors and implement retry logic with exponential backoff
Keep secrets secure: Store webhook secrets securely and rotate them periodically
Test webhook endpoints: Use test endpoints or staging environments before production deployment

Betbird API

Bet placement and virtual ticket management endpoints

Feedbird API

Program engine endpoints and webhook integration

On this page

Databird API Base URL Overview Program APIs Get Live Events Query Parameters Response Schema Example Request Example Response Get Hour Events Path Parameters Query Parameters Response Schema Example Request Example Response Get Recommended Events Query Parameters Response Schema Example Request Example Response Get Navigation Tree Query Parameters Response Schema Example Request Example Response Get Top Competitions Query Parameters Response Schema Example Request Example Response Get Top Combos Query Parameters Response Schema Example Request Example Response Get Single Event Path Parameters Query Parameters Response Schema Example Request Example Response Get Events by Competition Path Parameters Query Parameters Response Schema Example Request Example Response Get Events by Sport Path Parameters Query Parameters Response Schema Example Request Example Response Get Events by Date Query Parameters Response Schema Example Request Search Events Query Parameters Response Schema Example Request Get All Markets for Event Path Parameters Query Parameters Response Schema Example Request Get Event Statistics Path Parameters Query Parameters Response Schema Example Request Example Response Get Market Types for Sport Path Parameters Query Parameters Response Schema Example Request Example Response Webhook Endpoints Webhook Security HMAC Signature Authentication Idempotency Webhook Endpoints Live Events Webhook Headers Request Body Response Schema Example Request Example Response Error Responses Hour Events Webhook Headers Request Body Response Schema Recommended Events Webhook Headers Request Body Response Schema Navigation Tree Webhook Headers Request Body Response Schema Top Competitions Webhook Headers Request Body Response Schema Top Combos Webhook Headers Request Body Response Schema Webhook Retry Logic Webhook Best Practices