Feedback for the API should be directed to customerservice@pinnacle.com, however, we do not offer technical support or instructions beyond the available manual

Pinnacle API Specification v1.0
(updated: 2017/10/26)

Last Updated

26/10/2017

Overview

Pinnacle API is a RESTful service for straight, special, paralys and teasers betting on all sports. 

Please note that in order to access Pinnacle API you must have a funded account.

Data Formats

Pinnacle API supports only JSON format.

HTTP Request must have:

Accept: application/json

POST HTTP Request must have JSON body content and:

Content-Type: application/json

Compression

API supports HTTP compression. We strongly recommend using compression as it would give the best performances.

Please make sure you set the User Agent http header or compression might not work.

Date time

All dates and times are in UTC time zone, ISO 8601 format

Deduplication

When a client issues a network request, it is always possible for the request to timeout or return an error status code indicating that bet may not have been accepted. This opens up the possibility of the same request being sent more than once, which could create duplicate bets. Deduplication is a technique for avoiding creating these duplicates when retrying a create request.  We do the deduplication automatically for you.  If the bet is accepted, we store the uniqueRequestId in the system and we keep it for 30 min. If you try again to place a bet with the same uniqueRequestId, within that time range,  you will get appropriate error.

All place bet requests support deduplication.

Authentication

API use HTTP Basic access authentication . Always use HTTPS to access the API. You need to send HTTP Request header like this:

Authorization: Basic <Base64 value of UTF-8 encoded “username:password”>

For example:
Authorization: Basic U03MyOT23YbzMDc6d3c3O1DQ1

Getting Started

Step 1 – Sign Up

To get started you would need to create an account.

Please note that in order to access Pinnacle API the account must be funded.

Step 2 - Get a List of Offered Sports and Leagues

You would need to get the list of sports from Get Sports operation. If you are interested in particular leagues you can get all sport leagues by calling Get Leagues operation.

Step 3 - Place Bet

To place a bet please check sections How to place a straight bet? and How to place a parlay bet?

Step 4 - Get Bets

To check the status of the placed bet you need to call Get Bets operation. The recommended way is to use bet id.
For bets on live events that are in PENDING_ACCEPTANCE state, you can call Get Bets every 5 sec to get the new status of the bet, to see if it’s accepted or rejected.

How to Place a Straight Bet?

Step 1 – Call Get Fixtures operation

This will return the list of events that are currently offered. To get updates use delta requests (with since parameter)

Step 2 – Call Get Odds operation

This will return the list of odds that are currently offered. To get updates use delta requests (with since parameter)

Step 3 - Get Line (optional)

Call Get Line operation if you need exact limits or if you are interested in a specific line. Please note that the limits in the Get Odds response are general limits.

Step 4 - Place Bet

To place a bet you need to call Place Bet operation.



Table shows how to do mapping of Get Odds operation response to Place Bet and Get Line request.

ParameterGet Odds response parameter
sportId sportId
leagueId League Type -> id
eventId Event Type -> id
periodNumber Period Type -> number
team

Depends on selected odds from:

· Spread Type
· Moneyline Type
· Team Total Points

check the value in the corresponding Get Leagues Response -> League Type -> homeTeamType and set the appropriate value.

Example 1:

Given:
    homeTeamType="Team1"
When:
    Selected odds is Spread Type -> away
Then:
    team=Team2

Example 2:

When:
    Selected odds is Moneyline Type -> draw
Then:
    team=Draw

Example 3:

Given:
    homeTeamType="Team2"
When:
    Selected odds is Team Total Points Type -> away
Then:
    team=Team1

handicap Spread Type -> hdp
Total Points Type -> points
Team Total Points Type -> Total Points Type -> points
lineId Period Type -> lineId
altLineId Spread Type ->altLineId
Total Points Type -> altLineId

If you call Get Line operation, use the lineId (altLineId) from the response.

A period in an event is open for betting if:

1. Get Fixtures Response -> Event Type -> status has a value I or O
2. Event period has odds in Get Odds Response
3. Get Odds Response -> Period Type -> cutoff is in the future.

Please note that for live events, odds change quite frequently as well as the event status, from O/I to H and vice versa. Due to these frequent changes, it’s possible that you will be getting status NOT_EXISTS in the Get Line response more often than for the dead ball events.

How to Place a Parlay Bet?

Step 1 – Call Get Fixtures operation
This will return the list of events that are currently offered. To get updates use delta requests (with since parameter)
 
Step 2 – Call Get Odds operation
This will return the list of odds that are currently offered. To get updates use delta requests (with since parameter)
 
Step 3 – Call Get Parlay Lines operation
For each event and bet type you want to bet on, construct a Leg object for Get Parlay Lines call and submit your request using

POST /line/parlay

If response contains Invalid Legs – remove them and resubmit the request
If response have status = ‘VALID’ – place parlay bet request can be created
 
Step 4 – Call Place Parlay Bet
Construct a list of legs using lineId values from Get Parlay Lines response and specify roundRobbinOptions out of those retuned in Get Parlay Lines response.

How to Place a Teaser Bet?

Step 1 – call Get Teaser Groups operation
This will return the list of teasers by group containing all the details for each teaser. For example; the minimum/maximum number of legs, payout combinations for the chosen teaser and leagues for each teaser.

Step 2 – call Get Teaser Odds operation
This will return the list of adjusted points that are currently offered for the given teaser.
 
Step 3 – Optionally; call Get Teaser Lines operation
Prior to submitting a teaser bet you can call this endpoint to validate your proposed bet, calculate the effective minimum/maximum win/risk bet limits and as well as get the price you will receive for the bet without actaully placing a bet.

Step 4 – call Place Teaser Bet operation
Using the information obtained from the previous steps; build and place your bet.


How to Place a Special Bet?

Step 1 – call Get Special Fixtures operation
This will return the list of specials that are currently offered. To get updates use delta requests (with since parameter)

Step 2 – call Get Special Odds operation
This will return the list of special odds that are currently offered. To get updates use delta requests (with since parameter)
 
Step 3 – Optionally; call Get Special Lines operation
Prior to submitting a special bet you can call this endpoint to validate your proposed bet, calculate the effective minimum/maximum win/risk bet limits and as well as get the price you will receive for the bet without actaully placing a bet.

Step 4 – call Place Special Bet operation
Using the information obtained from the previous steps; build and place your bet.

API Reference

Lines API
Bets API
Customer API

FAQs

Please check our fair use policy

Please ensure that any links back to www.pinnacle.com are tagged with your tracking link. Your tracking links are available from your affiliate account accessed at http://affiliates.pinnacle.com

A correct tracking link will have the format:

http://affiliates.pinnacle.com/processing/clickthrgh.asp?btag=a_numbersb_numbers

All feed command requests that have the same parameters (e.g. same client ID/API key/sport ID) are cached for one minute.

Yes. To link directly to our odds pages please get in touch via customerservice@pinnacle.com

Get Sports and Get Leagues operations have hasOfferings property that indicates availability of the markets.

We use exchange rates provided by oanda.com which we update every 24 hours. Please note that for non-USD currencies, we round them to the largest integer less than or equal to the specified decimal number resulting from currency conversion. For example, a maximum bet amount of £345.23 would be rounded down to £345.

All times displayed in the feed are in GMT.

Please use Get Settled Fixtures to find out if the event's period was settled or the event was deleted.

             1)   Call the snapshot /odds ( without the since parameter) – this would return cached odds snapshot

             2)   Call the delta  /odds  (with the since parameter from the snapshot response) , to get all the changes since the snapshot.

   Delta response has only changed periods, with all the markets that are currently offered. For example if we offer period 0 and period 1 odds on an event and there was a change in one of the markets in period 1 – the delta call will have only period 1 with all the markets that we currently offer, not just the changed markets, and the period 0 will not be in the delta response.

Example:

1) Snapshot has period 1 and period 0 , and both off them have moneyline and spreads odds.
2) Delta call returns just period 1 with the same moneyline and totals

=> this mean that the period 0 did not have any changes and on the period 1 the spread is not offered anymore while the totals are offered now.

Affiliates

How do I get access to the API as an affiliate?

In order to access the API as an affiliate, you are required to send 5 new funded sign ups over the previous 3 months. If you are unable to refer 5 new funded sign ups over the previous 3 month period access to the API may be rescinded.

Fair Use

This API is protected by copyright laws and  is provided free of charge to our players, partners and affiliates only.

The use of this free resource is subject to our "Fair Use Policy" which is set out below.

When you utilise the API, you are agreeing to this policy. Any breaches of this policy, whether intentional or not, may result in a temporary or permanent suspension of your access without notice at our sole discretion.

 

Fair usage

The API is provided to players to facilitate wagering and may not be used for data gathering, scrapping or any other purpose. The API usage must be proportionate to wagering activities as determined on a case by case basis by Pinnacle.

Unless explicitly agreed in writing by Pinnacle, the commercial usage of the API will lead to the permanent suspension of your access.

You will not attempt or encourage others to:

Sell, rent, lease, sublicense, redistribute, or syndicate the API to any third party without prior written approval from Pinnacle.

The following limitations must be observed per sport:

 

Best practice

Please use a delta /fixtures and /odds calls (with the since parameter) calls instead of a snapshot /fixtures and /odds calls (without since parameter).

Disclaimer

Pinnacle is not liable for use of the API for any purpose, the API is provided on an “as is” and “as available” basis, without warranties of any kind, either express or implied, including, without limitation, implied warranties of merchantability, fitness for a particular purpose or non-infringement.

Code Examples



For users of R, please use the pinnacle.API package available on CRAN. (install.packages(“pinnacle.API”)).
The source code can be found here.

API Changelog

October 11th, 2017 - Bets API

Sr. No Summary
1

FEATURENew operation /v2/bets/straight

  • New feature (fillType), give more flexibility to the client when specifying stake amount.
  • When betting on events with live delay, bet id is not in the response. Client has to use uniqueRequestId to check if the bet was accepted or not, by calling v2/bets?uniqueRequestIds={,}. For danger zone live betting, we still return bet id in the response.
  • In case of successful place bet call, we return bet object now.
  • Status NOT_ACCEPTED is introduced as a replacement of REJECTED.

For more details see https://pinnacleapi.github.io/betsapi#operation/Bets_StraightV2

2

FEATURENew operation /v2/bets/straight

Query bets by uniqueRequestId is now supported in /v2/bets only.

For more details see https://pinnacleapi.github.io/betsapi#tag/Get-Bets

3 BUGFIX: Place bet operations return proper error in case of zero stake

4 DECOMMISSIONING/v1/bets/place will be decommissioned January 15th 2018 , please migrate to /v2/bets/straight 
5 DECOMMISSIONING: /v1/bets will be decommissioned January 15th 2018 , please migrate to /v2/bets

Archive - API Release Notes

Date Version
20-Sep-2017 7.12
27-Jul-2017 7.11
19-Jul-2017 7.10
03-May-2017 7.9
13-Dec-2016 7.8
10-Nov-2016 7.7
30-Aug-2016 7.6
21-Jul-2016 7.5



Version 7.12

Sr. No. Summary
1

FEATURE: fixtures/settled now returns Team1ScoreSets and Team2ScoreSets for Tennis

2 FIX: Odds and Fixtures now filters using the EventIds when the LeagueIds are not provided
3 FIX: Translations should now properly handle "+" character from the querystring
4 FIX: v2/leagues now returns "400 - Bad Request" when provided with invalid sportId
5 FIX: Specials: Incorrect contestant prices in '/v1/odds/special'. '/v1/line/special' returns correct price.














Version 7.11

Lines API and Bets API

Sr. No. Summary
1 FEATURESupport Live Delay for Live Soccer Games






Version 7.10

Lines API

Sr. No. Summary
1

FIX: 500 Internal Error on Get Parlay Line

2 FIX: Incorrect Limits for certain customers on Get Line
3 FEATUREAdd league name to the Get Fixtures response








Bets API

Sr. No Summary
1 New operation Get Betting Status
2 isMaxStakeBet, new property in the Place Bet request 
3 updateSequence, new property in the Get Bets response for all bet types.


Version 7.9

Sr. No. Summary
1

IMPROVEMENTPerformance optimizations when querying lines

2 FIX: Parlay odds returning incorrect values
3 FEATURENew Contest Limits calculation










Version 7.8

Sr. No. Summary
1

FEATURE: NEW OPERATION ['/v1/cancellationReasons'] - Get cancellation reasons API call.

2 FEATURE: 'cancellationReason' field added to response for 'v1/bets', 'v1/fixures/settled' and 'v1/fixtures/special/settled' operations.









Version 7.7

Sr. No. Summary
1 FIX: Appropriate HTTP STATUS CODE on error.

Endpoint Scenario Previous Response (HTTP_STATUS) New response (HTTP_STATUS)
v2/leagues Request Invalid  [Error Msg] (200) BAD_REQUEST (400)

v1/currencies

v1/leagues

v1/sports

v2/leagues 

v2/sports

Server encountered error during processing Internal server error (200) INTERNAL_SERVER_ERROR (500)

v1/bets/parlay

v1/fixtures

v1/line/parlay

v1/line/teaser

v1/odds

v1/odds/parlay

v1/odds/teaser

v1/periods

v1/fixtures/special

v1/fixtures/special/settled

Accept header set to application/xml INVALID_REQUEST_DATA (400) ACCEPT_TYPE_NOT_SUPPORTED (406)
2 IMPROVEMENT: Invalid/missing base text for 'v1/translations' now return appropriate error message.
3 FIX: Place Parlay Bet operation now returns 'LineNotAvailable' instead of 'OfflineEvent' message for no longer offered line.
4 FIX: For '/v1/odds/parlay?oddsFormat=Decimal', API now returns odds in requested format for 'Offline' events. It was earlier returning odds in American format for offline games.
5 IMPROVEMENT: For all 500 error responses, where format is json, 'ref' field is returned which contains unique GUID. When contacting Pinnacle support, please include value for this ref field for quick response.
6 FIX: For '/v1/line' calls, handicap is now mandatory irrespective of the casing of the betType parameter value. This doesn't not apply for Moneyline.
7

FUTURE IMPROVEMENT (Planned for December 15th 2016)Output of betId for duplicate UniqueRequestId when placing all types of bets. BetId will be the Id for the previously Accepted bet. For straight and parlay pats the response structure will change as following:


Old Response: Http Status Code 400

           {
                "code": "DUPLICATED_REQUEST",
                "message": "Please use new uniqueRequestId."
           }

 
New Response: Http Status Code 200 
           {
                "status": "PROCESSED_WITH_ERROR",                 "errorCode": "DUPLICATED_REQUEST",
               "betId": 481392270,
                "uniqueRequestId": "dff9d834-87c4-46c7-8232-06a4dceff9dd"
           }
 

For API client developers: Please implement handling for both old and new formats so your code will handle the transition period correctly.









































































Version 7.6

Sr. No. Summary
1 BUG: API returns XML on /odds and /fixtures when ContentType header value is XML and Accept header is not specified
2 FEATURE: Add eventId filter to Get Odds and Get Fixtures  call
3 IMPROVEMENT: Get CANCELLED Bets performance improvement










Version 7.5

Sr. No. Summary
1 Change on the Get Odds behavior. Events and periods will appear in the response as per the matrix:
 
 Event with all periods in the pastEvent with at least one period in the future
Operation/API Version v7.5 v7.4 v7.5 v7.4
Get Odds Snapshot No Yes Yes Yes
Get Odds Delta Yes* Yes Yes* Yes

* GetOdds will return empty period if the cut-off time is in the past, similar to following:

{"periods": [{

    "lineId": 314110088,
    "number": 0,
    "cutoff": "2016-06-22T21:00:00Z"
}]}

2 HTTP status/Response codes adjusted
3 Added eventCount to Get Leagues and Get Sports response
4

Added new operation Get Periods , to return all sport periods

GET /v1/periods?sportid={sportid}

5 PlaceBet (straight) operation returns accepted price (only for ACCEPTED bets)
6 Added more currencies to the Get Currencies response