API에 대한 피드백은 Kor.help@pinnacle.com으로 보내 주시기 바랍니다. 단, 당사는 기존 매뉴얼 이외의 기술 지원이나 지침은 제공하지 않습니다.

Pinnacle API Specification v1.0
(updated: 2018-1-15)

API Reference

Lines API
Bets API
Customer API

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 signups from the previous 3 months. If you are unable to refer 5 new funded signups from the previous 3-month period, access to the API may be rescinded.

Last Updated

15 Jan 2018 - Added Changelog for 21 Dec 2017 and 04 Jan 2018 releases.
22 Dec 2017 - Added new "Betting on Events with Live Delay" to the "Getting Started" section.

Overview

Pinnacle API is a RESTful service for straight, special, parlays 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

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

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

Date Time Format

All dates and times are in GMT 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 the 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 to avoid 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 for 30 min. If you try again within that time range to place a bet with the same uniqueRequestId, you will get the appropriate error.

All place bet requests support deduplication.

Authentication

The API uses 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”>
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 the 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 betId.
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, if 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 has 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, as well as get the price you will receive for the bet without actually 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, as well as get the price you will receive for the bet without actually placing a bet.

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

Betting on Events with Live Delay

Bets placed on events with live delay are treated differently than other bets. They get betId assigned only once they are ACCEPTED.


The only way to find out the status of such a bet is by querying Get Bets V2 by uniqueRequestIds:

/v2/bets?uniqueRequestIds=86a90ab9-fca1-4703-a11c-ce329a85584e


As long as the bet is in PENDING_ACCEPTANCE, the response would be:

{
    "straightBets": [
        {
            "uniqueRequestId": "86a90ab9-fca1-4703-a11c-ce329a85584e",
            "betStatus": " PENDING_ACCEPTANCE"
        }
    ]
}


NOTE: Status can change from PENDING_ACCEPTANCE to NOT_ACCEPTED or ACCEPTED


If the bet was
NOT_ACCEPTED, the response would be:

{
    "straightBets": [
        {
            "uniqueRequestId": "86a90ab9-fca1-4703-a11c-ce329a85584e",
            "betStatus": "NOT_ACCEPTED"
        }
    ]
}


If the bet was ACCEPTED, the response includes the full bet details:

{
    "straightBets": [
        {
            "betId": 800110193,
            "uniqueRequestId": "86a90ab9-fca1-4703-a11c-ce329a85584e",
            "wagerNumber": 1,
            "placedAt": "2017-12-20T21:57:22Z",
            "betStatus": "ACCEPTED",
            "betType": "MONEYLINE",
            "win": 2519.25,
            "risk": 11991.63,
            "oddsFormat": "AMERICAN",
            "updateSequence": 175277412,
            "sportId": 29,
            "leagueId": 5595,
            "eventId": 799939900,
            "price": -476,
            "teamName": "Universitario",
            "team1": "Universitario",
            "team2": "Club Petrolero",
            "periodNumber": 0,
            "isLive": "TRUE"
        }
    ]
}

We apply live delay of around 6 seconds, so the first call to Get Bets V2 should be 6 seconds after placing a bet.

30 minutes after placing a bet, we will stop returning a response for provided uniqueRequestId. This is due to cache cleanup to maintain optimal performance.

Please also note that the RUNNING bet list does not return any live delay bets that are PENDING_ACCEPTANCE or NOT_ACCEPTED.

FAQ

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 60 seconds.

Yes. To link directly to our odds pages, please contact customerservice@pinnacle.com

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

We follow oanda.com, and update our exchange rates 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.

In the feed, all times displayed are GMT.

Please use Get Settled Fixtures to find out if the event's period was settled or if 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 of them have moneyline and spreads odds.
    2) Delta call returns just period 1 with the same moneyline and totals
 => This means 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.

Fair Use Policy

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

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

Use of the API constitutes your agreement to this policy. You understand and agree that at our sole discretion, and without prior notice, we may block access to our site if we believe that your use of our site has violated or is inconsistent with this Fair Use Policy.

We may at any time, and at our sole discretion, modify this Fair Use Policy, with or without prior notice. Any such modification will be effective immediately upon public posting. Your continued use of our APIs and this site following such modification constitutes your acceptance of the modified terms in this Fair Use Policy.

 

Fair usage

The API is provided to players to facilitate wagering and may not be used for data gathering, scraping or for 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, nor encourage others to:
- interfere with, disrupt, or disable any API features;
- use the API for commercial purposes without a written agreement with Pinnacle;
- 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:

- Requests made for the /fixtures and /odds operation without the since parameter must be restricted to once every 60 seconds;
- Requests made for the /fixtures and /odds operation with the since parameter must be restricted to once every 5 seconds.

 

Best practice

Please use a delta /fixtures and /odds calls (with the since parameter) 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 expressed or implied, including, without limitation, implied warranties of merchantability and 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

January 04, 2018 - Lines API

Sr. No. Summary
1 Fix: v1/odds/special - When contestant line is no longer offered, delta calls on API should return contestant lline with null price
2 Fix: v1/line/special - API incorrectly returns successful response for offline events and when wager cutoff is in the past
3 Fix: /v1/line/special returns {"status": "OFFLINE"} when a contestant line is not offered (price = null)
4 Fix: v1/fixtures/settled for Tennis sometimes returns negative value for team1ScoreSets and team2ScoreSets fields



December 21, 2017 - Lines API

Sr. No. Summary
1 FIX: /v1/fixtures/special - eventId filtering not working



October 11, 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 betId 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 FEATURE: New operation Get Betting Status
2 FEATURE: isMaxStakeBet, new property in the Place Bet request 
3 FEATURE: 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 a line that is no longer offered.
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 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 bets, the response structure will change as follows:


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 correctly handle the transition period.


































































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 IMPROVEMENT: 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 cutoff time is in the past, similar to following:

{"periods": [{

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

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

FEATURE: Added new operation Get Periods, to return all sport periods

GET /v1/periods?sportid={sportid}

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