Trade v2.0

Summary

Trade
Resource
Trade	Trade is a transaction between two teams where an exchange of players is done.
Change Log
January 15, 2013
HTTP Methods
GET	Retrieve a trade by ID.
Exceptions
Following list of exceptions will be returned.
HTTP Methods
POST	Offer a trade to another team in league.
Exceptions
Following list of exceptions will be returned.
HTTP Methods
PUT	Accept, Reject, Withdraw, Vote, Approve, or Disapprove a Trade
Exceptions
Following list of exceptions will be returned.
Following list of exceptions will be returned.
Example
Offer a Trade
XML field definitions
/trade	A container element for data on a particular trade.
/trade/@id	The ID of the trade.
/trade/offered_by_team_id	The ID of the team that offered the trade.
/trade/timestamp	The time that the trade resource was created in UNIX timestamp format.
/trade/teams	A container element for a list of the teams that were parties to trade.
/trade/teams/team	A container element for data on a fantasy team that is party to a trade.
/trade/teams/team/@id	The ID of the fantasy team.
/trade/teams/team/logo	The fully qualified URL of the team’s logo.
/trade/teams/team/long_abbr	An abbreviation of the team’s name, as a string with a maximum length of 10 characters.
/trade/teams/team/abbr	An abbreviation of the team’s name, as a string with a maximum length of 3 characters.
/trade/teams/team/short_name	An abbreviation of the team’s name, as a string with a maximum length of 6 characters.
/trade/teams/team/name	The full name for the team.
/trade/offered_to_teams	Container element for the list of teams that the trade was originally offered to.
/trade/offered_to_teams/offered_to_team	The ID of the team that the trade was offered to.
/trade/players	A container element for a list of the players involved in the trade.
/trade/players/player	A container element for the data on one of the players involved in the trade.
/trade/players/player/@id	The ID of the player.
/trade/players/player/roster_status	Specifies the player’s roster status on a fantasy team.
/trade/players/player/position	An abbreviation for the player’s primary position.
/trade/players/player/firstname	The first name of the player.
/trade/players/player/lastname	The last name of the player.
/trade/players/player/fullname	The full name of the player.
/trade/players/player/from_team_id	The ID of the fantasy team that the player was traded from.
/trade/players/player/to_team_id	The ID of the fantasy team that the player was traded to.
/trade/players/player/pro_team	The professional team that the player plays for, as a team abbreviation.
/trade/state

Resource

Trade

Description

Trade is a transaction between two teams where an exchange of players is done. Based on the fantasy league’s trade policy, a trade goes through multiple stages. Following describes the different states of a trade for different trade policies. To find the trade policy for the current league, request the Rules resource. The trade policy is given in the /rules/transactions/trade_policy/value field.

Trade Policy ‘free_for_all’

League uses a trade policy that doesn’t require any further approval or a vote once the trade is agreed upon by both teams. Following are the different states of a trade.

Team A offers a trade to Team B
Team A can withdraw the trade offer at any time as long as Team B hasn’t taken any action on the trade.
Team B either accepts or rejects trade offer. If Team B accepts the offer, the trade is executed and players are transferred to their new teams without any further delay. If Team B rejects the offer, the trade is deleted without any further action.

Trade Policy ‘vote’

League uses a trade policy that requires all the league members not involved in the trade to vote either in favor of or against the trade by the trade voting deadline as defined by league rules once the trade is agreed upon by both teams. If the number of votes against the trade reaches the number of rejections required to reject a trade (as defined by the league rules), the trade is disapproved and deleted without any further notice. Following are the different states for a trade.

Team A offers a trade to Team B
Team A can withdraw the trade offer at any time as long as team B hasn’t taken any action on the trade.
Team B either accepts or rejects the trade offer. If Team B rejects the offer, the trade is deleted without any further action. If Team B accepts the offer, the trade is put up for a vote to the rest of the fantasy league members.
League Members vote for or against the trade by the trade voting deadline. Once the deadline has passed, all the votes are added up and if the number of votes against the trade meets the number of rejections required to reject a trade, the trade is rejected and deleted with no further action. If there aren’t enough votes against the trade to reject it, the trade is executed and players are transferred to their new teams completing the trade.

Trade Policy ‘approve’

League uses a trade policy that requires the commissioner to approve all the trades that have been agreed upon by the two teams involved. Once a trade is offered and accepted by two teams, it goes to the commissioner for final approval. If the commissioner approves the trade, it is executed and players are transfered to their new teams completing the trade. If a commissioner disapproves a trade, the trade is rejected and deleted without further action. Following are the different states for a trade.

Team A offers a trade to Team B
Team A can withdraw the trade offer at any time as long as team B hasn’t taken any action on the trade.
Team B either accepts or rejects the trade offer. If Team B rejects the offer, the trade is deleted without any further action. If Team B accepts the offer, the trade is sent to the commissioner for approval.
If commissioner approves the trade, it is executed and players are transferred to their new teams. If a commissioner disapproves the trade, the trade is deleted with no further action.

Change Log

January 15, 2013

Added exception handling.

HTTP Methods

GET

Retrieve a trade by ID. The following conditions have to be met for a user to be able to retrieve a trade.

User’s team is part of the trade as either the team that offered the trade of the team that the trade was offered to
User is the commissioner of the league and the trade is awaiting his approval
Trade has been accepted and is awaiting user’s vote

URL

http://api.cbssports.com/fantasy/league/transactions/trade?version=2.0

Parameters

response_format	(optional) Specifies the format in which the requested resource should be returned. Valid values are XML and JSON. The default is XML.
id	The ID of the trade to get. You can get a list of trades by requesting the Trades resource. The trade ID is in the /trades/trade/@id field. When you creat a new trade, the trade ID for that trade is returned in the /trade/@id field.

Exceptions

Following list of exceptions will be returned.

type: required_parameter, msg: Missing required param: id
type: invalid_trade_id, msg: No Trade Found with id <trade_id>

HTTP Methods

POST

Offer a trade to another team in league.

URL

http://api.cbssports.com/fantasy/league/transactions/trade?version=2.0

Parameters

response_format

(optional) Specifies the format in which the requested resource should be returned. Valid values are XML and JSON. The default is XML.

Exceptions

Following list of exceptions will be returned.

type: same_player_trade, msg: Trying to offer same player to different teams
type: same_draft_pick, msg: Trying to offer same draft pick to different teams
type: invalid_execute_immediately, msg: User is not a commissioner
type: invalid_offer, msg: User trying to offer trade on someone else’s behalf

POST Data

To be sent as payload=JSON

payload={ "team_to": "<team_to_id>", "team_from": "<team_from_id>", "players": [ "<player_id>:<current_team_id>:<new_team_id>", "<player_id>:<current_team_id>:<new_team_id>" ], "comment": "<comment>" }

where

<team_to_id> = ID of the fantasy team the trade is being offered to
<from_from_id> = ID of the fantasy team that is offering the trade
<player_id> = ID of the player that is part of the trade
<current_team_id> = ID of the fantasy team the player is currently on
<new_team_id> = ID of the fantasy team the player will end up on after the trade
<comment> = Any comment the team that is offering the trade wants to be included in the trade

HTTP Methods

PUT

Accept, Reject, Withdraw, Vote, Approve, or Disapprove a Trade

Exceptions

Following list of exceptions will be returned.

type: same_player_trade, msg: Trying to offer same player to different teams
type: same_draft_pick, msg: Trying to offer same draft pick to different teams
type: invalid_execute_immediately, msg: User is not a commissioner
type: invalid_offer, msg: User trying to offer trade on someone else’s behalf
type: invalid_offer, msg: Transactions are currently locked
type: invalid_offer, msg: Missing Offered By Team
type: invalid_offer, msg: Missing Offered To Team
type: invalid_offer, msg: Invalid Team ID <team_id>
type: invalid_offer, msg: Trades are disabled for <owner_name>
type: invalid_offer, msg: All owners of team the trade is being offered are disabled from making trades
type: invalid_offer, msg: Missing Players
type: invalid_offer, msg: Bad Trade : <player_name> is not on <team_name>
type: invalid_offer, msg: Your league’s trade deadline of <trade_deadline> has already passed
type: invalid_offer, msg: <player_name> is currently locked
type: invalid_offer, msg: <player_name> and <player_name> are currently locked
type: invalid_offer, msg: <player_name>, <player_name> and <player_name> are currently locked

URL

http://api.cbssports.com/fantasy/league/transactions/trade?version=2.0

PUT Data

To be sent as payload=JSON

payload={"id": "<id>", "action": "<action>"}

where

<id> = ID of the trade
<action> = ‘withdraw’ to withdraw a trade
<action> = ‘reject’ to reject a trade
<action> = ‘accept’ to accept a trade
<action> = ‘approve’ to vote for the trade
<action> = ‘object’ to vote against the trade
<action> = ‘commissioner_approve’ to approve the trade as a Commissioner of the league
<action> = ‘commissioner_reject’ to disapprove the trade as a Commissioner of the league

Note: User has to be the commissioner of the league to ‘commissioner_approve’ and ‘commissioner_reject’ the trade.

Following list of exceptions will be returned.

type: invalid_action, msg: Invalid Action <action>
type: invalid_trade, msg: Invalid Action <action>
type: same_player_trade, msg: Trying to offer same player to different teams
type: same_draft_pick, msg: Trying to offer same draft pick to different teams
type: invalid_execute_immediately, msg: User is not a commissioner
type: invalid_offer, msg: User trying to offer trade on someone else’s behalf
type: invalid_offer, msg: Transactions are currently locked
type: invalid_offer, msg: Missing Offered By Team
type: invalid_offer, msg: Missing Offered To Team
type: invalid_offer, msg: Invalid Team ID <team_id>
type: invalid_offer, msg: Trades are disabled for <owner_name>
type: invalid_offer, msg: All owners of team the trade is being offered are disabled from making trades
type: invalid_offer, msg: Missing Players
type: invalid_offer, msg: Bad Trade : <player_name> is not on <team_name>
type: invalid_offer, msg: Your league’s trade deadline of <trade_deadline> has already passed
type: invalid_offer, msg: <player_name> is currently locked
type: invalid_offer, msg: <player_name> and <player_name> are currently locked
type: invalid_offer, msg: <player_name>, <player_name> and <player_name> are currently locked

Example

Offer a Trade

Sample URL

POST http://api.cbssports.com/fantasy/league/transactions/trade?version=2.0

POST Data

payload={"team_to": 23,"team_from": 15, "players":["589256:15:23", "7495:23:15"], "comment": "Trade Offer"}

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<result uriAlias="/league/transactions/trade" uri="/league/transactions/trade" statusCode="200" statusMessage="OK">
    <body>
        <trade id="1319568532.15">
            <offered_by_team_id>15</offered_by_team_id>
            <timestamp>1319568532</timestamp>
            <teams>
                <team id="15">
                    <logo>Team Logo URL</logo>
                    <long_abbr>Team Long Abbreviation</long_abbr>
                    <abbr>Team Long Abbreviation</abbr>
                    <short_name>Team Short Name</short_name>
                    <name>Team Name</name>
                </team>
                <team id="23">
                    <logo>Team Logo URL</logo>
                    <long_abbr>Team Long Abbreviation</long_abbr>
                    <abbr>Team Long Abbreviation</abbr>
                    <short_name>Team Short Name</short_name>
                    <name>Team Name</name>
                </team>
            </teams>
            <offered_to_teams>
                <offered_to_team>23</offered_to_team>
            </offered_to_teams>
            <players>
                <player id="7495">
                    <roster_status>A</roster_status>
                    <position>SP</position>
                    <name>Chris Carpenter</name>
                    <from_team_id>23</from_team_id>
                    <to_team_id>15</to_team_id>
                    <pro_team>STL</pro_team>
                </player>
                <player id="589256">
                    <roster_status>A</roster_status>
                    <position>SS</position>
                    <name>Troy Tulowitzki</name>
                    <from_team_id>15</from_team_id>
                    <to_team_id>23</to_team_id>
                    <pro_team>COL</pro_team>
                </player>
            </players>
            <state>offer</state>
        </trade>
    </body>
</result>

JSON Response

{
   "body" : {
      "trade" : {
         "offered_by_team_id" : 15,
         "timestamp" : "1319568532",
         "teams" : [
            {
               "logo" : "Team Logo URL",
               "long_abbr" : "Team Long Abbreviation",
               "abbr" : "Team Long Abbreviation",
               "short_name" : "Team Short Name",
               "name" : "Team Name",
               "id" : "15"
            },
            {
               "logo" : "Team Logo URL",
               "long_abbr" : "Team Long Abbreviation",
               "abbr" : "Team Long Abbreviation",
               "short_name" : "Team Short Name",
               "name" : "Team Name",
               "id" : "23"
            }
         ],
         "offered_to_teams" : [
            23
         ],
         "players" : [
            {
               "roster_status" : "A",
               "position" : "SP",
               "name" : "Chris Carpenter",
               "id" : "7495",
               "from_team_id" : "23",
               "to_team_id" : "15",
               "pro_team" : "STL"
            },
            {
               "roster_status" : "A",
               "position" : "SS",
               "name" : "Troy Tulowitzki",
               "id" : "589256",
               "from_team_id" : "15",
               "to_team_id" : "23",
               "pro_team" : "COL"
            }
         ],
         "id" : "1319568532.15",
         "state" : "offer"
      }
   },
   "uriAlias" : "/league/transactions/trade",
   "statusMessage" : "OK",
   "uri" : "/league/transactions/trade",
   "statusCode" : 200
}

XML field definitions

/trade

A container element for data on a particular trade.

/trade/@id

The ID of the trade.

/trade/offered_by_team_id

The ID of the team that offered the trade. This ID also indicates which of the teams that are party to the trade was the team that offered the trade. Thus this ID will always correspond to one of the values of /trade/teams/team/@id for the current trade. You can get a list of the fantasy team IDs by requesting the Fantasy Teams resource.

/trade/timestamp

The time that the trade resource was created in UNIX timestamp format.

/trade/teams

A container element for a list of the teams that were parties to trade.

/trade/teams/team

A container element for data on a fantasy team that is party to a trade.

/trade/teams/team/@id

The ID of the fantasy team. To determine if this team is the party who offered the trade or the party it was offered to, you can compare this ID to the value of /trade/offered_by_team_id or to each of the values of /trade/offered_to_teams/offered_to_team. To get a list of fantasy team IDs, request the Fantasy Teams resource.

/trade/teams/team/logo

The fully qualified URL of the team’s logo. You can use this URL to display the team logo.

/trade/teams/team/long_abbr

An abbreviation of the team’s name, as a string with a maximum length of 10 characters.

/trade/teams/team/abbr

An abbreviation of the team’s name, as a string with a maximum length of 3 characters.

/trade/teams/team/short_name

An abbreviation of the team’s name, as a string with a maximum length of 6 characters.

/trade/teams/team/name

The full name for the team.

/trade/offered_to_teams

Container element for the list of teams that the trade was originally offered to.

/trade/offered_to_teams/offered_to_team

The ID of the team that the trade was offered to. This ID will always correspond to one of the values of /trade/teams/team/@id for the current trade. To get a list of fantasy team IDs, request the Fantasy Teams resource.

/trade/players

A container element for a list of the players involved in the trade.

/trade/players/player

A container element for the data on one of the players involved in the trade.

/trade/players/player/@id

The ID of the player. You can use this ID to get more information about the player by requesting the Player Outlook resource or the Player Updates resource.

/trade/players/player/roster_status

Specifies the player’s roster status on a fantasy team. Possible values are A (Active), RS (Reserve), I (Injured), ML (Minors), and PR (Practice Squad -- football only)

/trade/players/player/position

An abbreviation for the player’s primary position. You can get a list of the abbreviations and their expansions by requesting the Positions resource.

/trade/players/player/firstname

The first name of the player.

/trade/players/player/lastname

The last name of the player.

/trade/players/player/fullname

The full name of the player. The value is equivlent to the values of /trade/players/player/firstname and /trade/players/player/lastname joined with a space.

/trade/players/player/from_team_id

The ID of the fantasy team that the player was traded from. This ID will correspond to the the ID of the fantasy team in /trade/teams/team/@id. To get a list of fantasy team IDs, request the Fantasy Teams resource.

/trade/players/player/to_team_id

The ID of the fantasy team that the player was traded to. This ID will correspond to the the ID of the fantasy team in /trade/teams/team/@id. To get a list of fantasy team IDs, request the Fantasy Teams resource.

/trade/players/player/pro_team

The professional team that the player plays for, as a team abbreviation.

/trade/state

The current state of the trade. Possible values and their meanings are

offer	The trade has been offered but not accepted.
vote	The trade has been accepted and is in the voting period (only exists in leagues that use a trade policy that requires all the league members not involved in the trade to vote either in favor of or against the trade by the trade voting deadline as defined by league rules once the trade is agreed upon by both teams.)
approve	Pending trade awaiting commissioner approval/rejetion

Specifies the method by which trades are done.

The ID of the trade.

The ID of the fantasy team.

The ID of the team that offered the trade.

The ID of the team that the trade was offered to.

The first name of the player.

The last name of the player.