Getting Started

Welcome to the Odditt B2B API. This guide will get you from API key to live data in under a minute.

Access & Onboarding

Everything you need is provisioned for you by the Odditt team at onboarding - there is no self-serve signup. Here's how it works:

What Odditt hands you:

• API keys - one for sandbox, one for production. Keys are shown once at issuance, so store them safely.
• Your widget instance (widget customers) - a dedicated deployment at your own subdomain, pre-configured for your account. The widget.example.com URLs in these docs stand in for the real URL you receive.
• Playground access - the URL plus login credentials for each of your designers, so your team can build and preview themes.
• Preset hosting - your approved themes are hosted and served by Odditt; no infrastructure needed on your side.
• A point of contact - your Odditt contact coordinates provisioning and any integration questions.

What Odditt needs from you:

• Embed origins (widget customers) - the exact domains that will embed the widget (e.g. https://www.yoursite.com). Your widget instance only renders inside registered origins - if your iframe shows up blank, an unregistered origin is the most common cause; send us the origin and we'll add it.
• Default language and the countries/regions you operate in.
• Designer names for playground logins.
• Anything your contract enables that needs configuration - odds formats, product mode, feature entitlements - which we set on your account for you.

Send these to your Odditt contact and provisioning typically completes within a business day. Then come back here:

Base URL

All production API requests are made to:

https://api.odditt.com

Sandbox URL:

https://sandbox.odditt.com

All endpoints are prefixed with /v1/.

Prerequisites

Before you begin, make sure you have:

1. An API key provided by the Odditt team during onboarding.
2. An HTTP client - cURL, Postman, your application code, or any tool that can make HTTP requests.

That's it. No login step, no token exchange - just add your API key to a header and start making calls.

Your First API Call

Pass your API key in the X-API-Key header. Let's fetch the list of available sports:

curl https://api.odditt.com/v1/references/sports \
 -H "X-API-Key: YOUR_API_KEY"

You'll get back a paginated list of sports with their IDs and names. These IDs are what you'll use to drill deeper into the API.

Explore Your Data

The reference endpoints let you discover and map the entities in the Odditt system. Work from broad to specific: sports, then leagues, then teams and players.

List leagues for a sport

Pick a sport_id from the previous call and fetch its leagues:

curl "https://api.odditt.com/v1/references/leagues?sport_id=1&page=1&page_size=20" \
 -H "X-API-Key: YOUR_API_KEY"

List teams in a league

curl "https://api.odditt.com/v1/references/teams?league_id=7&page=1&page_size=20" \
 -H "X-API-Key: YOUR_API_KEY"

List players on a team

curl "https://api.odditt.com/v1/references/players?team_id=42&page=1&page_size=20" \
 -H "X-API-Key: YOUR_API_KEY"

All reference endpoints support search for partial name matching and are paginated. See Pagination for response format details.

Get Upcoming Events

Once you know which sport and league you're interested in, fetch upcoming events:

curl -X POST https://api.odditt.com/v1/events/upcoming-events \
 -H "X-API-Key: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "sport_id": 1,
    "league_id": 7,
    "page": 1,
    "page_size": 20
  }'

You can also filter by date range using event_start_date_from and event_start_date_to to narrow down to a specific window.

The response includes event IDs, team matchups, and scheduled start times. You'll use these event IDs in the next step.

Discover Trends: Flows and Mixed Flows

Odditt provides flows - curated statistical trends and insights about upcoming bets. See them in action at demo.odditt.com.

There are two main endpoints for retrieving flows:

Mixed Flows (recommended starting point)

Returns all flow types together (fact flows, fun flows, parlays) in a single paginated response:

curl -X POST https://api.odditt.com/v1/trends/mixed-flows \
 -H "X-API-Key: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "sport_id": 1,
    "league_id": 7,
    "page": 1,
    "page_size": 10
  }'

Both endpoints return the same underlying content - the difference is how it's delivered. Mixed flows gives you a pre-mixed feed where all flow types (fact flows, fun flows, parlays) are interleaved together in a single paginated list. This is the easiest way to get a diverse set of trends without managing each type separately.

Flows (unmixed, by type)

Returns the same content as mixed flows, but separated by type. You request one flow type at a time:

curl -X POST https://api.odditt.com/v1/trends/flows \
 -H "X-API-Key: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "sport_id": 1,
    "league_id": 7,
    "flow_type": "fact",
    "bet_type": "singles",
    "page": 1,
    "page_size": 10
  }'

Use this when you want to paginate through a single flow type (fact, fun, plain) or bet type (singles, parlay, same_game_parlay) independently - for example, if your UI has separate sections for each type or you need to apply statistical thresholds to a specific category.

When to use which

Expand a Fact Flow: Graph Data

Fact flows arrive collapsed by default (fact_flow_type: "base"): the card carries its surfaced trend window, narrative, and hit-rate numbers - light enough to render a whole feed. When the user expands a card, fetch the full picture with Get fact flow graph data:

curl https://api.odditt.com/v1/trends/flow-graph-data/468466851 \
 -H "X-API-Key: YOUR_API_KEY"

The response is a display_json object keyed by trend window (L5, L10, L20, H2H, SZN, LAST SZN), each with per-game values, result colors, dates, and opponents plus its own narrative and tagline - everything needed to draw the bar chart, the split tabs, and the per-split story. This start-collapsed / expand-on-demand pattern is exactly how the widget renders fact flows.

Two notes:

• Fact flow parlays work the same way per leg: each leg carries its own fact flow id - call the graph endpoint with the leg's id when the user expands that leg.
• If you'd rather skip the second call, request fact_flow_type: "expanded" on the flows endpoints to get split data inline - heavier payloads, no follow-up fetch.

Get Odds for an Event

For a specific event, retrieve the available betting markets and odds:

curl -X POST https://api.odditt.com/v1/odds/upcoming-odds-by-event \
 -H "X-API-Key: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "event_id": 12345,
    "page": 1,
    "page_size": 20
  }'

This returns the betting markets available for the event and the positions you can bet on within each market.

Mapping Bets: ETL Workflow

If you need to map Odditt's betting data to your own system, a typical ETL workflow looks like this:

1. Pull upcoming events for your target leagues using paginated calls to /v1/events/upcoming-events.
2. For each event, paginate through /v1/odds/upcoming-odds-by-event to get the full set of available bets.
3. Map bet identifiers using the dimension tables below so your system understands the betting market types and positions.

This approach gives you full coverage of all available bets for the events you care about.

Understanding Betting Dimensions

Three reference tables help you understand and categorize the bets returned by the API:

Betting Markets

Describes the types of bets available (e.g., moneyline, spread, totals, player props):

curl "https://api.odditt.com/v1/references/betting-markets?page=1&page_size=50" \
 -H "X-API-Key: YOUR_API_KEY"

Betting Market Positions

Describes the specific sides or positions within each market (e.g., over/under, home/away):

curl https://api.odditt.com/v1/references/betting-market-positions \
 -H "X-API-Key: YOUR_API_KEY"

Event Periods

Describes the time segments a bet can apply to (e.g., full game, first half, first quarter). See the API Reference for the full schema.

Together, these three dimensions let you fully classify any bet in the system.

Advanced Filtering

The API supports extensive filtering options across most endpoints - hit rate thresholds, implied probability ranges, operator filters, betting market filters, date ranges, and more. See the Filtering guide for the full reference.

Pagination

All list and search endpoints return paginated results. Use page and page_size parameters to navigate. See Pagination for the response format and best practices.

Advanced Authentication

For getting started, the X-API-Key header is all you need. For production deployments, you may want to use JWT tokens to reduce how often your API key is sent over the wire. The API supports both API key exchange and OAuth2 client credentials flows for obtaining tokens.

See the Advanced Authentication guide for details on token lifecycle, refresh flows, and best practices.

Next Steps

• Browse the API Reference for complete endpoint documentation with request/response schemas.
• Read Filtering to learn about all available query parameters.
• Explore Segmentation & Tags to target the feed by content and metadata tags.
• See the Affiliate API for offers, the comparison cart, and link management.
• Check Rate Limiting to understand your request limits.
• See Response Format & Error Handling for HTTP status codes and error response formats.
• Explore Localization to get trend narratives in other languages.