# Migration Guide - V1 to V2 API
URL: https://sockodds.com/docs/info/v1-to-v2/

# Migration Guide - V1 to V2 API [#migration-guide---v1-to-v2-api]

> SockOdds has only ever served the v2 schema. This page exists for teams arriving from a SportsGameOdds **v1** integration: the changes below are the v1 → v2 differences you must make, and the resulting v2 code runs against SockOdds unchanged.

## Overview of changes [#overview-of-changes]

- **Combined /odds and /events endpoints** — everything is on `/v2/events`; there is no `/v2/odds`.
- **Deeplinks on events** — `links.bookmakers` and `links.betslip`.
- **Bookmaker prices persist when unavailable** — every `byBookmaker` entry carries `available`; filter on it.
- **Unique playerIDs** — `PLAYER_NAME_NUMBER_LEAGUE` (`PATRICK_MAHOMES_1_NFL`), the same across teams.
- **Many more request options** on the events endpoint.

## Upgrade guide [#upgrade-guide]

### Swap the base URL [#swap-the-base-url]

```diff
- https://api.sportsgameodds.com/v1/...
+ https://api.sockodds.com/v2/...
```

### Point v1/events and v1/odds at the combined v2/events [#point-v1events-and-v1odds-at-the-combined-v2events]

```diff
- /v1/events...
- /v1/odds...
+ /v2/events...
```

### Odds field renames [#odds-field-renames]

- `odds` → `fairOdds`
- `spread` → `fairSpread`
- `overUnder` → `fairOverUnder`
- `isFallbackOdds` → removed (no placeholder even-money prices)

### Status field renames [#status-field-renames]

- `hasMarketOdds` / `hasAnyOdds` → `oddsPresent`
- `anyOddsAvailable` / `marketOddsAvailable` → `oddsAvailable`
- `nextUpdateAt` → removed (use `info.lastUpdatedAt`)

### Add includeAltLines if you need alt lines [#add-includealtlines-if-you-need-alt-lines]

Alt lines are off by default in v2.

### Filter unavailable byBookmaker odds [#filter-unavailable-bybookmaker-odds]

```diff
+ Event.odds.<oddID>.byBookmaker.<bookmakerID>.available
```

### Player name paths [#player-name-paths]

- `Player.firstName` → `Player.names.firstName` on `/players` (event players keep the flat fields)

## New features & non-breaking changes [#new-features-non-breaking-changes]

- The API key can be a query param (`?apiKey=`).
- New params on `/v2/events`: `type`, `oddsPresent`, `includeOpposingOdds` (alias `includeOpposingOddIDs`), `includeAltLines`, `bookmakerID`, `teamID`, `playerID`, `live`, `started`, `ended`, `cancelled`, `finalized`, `includeOpenCloseOdds` (accepted; no snapshots yet).
- `marketName` on every market; `decimal` on every bookmaker entry.
- Default/max limits: `/events` 10/100; `/teams` and `/players` 50/250.

> Need help?[FAQ](https://sockodds.com/docs/faq/) · [Email](mailto:api@sockodds.com) · [Contact](https://sockodds.com/contact-us/)