Pinnacle Player Props API: Getting Props and Specials in JSON

Pinnacle is not where most people go for player props, and that is exactly why its prop prices are interesting. A recreational book prices a points total around what its customers like to bet. Pinnacle prices it around what sharp money will take at a limit. When those two disagree, the gap is usually on the recreational side.

This post is about getting those prices out of the pinnodds Pinnacle API: which flag turns them on, what the rows look like, and how not to drown in them.

What Pinnacle calls a special

In Pinnacle's market model the main lines on an event are moneyline, spread, total and team total, per period. Everything else is a special: player props, team props, exact scores, "race to" markets, futures and outrights. Specials are their own events, priced separately, with their own stake limits, and they are usually much lower-limit than the main lines.

Two consequences for an API user. Specials multiply the size of a board by a lot, and they move differently: a main line moves because money came in, a prop often moves because the main line it is derived from moved.

Turning them on

Specials are off by default. Every existing integration that polls /kit/v1/prematch/fixtures keeps the payload it expects. To include them, add one parameter:

curl -H "x-api-key: YOUR_KEY" \
  "https://pinnodds.com/kit/v1/prematch/fixtures?sport_id=5&include_specials=1"

The flag takes two values:

Flat is cheaper to poll because a prop that changed is one small row, not a re-send of the whole parent. Nested is easier to read.

What a special row carries

A special-market row has everything a normal event row has, plus:

• special, the market's name as Pinnacle titles it,
• special_category, the family it belongs to (player prop, team prop, exact score, future and so on),
• special_units, the unit the line is in where that applies (points, yards, goals),
• special_markets, the priced outcomes with their decimal prices and limits.

The parent_id links it to the match. So "fetch the game, then fetch its props" is one call, and "find every prop on this game" is a filter on parent_id.

The exact field list is in the documentation, which is the source of truth if this post and the docs ever disagree.

Keeping the payload sane

An NFL Sunday with specials on is a large response. Some habits that keep it workable:

Filter by sport and by parent. Do not pull specials for every sport if you only model one league. Pull fixtures for the sport, pick the event ids you want, and request those events' lines by event_id. A special fetched by its own id comes back whether or not the flag is set.

Poll with since=. On the flat shape, pass the last timestamp you saw and you get only rows that changed. On a quiet afternoon that is a few props, not the whole board.

Let the drop detector do the watching. If what you actually want is "tell me when a prop price falls", do not diff boards. /api/drops and the SSE stream report falls on every priced market, props included, with the from and to prices and the no-vig fair price. One request every few minutes replaces a polling loop.

Respect the limits. Prop limits at Pinnacle are a fraction of main-line limits, and the max field on each price tells you what they are. A prop price can move on a single bet. Treat a prop drop as a weaker signal than a main-line drop of the same size.

A worked flow

Say you want Pinnacle's view on tonight's NBA points props to compare against a soft book.

1. GET /kit/v1/prematch/fixtures?sport_id=3 once. Keep the event_id of each game that matters.
2. For each, GET /kit/v1/prematch/lines?event_id=…&include_specials=nested. Each game comes back with its specials array.
3. Filter special_category to player props, read special_markets for each, and compute the no-vig fair price with the few lines in the no-vig post.
4. Compare against the soft book's price. Where the soft price is above the fair price by more than the limit you are comfortable with, you have a candidate.
5. Subscribe to drops with a low threshold so you hear about Pinnacle moving the line before you place anything.

Four of those five steps fit inside the free key's 100 requests a day if you keep the game list short.

What this is not

pinnodds carries prices. It does not settle markets, grade props or interpret Pinnacle's rules on what counts as a completed pass. For settlement questions, read Pinnacle's rules. For whether a given prop exists on a given night, the feed is the answer: if Pinnacle priced it, it is there.

Props, team totals and everything else described here are on every plan, including the free trial key. What changes with the paid plans is how often you can ask and whether you can be pushed to.

pinnodds is an independent service and is not affiliated with, endorsed by or connected to Pinnacle.