> For the complete documentation index, see [llms.txt](https://developer.aiodds.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.aiodds.com/get-started/first-integration.md). # First integration > This guide shows the recommended first integration flow for teams connecting AiOdds data to a sportsbook, trading system, analytics workflow, or monitoring tool. When integrating AiOdds for the first time, the recommended flow is: {% stepper %} {% step %} ### API {% endstep %} {% step %} ### Snapshot {% endstep %} {% step %} ### WebSocket {% endstep %} {% endstepper %} This ensures your system has a complete data foundation before it starts receiving real-time updates. ### 1. Fetch Foundational Data with API Start by using the API to retrieve all basic reference data. This includes: * [sports](/bookmaker-odds/basic-data/sport.md), * [locations](/bookmaker-odds/basic-data/location.md), * [tournaments](/bookmaker-odds/basic-data/tournament.md), * [teams](/bookmaker-odds/basic-data/team.md), * [bookmakers](/bookmaker-odds/bookmaker-odds/bookmaker.md), * [markets](/bookmaker-odds/bookmaker-odds/market.md), * match-related information. These endpoints are used to build your local data structure and mapping tables. You only need to fetch this foundational data once at the beginning, then store it locally in your backend database. APIs such as `Get ... By ID` can be used later for validation or checking specific records. {% hint style="danger" %} **Do not call the API directly from the frontend.** The backend should request, store, process, and then return the required data to the frontend. {% endhint %} ### 2. Use Snapshot to Load Full Match and Odds Data After the basic data is ready, use Snapshot to retrieve the full match and odds dataset. Snapshot is used for initial full data retrieval. It includes match schedules and odds data, making it suitable for building the first complete version of your local dataset. You can use Snapshot for: * [In-Play data](/bookmaker-odds/bookmaker-odds/snapshot-v2.md#get-in-play-odds-snapshot) * [Pre-Match data](/bookmaker-odds/bookmaker-odds/snapshot-v2.md#get-pre-match-odds-snapshot) * [AI Trading data](/trading-odds/ai-trading/snapshot-v2.md) Because Snapshot contains a large volume of data, processing and storing it may take several minutes. It should not be used as a high-frequency endpoint. For the first integration, the Snapshot endpoint is mainly used to create the initial full data state. ### 3. Start WebSocket for Delta Updates Once the snapshot has been stored, start WebSocket to receive real-time delta updates. WebSocket actively pushes changes when data updates. It supports four main data types: * [Bookmaker Odds](/bookmaker-odds/websocket/bookmaker-odds.md): odds updates * [Settlement](/bookmaker-odds/websocket/settlement.md): settlement updates * [Match](/bookmaker-odds/websocket/match.md): match updates * [Match Score](/bookmaker-odds/websocket/match-score.md): statistics updates The WebSocket data is returned in protobuf format, so your backend must parse and convert it before storing or sending it to the frontend. Clients should also implement their own reconnection mechanism to ensure the service can recover from connection interruptions. ## Recommended First Integration Flow 1. Use API to fetch basic reference data. 2. Store all basic data locally in the backend. 3. Use Snapshot to retrieve full match and odds data. 4. Start WebSocket to receive delta updates. 5. Parse WebSocket protobuf data and update local storage. 6. Use Snapshot again only when data is missing or recovery is needed. This integration flow gives your system a complete initial dataset, reliable real-time updates, and a clear fallback mechanism for missing data. *** ## Keep Data Consistent During Recovery If data is missing or the WebSocket connection is interrupted, use Snapshot as a fallback. During Snapshot recovery, continue using WebSocket to capture real-time changes. Once the Snapshot data is fully received, insert the Snapshot data before the WebSocket updates. This helps maintain correct data order and consistency. For frequently changing data such as odds, it is recommended to use a caching system like Redis. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.aiodds.com/get-started/first-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.