# Odditt API Documentation

> Documentation for Odditt API

## Guides: Getting Started
- [Getting Started](https://developer.odditt.com/docs/getting-started.md)
- [Guides](https://developer.odditt.com/docs/guides.md)
- [Glossary](https://developer.odditt.com/docs/glossary.md)
- [Filtering & Query Parameters](https://developer.odditt.com/docs/filtering-query-parameters.md)
- [Segmentation & Tags](https://developer.odditt.com/docs/segmentation-tags.md)
- [Pagination](https://developer.odditt.com/docs/pagination.md)
- [Rate Limiting](https://developer.odditt.com/docs/rate-limiting.md)
- [Response Format & Error Handling](https://developer.odditt.com/docs/response-format-error-handling.md)
- [Localization](https://developer.odditt.com/docs/localization.md)
- [Affiliate](https://developer.odditt.com/docs/affiliate-api.md)
- [Caching](https://developer.odditt.com/docs/caching.md)
- [Versioning](https://developer.odditt.com/docs/versioning.md)
- [Advanced Authentication](https://developer.odditt.com/docs/advanced-authentication.md)
- [Account Management](https://developer.odditt.com/docs/account-management.md)
- [League Coverage](https://developer.odditt.com/docs/league-coverage.md)

## Guides: Widgets
- [Overview](https://developer.odditt.com/docs/overview.md)
- [Playground](https://developer.odditt.com/docs/playground.md)
- [Presets](https://developer.odditt.com/docs/presets.md)
- [Iframe Parameters](https://developer.odditt.com/docs/iframe-parameters.md)
- [Widget Events](https://developer.odditt.com/docs/widget-events.md)
- [Product Modes](https://developer.odditt.com/docs/product-modes.md)
- [Integration Recipes](https://developer.odditt.com/docs/integration-recipes.md)
- [Mobile SDKs](https://developer.odditt.com/docs/mobile-sdks.md)
- [Live Scores & Realtime](https://developer.odditt.com/docs/integration-recipes-1.md)
- [Widget Modes](https://developer.odditt.com/docs/widget-modes.md)
- [Testing & Simulation](https://developer.odditt.com/docs/testing-simulation.md)

## API Reference: Odditt B2B Public API
- Authentication
  - [Login with API key](https://developer.odditt.com/reference/post_v1-auth-login.md): ## Example response  ```json {   "access_token": "<REDACTED>",   "refresh_token": "<REDACTED>",   "token_type": "Bearer",   "expires_at": "2026-07-31T22:34:51.110325536Z",   "expires_in": 899 } ```
  - [Refresh tokens](https://developer.odditt.com/reference/post_v1-auth-refresh.md): ## Example request  ```json {   "refresh_token": "<REDACTED>" } ```  ## Example response  ```json {   "access_token": "<REDACTED>",   "refresh_token": "<REDACTED>",   "token_type": "Bearer",…
  - [OAuth login (client credentials)](https://developer.odditt.com/reference/post_v1-oauth-login.md)
  - [OAuth refresh](https://developer.odditt.com/reference/post_v1-oauth-refresh.md)
- Account
  - [Get own usage stats](https://developer.odditt.com/reference/get_v1-account-usage.md)
- Events
  - [Get upcoming events](https://developer.odditt.com/reference/post_v1-events-upcoming-events.md): Returns upcoming events with optional sport and league filters, timezone support, and pagination.  ## Example response  ```json {   "page": 1,   "page_size": 100,   "records": [     {…
- References
  - [Get betting market categories](https://developer.odditt.com/reference/get_v1-references-betting-market-categories.md): Returns available betting market categories, optionally filtered by sport.  ## Example response  ```json {   "records": [     {       "betting_market_category_display_name": "Assist Props",…
  - [Get all betting market positions](https://developer.odditt.com/reference/get_v1-references-betting-market-positions.md): Returns all available betting market positions.  ## Example response  ```json {   "records": [     {       "betting_market_position_display_description": "Home",…
  - [Get betting markets (paginated)](https://developer.odditt.com/reference/get_v1-references-betting-markets.md): Returns a paginated list of betting markets with optional sport filter and text search.  ## Example response  ```json {   "page": 1,   "page_size": 100,   "records": [     {…
  - [Get countries (paginated)](https://developer.odditt.com/reference/get_v1-references-countries.md): ## Example response  ```json {   "page": 1,   "page_size": 20,   "records": [     {       "external_key": "algeria",       "flag_emoji": "1F1E9 1F1FF",       "id": 1122,       "name": "Algeria"…
  - [Get event periods](https://developer.odditt.com/reference/get_v1-references-event-periods.md): Returns available event periods, optionally filtered by sport.  ## Example response  ```json {   "records": [     {       "event_period_abr": "Q1",       "event_period_category": "quarter",…
  - [Get leagues (paginated)](https://developer.odditt.com/reference/get_v1-references-leagues.md): ## Example response  ```json {   "page": 1,   "page_size": 20,   "records": [     {       "country_external_key": null,       "country_flag_unicode": null,       "country_id": null,…
  - [Get odds formats (paginated)](https://developer.odditt.com/reference/get_v1-references-odds-format.md): ## Example response  ```json {   "page": 1,   "page_size": 20,   "records": [     {       "id": 1,       "name": "decimal",       "translations": {         "en": "Decimal"       }     },     {…
  - [Get operators (paginated)](https://developer.odditt.com/reference/get_v1-references-operators.md): ## Example response  ```json {   "page": 1,   "page_size": 20,   "records": [     {       "external_key": "bet365",       "id": 2,       "is_active": true,       "is_licensed": true,…
  - [Get players (paginated)](https://developer.odditt.com/reference/get_v1-references-players.md): ## Example response  ```json {   "page": 1,   "page_size": 20,   "records": [     {       "external_key": "kauan",       "first_name": "Kauan",       "headshot_url":…
  - [Get sports (paginated)](https://developer.odditt.com/reference/get_v1-references-sports.md): ## Example response  ```json {   "page": 1,   "page_size": 20,   "records": [     {       "emoji_unicode": "1F3C8",       "external_key": "american-football",       "id": 1,       "is_active": true,…
  - [Get teams (paginated)](https://developer.odditt.com/reference/get_v1-references-teams.md): Returns a paginated list of teams. When neither `start_date` nor `end_date` is provided, only teams whose affiliation is currently active are returned. When either date is provided, the result is…
  - [Get tag dimensions](https://developer.odditt.com/reference/get_v1-references-tag-dimensions.md): Returns the top-level tag dimension categories. Use these as entry points to explore the tag hierarchy. Optionally filter to dimensions relevant to a specific flow type.  ## Example response  ```json…
  - [Search tag types](https://developer.odditt.com/reference/get_v1-references-tag-types-search.md): Search across tag types by keyword. Returns paginated results with breadcrumb paths for disambiguation. Use terminal_only combined with flow_type to find only tags that are usable as filters for a…
  - [Get child tag types](https://developer.odditt.com/reference/get_v1-references-tag-types-tag-type-id-children.md): Returns the direct children of a given tag type, along with context about the parent (description and known values). Use this to navigate the tag hierarchy from dimensions down to individual…
  - [Get subnational regions (paginated)](https://developer.odditt.com/reference/get_v1-references-subnational-regions.md): ## Example response  ```json {   "page": 1,   "page_size": 20,   "records": [     {       "complete_subnational_region_code": "GD-01",       "subnational_region_code": "01",…
- Trends
  - [Get fact flow graph data](https://developer.odditt.com/reference/get_v1-trends-flow-graph-data-fact-flow-id.md): ## Example response  ```json {   "display_json": {     "H2H": {       "colors": [         "green",         "green",         "green"       ],       "dates": [         "2020-08-06",…
  - [Get flows (paginated)](https://developer.odditt.com/reference/post_v1-trends-flows.md): Same parameters as mixed-flows but returns non-mixed (single-type) flows. Uses the same underlying request model.  ## Example response  ```json {   "fact_flow_records": [     {…
  - [Get mixed flows (paginated)](https://developer.odditt.com/reference/post_v1-trends-mixed-flows.md): Returns a paginated set of mixed flows matching the supplied filters.  This endpoint also accepts the HTTP `QUERY` method. A `QUERY` request takes the same request body and returns the same response…
- Odds
  - [Get upcoming odds by event](https://developer.odditt.com/reference/post_v1-odds-upcoming-odds-by-event.md): Returns paginated betting market positions for a specific upcoming event, optionally filtered by operator.  ## Example request  ```json {   "event_id": 3426175 } ```  ## Example response  ```json {…
- Historical
  - [List historical odds events (paginated)](https://developer.odditt.com/reference/get_v1-historical-events.md): Returns a paginated list of events with historical odds available to your account, filterable by sport, league, team, and date range. Use each event's ID with `GET…
  - [Get historical odds for an event (JSON or CSV)](https://developer.odditt.com/reference/get_v1-historical-odds-event-id-ext.md): Returns the historical odds for an event in your preferred format — `json` or `csv`, chosen by the path extension. One HTTP call per event.  Responses carry a strong `ETag`; send `If-None-Match` to…
- Affiliates
  - [Single-bet cart for affiliate mode](https://developer.odditt.com/reference/post_v1-affiliates-event-position.md): Returns live odds across operators for a single event betting market position, overlaid with the calling client's best affiliate offer per operator. Powers the widget's "Bet Now" cart for a single…
  - [Parlay cart for affiliate mode](https://developer.odditt.com/reference/post_v1-affiliates-parlay.md): Returns combined parlay odds per operator, the per-leg single bets, and the calling client's best affiliate offer per operator, with combo deeplinks generated per operator. Powers the widget's "Bet…
- Offers
  - [Client offer cards for a geography](https://developer.odditt.com/reference/post_v1-affiliates-offers.md): Returns the calling client's best operator offer card per operator for a geography. The core offers read the widget cart renders.
  - [Paginated client deals](https://developer.odditt.com/reference/post_v1-affiliates-deals.md): Paginated client deals (carousel/featured/list), optionally enriched with operator reviews. Scoped to the authenticated client.
- Links
  - [Create or upsert a single link](https://developer.odditt.com/reference/post_v1-affiliates-links.md): Creates a link, or updates the existing one on the natural key (operator + geography + category + campaign + label). Resolves operator, country, and region at write time; unresolvable codes return…
  - [Bulk create/upsert links (JSON or CSV)](https://developer.odditt.com/reference/post_v1-affiliates-links-bulk.md): Upserts many links idempotently on the natural key. Accepts a JSON array of row objects or a text/csv body (header row). Per-row errors never fail the batch. Use ?dry_run=true to validate without…
  - [Bulk patch links by filter](https://developer.odditt.com/reference/patch_v1-affiliates-links-bulk.md): Applies a patch to all links matching a filter (e.g. rewrite all FanDuel-NJ URLs on a domain change).
  - [Bulk deactivate links by filter](https://developer.odditt.com/reference/post_v1-affiliates-links-bulk-deactivate.md): Soft-deletes all links matching a filter (e.g. a state goes offline).
  - [List async bulk jobs](https://developer.odditt.com/reference/get_v1-affiliates-links-jobs.md): Recent async bulk jobs for the authenticated client.
  - [Poll an async bulk job](https://developer.odditt.com/reference/get_v1-affiliates-links-jobs-job-id.md): Status, counts, and per-row errors for one async bulk job. Poll until status is "completed" or "failed". Scoped to the authenticated client.
- Reporting
  - [Impression/click rollups](https://developer.odditt.com/reference/get_v1-affiliates-links-clicks.md): Per-link, per-day impression and click counts for the authenticated client.
  - [Inventory counts](https://developer.odditt.com/reference/get_v1-affiliates-links-inventory-summary.md): Active/inactive link counts grouped by the requested dimension.
- Lookups
  - [Operators](https://developer.odditt.com/reference/get_v1-affiliates-lookups-operators.md): Paginated list of operators, optionally filtered by a free-text search term.
  - [Operator jurisdictions](https://developer.odditt.com/reference/get_v1-affiliates-lookups-operator-jurisdictions.md): Where we believe an operator is live. Informational only — not an upload gate.
  - [Offer categories](https://developer.odditt.com/reference/get_v1-affiliates-lookups-offer-categories.md)
  - [Affiliate networks](https://developer.odditt.com/reference/get_v1-affiliates-lookups-affiliate-networks.md)