Add/Drop v2.0
| Add/ | |
| Resource | |
| Add/ | Add/Drop is a transaction where a team drops a player on their current roster and/or picks up a player from the free-agent pool to add to their roster. |
| Change Log | |
| January 15, 2013 | |
| HTTP Methods | |
| GET | Retrieve an add/drop by ID. |
| Exceptions | |
| Following list of exceptions will be returned. | |
| HTTP Methods | |
| POST | Create a new add/drop resource. |
| PUT | Approve, Deny, Update Priority Order |
| Exceptions | |
| Following list of exceptions will be returned. | |
| HTTP Methods | |
| DELETE | Withdraw or Clear an add/drop. |
| Exceptions | |
| Following list of exceptions will be returned. | |
| Example | |
| Add Albert Pujols | Sample illustrates the user trying to add Albert Pujols (id 223571) and drop Derek Jeter (id 7758) |
| XML field definitions | |
| /add_drop | A container element for an add/drop. |
| /add_drop/@id | The ID of the add/drop. |
| /add_drop/ | A container element for the list of players to be dropped. |
| /add_drop/ | A container element for a player to be dropped. |
| /add_drop/ | The ID of the player. |
| /add_drop/ | The first name of the player. |
| /add_drop/ | An abbreviation for the player’s primary position. |
| /add_drop/ | The last name of the player. |
| /add_drop/ | Specifies the roster status of the player on the player’s pro team. |
| /add_drop/ | The fully qualified URL for the CBSSports.com profile for a player. |
| /add_drop/ | The full name of the player. |
| /add_drop/ | The professional team that the player plays for, as a team abbreviation. |
| /add_drop/ | The priority of the add/drop. |
| /add_drop/ | The amount bid to perform the add/drop. |
| /add_drop/ | The date on which the add/drop becomes effective, in YYYYMMDD format. |
| /add_drop/ | A container element for the list of players to be added. |
| /add_drop/ | A container element for a player to be added. |
| /add_drop/ | The ID of the player. |
| /add_drop/ | The first name of the player. |
| /add_drop/ | An abbreviation for the player’s primary position. |
| /add_drop/ | The last name of the player. |
| /add_drop/ | Specifies the roster status of the player on the player’s pro team. |
| /add_drop/ | The fully qualified URL for the CBSSports.com profile for a player. |
| /add_drop/ | The full name of the player. |
| /add_drop/ | The professional team that the player plays for, as a team abbreviation. |
| /add_drop/ | |
| /add_drop/ | The time that the add/drop resource was created, in UNIX timestamp format. |
| /add_drop/ | |
| /add_drop/ | A container element for data on the fantasy team performing the add/drop. |
| /add_drop/ | The ID of the fantasy team. |
| /add_drop/ | The URL of the team’s logo. |
| /add_drop/ | An abbreviation of the team’s name, as a string with a maximum length of 10 characters. |
| /add_drop/ | An abbreviation of the team’s name, as a string with a maximum length of 3 characters. |
| /add_drop/ | An abbreviation of the team’s name, as a string with a maximum length of 6 characters. |
| /add_drop/ | The full name for the team. |
Add/Drop
Description
Add/Drop is a transaction where a team drops a player on their current roster and/or picks up a player from the free-agent pool to add to their roster. Based on a league’s add drop policy, an add/drop goes through multiple states. Following describes the different stages of an add/drop for different policies. To find the add/drop policy for the current league, request the Rules resource. The add/drop policy is given in the </rules/transaction/add_drop_policy/value> field.
Add Drop Policy ‘free_for_all’
League uses an add/drop policy that lets owners make immediate add/drops at any time. Players that are dropped do not go on waivers and are available for immediate pickup for the teams in the league. The add/drop goes through immediately without any further approval required from the commissioner.
Add Drop Policy ‘waivers’
League uses an add/drop policy that lets users make claims for players they intend to add to their roster. CBSSports.com then runs an automated process to determine if the claim results in a successful add/drop or is denied. Players that clear waivers by not being picked up by any team during the waiver process either become free agents or remain on the waivers based on the league’s rules. Players that are dropped go to waivers and remain on waivers till either the next waiver run or the number of days a player is supposed to remain on waivers after a drop based on the league’s rules. Players that do clear waivers and become free agents are then available for immediate pickup for all teams.
- Team makes a claim for a player (Add/Drop resource is created and added to pending claims list)
- CBSSports.com runs an automated waivers process to determine if the claim is successful or no.
- If the claim is successful, it is marked as completed with the status of ‘granted’, deleted from the pending list, and added to the completed list.
- If the claim is denied, it is marked as completed with the status of ‘denied’, deleted from the pending list, and added to the completed list.
Add Drop Policy ‘faab_auto’
League uses an add/drop policy that lets users put bids on players they intend to add to their roster. CBSSports.com then runs an automated auction process to determine if the bid results in a successful add/drop or is denied. Players that are dropped never become free agents and there is no immediate pickup in leagues that use faab_auto as their add/drop policy. The only way to add players to the team from the free agent pool is by placing a bid on a player and have the automated process decide what team wins the player. The team with the highest bid on a player wins the player provided the bid passes all the validation.
- Team puts in a bid for a player (Add/Drop resource is created and added to the pending list)
- CBSSports.com runs an automated process to determine if the bid is successful or no
- If the bid is successful, it is marked as completed with the status of ‘won’, deleted from the pending list, and added to the completed list.
- All the other bids by other teams for the same player are marked as completed with the status of ‘lost’, deleted from the pending list, and added to the completed list
Add Drop Policy ‘faab_approve’
League uses an add/drop policy that lets users put bids on players they intend to add to their roster. These bids have to be processed by the league’s commissioner at the time and days of the week of their choosing. Owners are allowed to put bids up until a certain time when the bids lock as determined by the league rules. Once the bids are locked, the commissioner gets notified that there are pending bids to process. Commissioner then uses a tool provided by CBSSports.com within their fantasy league to process each individual bid in the order they need to be processed. The order is determined by the highest overall bid amount amongst all the players that have received bids and the commissioner is presented with the player and all the bids for that player in the order of the bid amounts. The commissioner then picks the winning bid and submits the form. The commissioner is then presented with the next player to auction and so on until there are no more players left to auction. Once the commissioner is finished with processing the pending bids, the bidding process is unlocked for the owners to put their bids in for players until the process locks again determined by the league’s rules. The commissioner can decide to override the winning bid for a player and if they do, it is shown as such on the transaction logs page available for all league owners to see. The commissioner can also pick a lower bid for a player as the winning bid and if they do, it is shown as such on the transaction logs page available for all the league owners to see.
- Team puts in a bid for a player (Add/Drop resouce is created and added to the pending list)
- Bids lock at a fixed time and day for the commissioner to proces them
- Commissioner is notified to process pending bids via the league’s message center and also on the league’s add drop page.
- Commissioner uses the tool available on CBSSports.com to process bids
- Commissioner processes all the bids in an order and unlocks the bidding process when there are no more players to auction.
- Winning Bids are marked as completed with the status of ‘won’, deleted from the pending list, and added to the completed list.
- All the other bids by other teams for the same player are marked as completed with the status of ‘lost’, deleted from the pending list, and added to the completed list.
- Commissioner can also ‘reject’ all the bids for a given player. In such case, all the bids for a player are marked as ‘lost’, deleted from pending list, and added to the completed list.
Add Drop Policy ‘approve’
League uses an add/drop policy that lets users put in claims for players they intend to add to their roster. The league’s commissioner is notified of a pending claim and the commissioner either approves the claim or denies it. Players that are dropped never become available for immediate pickup. The only way to add a player from the free-agent pool to a team’s roster is by making a claim for a player and the commissioner approving it.
- Team puts in a claim for a player (Add/Drop resource is created and added to the pending list)
- Commissioner is notified of the pending claim
- Commissioner uses tools provided by CBSSports.com within the league to approve/deny the pending claim
- If the claim is approved, it is marked as completed with the status of ‘granted’, deleted from the pending list, and added to the completed list
- If the claim is denied, it is marked as completed with the status of ‘denied’, deleted from the pending list, and added to the completed list
Add Drop Policy ‘none’
League doesn’t use an add/drop policy and owners are restricted from making add/drops
GET
Retrieve an add/drop by ID. The following conditions have to be met for a user to be able to retrieve the add/drop
- Add/Drop with the given id needs to exist either in the pending list or completed list
- User’s team has to be the team that made the claim/bid
- User is the commissioner of the league and the add/drop is awaiting his approval
If a request is made for an add/drop and if the above conditions are not met, a HTTP Status COde 400 is returned and the HTTP Response Body containing the error message.
URL
http://api.cbssports.com
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 add/drop to get. You can get a list of add/drops by requesting the Add/Drops resource. The Add/Drop ID is in the </add-drops/add-drop/@id> field. When you create a new add/drop, the add/drop ID for that add/drop is returned in the </add-drop/@id> field. |
Following list of exceptions will be returned.
- type: required_parameter, msg: Missing required param: id
- type: invalid_id, msg: No Transaction Found with id <id>
- type: no_access, msg: User does not have access to view this add drop
- 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_transaction, msg: User trying to offer trade on someone else’s behalf
- type: invalid_transaction, msg: Transactions are currently locked
- type: invalid_transaction, msg: Missing Offered By Team
- type: invalid_transaction, msg: Missing Offered To Team
- type: invalid_transaction, msg: Invalid Team ID <team_id>
- type: invalid_transaction, msg: Trades are disabled for <owner_name>
- type: invalid_transaction, msg: All owners of team the trade is being offered are disabled from making trades
- type: invalid_transaction, msg: Missing Players
- type: invalid_transaction, msg: Bad Trade : <player_name> is not on <team_name>
- type: invalid_transaction, msg: Your league’s trade deadline of <trade_deadline> has already passed
- type: invalid_transaction, msg: <player_name> is currently locked
- type: invalid_transaction, msg: <player_name> and <player_name> are currently locked
- type: invalid_transaction, msg: <player_name>, <player_name> and <player_name> are currently locked
POST
Create a new add/drop resource. Depending on the league’s add/drop policy, the add/drop is
- Executed immediately for league’s using an add/drop policy ‘free_for_all’ or ‘waivers’ and if the player is a free agent and HTTP Status Code 204 is returned
- Added to the pending list as a claim, a bid or an add/drop waiting commissioner’s approval. HTTP Status Code 201 is returned with the HTTP Response Body containing the resource
- Not created if validation failed and HTTP Status Code 400 is returned with the HTTP Response Body containing the error message.
URL
http://api.cbssports.com
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. |
POST Data
To be sent as payload=JSON
payload={ "add_player_id": "<add_player_id>", "drop_player_id": "<drop_player_id>", "state": "<state>", "team": "<team_id>", "add_pos": "<position>", "faab_bid_amount": "<faab_bid_amount>" }where
- <add_player_id> = (optional in case the team is just trying to drop a player) ID of the player the team wants to add
- <drop_player_id> = (optional) ID of a player the team wants to drop
- <state> = (optional) ‘pending’ if the league uses ‘waivers’, the player is a free agent, but the team still wants to have this add/drop be processed when the automated Waivers process runs
- <team> = (optional - defaults to the user’s team identified in the access_token) ID of the fantasy team trying to make this add/drop.
- <add_pos> = (optional - defaults to the add_player_id’s primary position) Position at which to add the player to the roster in case player is eligible at multiple positions.
- <faab_bid_amount> = (optional - only applies to ‘faab_auto’ and ‘faab_approve’ policies - Bid amount in US Dollars for the player to add.
PUT
Approve, Deny, Update Priority Order
Waivers Claims are processed in the order a user has priortized their pending claims. By default, the priorities are set on the order in which the claims were created with the earliest one being the first priority and so on. Users can change the priority of their pending claims by using this method.
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. |
Following list of exceptions will be returned.
- type: invalid_direction, msg: Invalid Direction <direction>
- type: move_error, msg: Transaction ID Missing
- type: move_error, msg: Move Direction Missing
- type: move_error, msg: User doesn’t have permission to move this transaction
- type: invalid_commish_action, msg: Invalid Commissioner Action <state>
- type: invalid_id, msg: No Add/Drop found with id <id>
- type: invalid_actions, 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_transaction, msg: User trying to offer trade on someone else’s behalf
- type: invalid_transaction, msg: Transactions are currently locked
- type: invalid_transaction, msg: Missing Offered By Team
- type: invalid_transaction, msg: Missing Offered To Team
- type: invalid_transaction, msg: Invalid Team ID <team_id>
- type: invalid_transaction, msg: Trades are disabled for <owner_name>
- type: invalid_transaction, msg: All owners of team the trade is being offered are disabled from making trades
- type: invalid_transaction, msg: Missing Players
- type: invalid_transaction, msg: Bad Trade : <player_name> is not on <team_name>
- type: invalid_transaction, msg: Your league’s trade deadline of <trade_deadline> has already passed
- type: invalid_transaction, msg: <player_name> is currently locked
- type: invalid_transaction, msg: <player_name> and <player_name> are currently locked
- type: invalid_transaction, msg: <player_name>, <player_name> and <player_name> are currently locked
URL
http://api.cbssports.com
PUT Data
To be sent as payload=JSON
To Update Priority of a pending claim
payload={"id": "<id>", "action": "move", "direction": "<direction>"}where
- <id> = ID of the pending add/drop
- <action> = ‘move’
- <direction> = ‘up’ to move a pending claim to one slot higher priority, ‘down’ to move a pending claim to one slot lower priority.
To Approve/Deny a pending claim as a commissioner
payload={"id": "<id>", "action": "commissioner_action", "state": "<state>"}where
- <id> - ID of the pending add/drop
- <action> - ‘commissioner_action’
- <state> - ‘approve’ to approve the claim, ‘reject’ to deny the claim.
Note: A user has to be a commissioner to approve/deny the claim. If a non commissioner user tries to approve/deny a claim, a HTTP Status Code 400 is returned with the HTTP Response Body containing the error message denoting that the user is not a commissioner.
DELETE
Withdraw or Clear an add/drop. Users can withdraw pending claims before they get processed. A completed claim can be ‘cleared’ from the completed list by the user. Both these actions result in deletion of the resource.
URL
http://api.cbssports.com
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 | (required) ID of the transaction to withdraw/clear |
Add Albert Pujols
Sample illustrates the user trying to add Albert Pujols (id 223571) and drop Derek Jeter (id 7758)
Sample URL
POST http://api.cbssports.com/fantasy/league/transactions/add-drop?version=2.0
POST Data
payload={ "add_player_id": "223571", "drop_player_id": "7758", "state": "drop", "team": "15", "add_pos": "1B", "faab_bid_amount": "24" }XML Response
Immediate Pickup: HTTP Status Code 204 with no body Invalid Add/Drop (Failed Validation): HTTP Status Code 400 with error message Pending Add/Drop:
<?xml version="1.0"?>
<result uriAlias="/league/transactions/add-drop" uri="/league/transactions/add-drop" statusCode="200" statusMessage="OK">
<body>
<add_drop id="1326689794.15">
<drop_players>
<drop_player id="7758">
<firstname>Derek</firstname>
<position>SS</position>
<lastname>Jeter</lastname>
<pro_status>A</pro_status>
<profile_url>/players/playerpage/7758</profile_url>
<fullname>Derek Jeter</fullname>
<pro_team>NYY</pro_team>
</drop_player>
</drop_players>
<priority>1</priority>
<bid_amount>24</bid_amount>
<effective_point>20120328</effective_point>
<add_players>
<add_player id="223571">
<firstname>Albert</firstname>
<position>1B</position>
<lastname>Pujols</lastname>
<pro_status>A</pro_status>
<profile_url>/players/playerpage/223571</profile_url>
<fullname>Albert Pujols</fullname>
<pro_team>LAA</pro_team>
</add_player>
</add_players>
<state>claim</state>
<timestamp>1326689794</timestamp>
<action>drop</action>
<team id="15">
<logo>Team Logo URL</logo>
<long_abbr>Stun</long_abbr>
<abbr>Stu</abbr>
<short_name>Stunne</short_name>
<name>Stunners</name>
</team>
</add_drop>
</body>
</result>JSON Response
Immediate Pickup: HTTP Status Code 204 with no body Invalid Add/Drop (Failed Validation): HTTP Status code 400 with error message Pending Add/Drop:
{
"body" : {
"add_drop" : {
"drop_players" : [
{
"firstname" : "Derek",
"position" : "SS",
"lastname" : "Jeter",
"pro_status" : "A",
"profile_url" : "/players/playerpage/7758",
"fullname" : "Derek Jeter",
"id" : "7758",
"pro_team" : "NYY"
}
],
"priority" : 1,
"bid_amount" : 24,
"effective_point" : "20120328",
"add_players" : [
{
"firstname" : "Albert",
"position" : "1B",
"lastname" : "Pujols",
"pro_status" : "A",
"profile_url" : "/players/playerpage/223571",
"fullname" : "Albert Pujols",
"id" : "223571",
"pro_team" : "LAA"
}
],
"state" : "claim",
"timestamp" : "1326689794",
"action" : "drop",
"team" : {
"logo" : "Team Logo URL",
"long_abbr" : "Stun",
"abbr" : "Stu",
"short_name" : "Stunne",
"name" : "Stunners",
"id" : "15"
}
}
"id" : "1326689794.15"
},
"uriAlias" : "/league/transactions/add-drop",
"statusMessage" : "OK",
"uri" : "/league/transactions/add-drop",
"statusCode" : 200
}/add_drop/drop_players/drop_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.
/add_drop/drop_players/drop_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.
/add_drop/drop_players/drop_player/fullname
The full name of the player. The value is equivlent to the values of /add_drop/drop_players/drop_player/firstname and /add_drop/drop_players/drop_player/lastname joined with a space.
/add_drop/add_players/add_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.
/add_drop/add_players/add_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.
/add_drop/add_players/add_player/fullname
The full name of the player. The value is equivlent to the values of /add_drop/add_players/add_player/firstname and /add_drop/add_players/add_player/lastname joined with a space.
/add_drop/team/@id
The ID of the fantasy team. To get a list of fantasy team IDs, request the Fantasy Teams resource.
