Team Cowboy

REST API v1.0 Documentation

November 18, 2013 (Revision 8.12)

 

© 2013 Team Cowboy, LLC. All rights reserved.

 

View Document Revision History

Table of Contents

Introduction. 5

Overview.. 5

API Accounts. 5

Requesting an API Account 6

Logging. 6

Rate Limiting. 6

API Endpoint URL. 6

HTTP Endpoint URL. 6

HTTPS (Secure) Endpoint URL. 6

API Requests & Responses. 7

Requests. 7

Required Parameters. 7

Optional Parameters. 8

Request Signatures. 8

Creating the Concatenated String of Request Name/Value Pairs. 9

Responses. 10

Sample Response with Error (JSON) 11

HTTP/1.1 Status Codes. 11

Response Errors. 11

Error Object Definition.. 12

Error Codes. 12

Methods. 12

Authentication Methods. 13

Auth_GetUserToken.. 13

Event Methods. 13

Event_Get 13

Event_GetAttendanceList 14

Event_SaveRSVP.. 14

Message Methods. 16

Message_Get 16

Message_Delete. 16

Message_Save. 16

MessageComment_Delete. 17

MessageComment_Add. 18

Team Methods. 18

Team_Get 18

Team_GetEvents. 19

Team_GetMessages. 20

Team_GetRoster 21

Team_GetSeasons. 22

Test Methods. 23

Test_GetRequest 23

Test_PostRequest 23

User Methods. 23

User_Get 23

User_GetNextTeamEvent 24

User_GetTeamEvents. 24

User_GetTeamMessages. 25

User_GetTeams. 26

Object Definitions. 27

Activity. 27

Description.. 27

Object Properties. 27

AttendanceList 27

Description.. 27

Object Properties. 27

AttendanceListUserInfo. 29

Description.. 29

Object Properties. 29

ColorSwatch.. 30

Description.. 30

Object Properties. 30

Event 30

Description.. 30

Object Properties. 31

Location.. 34

Description.. 34

Object Properties. 34

LinkedUser 35

Description.. 35

Object Properties. 35

Message. 36

Description.. 36

Object Properties. 36

MessageComment 38

Description.. 38

Object Properties. 38

RSVPInstance. 39

Description.. 39

Object Properties. 39

SaveRSVPResponse. 40

Description.. 40

Object Properties. 41

Season.. 41

Description.. 41

Object Properties. 41

Team.. 42

Description.. 42

Object Properties. 42

TeamMemberType. 45

Description.. 45

Object Properties. 45

TeamType. 46

Description.. 46

Object Properties. 46

User 46

Description.. 46

Object Properties. 47

Document Revision History. 49

November 18, 2013 (Rev 8.12) 49

June 17, 2013 (Rev 8.11) 49

September 27, 2012 (Rev 8.10) 49

June 6, 2012 (Rev 8.00) 49

May 4, 2012 (Rev 7.9) 50

May 4, 2012 (Rev 7.8) 50

April 29, 2012 (Rev 7.7) 50

April 27, 2012 (Rev 7.61) 51

April 27, 2012 (Rev 7.6) 51

April 15, 2012 (Rev 7.51) 51

February 11, 2012 (Rev 7.5) 51

February 3, 2012 (Rev 7.42) 52

February 2, 2012 (Rev 7.41) 52

August 10, 2011 (Rev 7.40) 53

July 29, 2011 (Rev 7.34) 53

July 23, 2011 (Rev 7.33) 53

June 18, 2011 (Rev 7.32) 53

June 14, 2011 (Rev 7.31) 53

June 9, 2011 (Rev 7.3) 54

May 3, 2011 (Rev 7.2) 54

April 25, 2011 (Rev 7.1) 54

March 11, 2011 (Rev 7.0) 54

March 10, 2011 (Rev 6.0) 55

February 15, 2011 (Rev 5.0) 55

February 14, 2011 (Rev 4.0) 55

February 10, 2011 (Rev 3.0) 56

February 3, 2011 (Rev 2.0) 57

January 30, 2011 (Rev 1.0) 57

 

Introduction

The Team Cowboy Application Programming Interface (API) described in this document allows developers to create mobile, desktop, and other software applications that interact with Team Cowboy (http://www.teamcowboy.com). These applications can then leverage Team Cowboy’s extensive functionality for managing and accessing social sports teams and groups.

 

The API is currently available for both personal/non-commercial and commercial use while in the BETA phase. This is subject to change at any time, so development of commercial products against this API should be done at your own risk and a fee may apply in the future to use the Team Cowboy API for a commercial application (i.e., an application that has a purchase cost or collects revenue as part of its normal operation).

 

If you have any questions along the way or find problems with this documentation or the API itself, please contact api@teamcowboy.com.

Overview

The API is comprised of various methods for retrieving, creating, updating, and deleting information for users or teams on Team Cowboy as outlined in the Methods section of this document.

 

To perform an action using the Team Cowboy API, a request is sent with parameters to an API endpoint URL. A response is then sent back to you which you can use to determine success or failure of the request and to take action based on any other information in the response.

API Accounts

To access the Team Cowboy API, you must request an API account. Once an account is created in our system, you will receive a public API key and private API key pair. You should use a separate API account for each application or purpose for accessing the Team Cowboy API. For example, if you create a Team Cowboy mobile application for three different platforms, you should have three separate API accounts.

 

All requests must include your public API key. Your private API key should NEVER be transmitted in clear text on any request whatsoever. It is instead used to sign API requests. Team Cowboy uses the signature you provide in your requests before granting access to information returned from API requests. The request signing process is outlined in detail below.

 

Please note that Team Cowboy reserves the right to rate-limit, disable, or delete API accounts (and associated keys) at any time and without notice. We will of course not generally do this unless we suspect that an account is being abused or has otherwise been compromised.

Requesting an API Account

To request an API Account, please sign into an active Team Cowboy account, then visit https://www.teamcowboy.com/api/requestAccount.

Logging

Team Cowboy logs all requests made against the API.

 

Rate Limiting

Team Cowboy reserves the right to impose rate limiting for your API account at any time. Please use good design when accessing the API and cache any information where possible to ensure your account does not get throttled or disabled completely. API request limits are set high enough for normal use of the API.

API Endpoint URL

The Team Cowboy API can be accessed over HTTP and HTTPS (secure/SSL). Each method listed in the Methods section of this documentation outlines whether the method should be accessed via the regular or secure URL. Attempting to access a method via the regular URL when it requires the secure URL will result in an error.

HTTP Endpoint URL

http://api.teamcowboy.com/v1

 

HTTPS (Secure) Endpoint URL

Please do not send all requests via the secure URL! Instead, use the regular (non-HTTPS) URL for all requests unless the method specifies that the secure URL should be used.

 

https://api.teamcowboy.com/v1

 

API Requests & Responses

Requests

The Team Cowboy API is a RESTful API. All requests to the API are done via either an HTTP GET or an HTTP POST. At this time, the Team Cowboy API does not make use of HTTP PUT or DELETE requests.

Required Parameters

At a minimum, all requests against the Team Cowboy API must include the following five parameters:

 

Parameter Name

Type

Description

api_key

string (40)

This is the public API key granted to you along with your API account.

Example:  b412e0691e179ad12df2a0ff5b8dac2aafb74a3d

method

string

The API method being called. See Methods for a list of supported API methods. This parameter is case-sensitsive, so the method name should be entered exactly as shown in this documentation.

Example:  User_GetTeams

timestamp

integer

The UNIX timestamp (seconds since the Epoch) of your request. The timestamp passed must be within 120 seconds of the Team Cowboy API server or your API request will not be fulfilled. Note that this should be an integer, not a floating point number.

Example: 1296268551

nonce

string

A cryptographic nonce value for your request. This value should be unique for each and every request you make against the API. Although the term “nonce” typically refers to “a number used once”, the API will accept any value >= 8 characters, as long as it’s unique.

Example:  392049284

sig

string (40)

The unique signature for your request. Creating signatures is discussed in the section, Request Signatures

Example:  9c8c2450734baf8b0bf610e4c9688e9c5faf233f

 

These parameters are referenced from the list of Methods as “Required Parameters”.

Optional Parameters

The following optional base parameters can also be provided with your requests:

 

Parameter Name

Type

Description

response_type

string (enumeration)

The desired response type to receive from the API server from an API request.

 

Accepted values:

json -- (default) serialized JSON data

php -- serialized PHP data

 

Other parameters will also be required or optional and vary depending on the API method you are calling as outlined in the Methods section.

Request Signatures

All requests against the Team Cowboy API must include a “sig” parameter which represents a signature for the data being sent with your request. Request signatures help ensure that the API request was made by you and that the data received by the API server is the same as what you sent (i.e., that it was not tampered with in transit by a third party).

 

A signature is created by concatenating specific values together with a pipe character ( | ) and then creating SHA-1 hash from the concatenated string. There are six values that are used to create the string to be hashed as explained below.

 

IMPORTANT:

The value for the signature should be sent to the Team Cowboy API should be lowercase. This requirement is in place to remove any ambiguity since different programming languages return different cases for the hex values of a SHA-1 hash.

 

The values that comprise the signature, in this specific order, are:

1.     Private API key - case-sensitive

2.     HTTP request method (“GET” or “POST”) - case-sensitive

3.     Team Cowboy API Method being called - case-sensitive

4.     Timestamp

5.     Nonce

6.     Concatenated string of request name/value pairs, sorted alphabetically by parameter name with values URL-encoded, and lower-cased. Further details on the expected format are provided below.

 

For example, suppose you have the following values that will be used to create your signature:

1.     Private API key:  413abdc2120adb9a06eb13cf76483aa25d18dc5a

2.     HTTP request method:  GET

3.     Team Cowboy API Method being called:  Team_Get

4.     Timestamp:  1296268551

5.     Nonce:  5646464564

6.     Concatenated request string:  api_key=b412e0601e179ad12df1a0ff5b8da12aafb74a3d
&method=team_get&nonce=5646464564&teamId=1234&timestamp=1296268551&userToken=0bd5a0ed9ff7f4c59e1854b63b341a8f

 

The concatenated string would be as follows (NOTE: line breaks added here for readability, actual string to be hashed should NOT contain line breaks):

413abdc2120adb9a06eb13cf76483aa25d18dc5a|GET|Team_Get|1296268551|
5646464564|api_key=b412e0601e179ad12df1a0ff5b8da12aafb74a3d
&method=team_get&nonce=5646464564&teamId=1234
&timestamp=1296268551&userToken=0bd5a0ed9ff7f4c59e1854b63b341a8f

 

And the SHA-1 hash of the above value would be:

420dbffb7136d0dab320a29d0d2e64ce8a27f7e7

 

As shown above, the SHA-1 hash signature string should be lowercase and 40 characters long.

 

This value would then be passed in your API request as the value for the “sig” parameter.

Creating the Concatenated String of Request Name/Value Pairs

Part of the process of creating a signature for requests to the Team Cowboy API involves creating a concatenated string of the name/value pairs that are present in the request. This section describes how to properly create that string to ensure will match the logic used on the API server. If these instructions are not followed properly, your request signature will not match.

 

The goal is to get a string of name/value pairs where the name and value in a given pair are separated by an equal sign (=) and each name/value pair are separated by an ampersand (&).

 

Other important notes:

      Parameter names should be lowercased

      All values in the string should be URL-encoded per RFC 3986. In PHP, the URL encoding would be accomplished using the rawurlencode() function (not urlencode()). In .NET C#, this would be done with HttpUtility.UrlEncode() and then a manual replacement of plus signs (+) with the encoded value of %20.

      Parameter values should be lowercased *after* URL-encoding

      Among other things, spaces should be encoded as %20, not as a plus sign (+). Be sure your development language is doing this or your string will not be correct and your request signature will not be validated by the Team Cowboy API server.

 

STEP 1:

Convert your request parameters to lowercase and sort them alphabetically by parameter name. In other words, the order that request parameters are in when the concatenated string is created is very important!


EXAMPLE:

Suppose you have a request with the following name/value pairs present:

house = White with blue trim

dog = Toy Poodle

tree = BIRCH

cat = tabby

 

These parameters need to first be sorted alphabetically by parameter name, so the order of the parameters should become:

cat = tabby

dog = Toy Poodle

house = White with blue trim

tree = BIRCH

 

STEP 2:

Concatenate each name/value pair with an equal sign (=), then concatenate each of the name/value pairs with an ampersand (&). The values in each name/value pair should be URL-encoded and then the entire name/value pair string should be converted to lowercase.


The result of this per the ordered list of parameters shown above in STEP 1 would be (note that all values have been lower-cased!):

cat=tabby&dog=toy%20poodle&house=white%20with%20blue%20trim&tree=birch

Responses

The Team Cowboy API will return a HTTP response to each HTTP request. By default, the body of the HTTP response will be serialized JSON data. The Team Cowboy API can also return serialized PHP by providing a value for the response_type parameter of “php”. We chose JSON as the default response type because of it’s widespread acceptance and because encoding/decoding functions for JSON exist for all major programming languages.

 

At a high level, API responses (regardless of response type) include the following values:

1.     success -- a boolean value (true or false) which indicates if the request was successful. If this is false, the body (described below) will generally include an error object which includes an error code, a description of the error that occurred, and other relevant information.

2.     requestSecs -- the length of time (in seconds) that it took to fulfill your API request

3.     body -- the body of the response will either be the expected response data for the method you are calling or it will be an object representing an error that occurred from the request. A list of possible errors is outlined in the section, Response Errors.

 

Sample Response with Error (JSON)

Here is an example of a response that might be returned for an unsuccessful request. This response body includes an error object as described above. See Response Errors for more information about errors that are returned in API responses.

 

{"success":false,"body":{"error":{"errorCode":"invalidMethod","httpResponse":501,"message":"An invalid or unsupported method was passed to the API (or no method was passed at all). Please check the documentation."}}}

 

Here is a more human-readable version of the same information:

success:  false (boolean)

body:  error (object):

errorCode:  invalidMethod

httpResponse:  501

message:  An invalid or unsupported method was passed to the API (or no method was passed at all). Please check the documentation.

HTTP/1.1 Status Codes

Responses from the API will include proper status code headers based on the HTTP/1.1 standard, such as:

      200 - OK

      400 - Bad request

      401 - Unauthorized

      403 - Forbidden

      404 - Not Found

      405 - Method not allowed

      500 - Internal server error

      501 - Not implemented

 

Response Errors

If an API method is called and something goes wrong, you should receive an error object (serialized as JSON or PHP) in the body of the response.

Error Object Definition

Property

Type

Description

errorCode

string

The unique error code for the error. See below for a list of error codes that may be returned from requests to the API.

httpResponse

integer

The HTTP/1.1 status code that was returned. See HTTP/1.1 Status Codes.

message

string

A message describing the error in more detail.

 

Error Codes

The table below lists possible error codes that may be returned from requests against the API. Error codes will be returned as part of the error response as outlined above. The wording of the descriptions returned from the API for each of these error codes may differ from those below.

 

COMING SOON…

 

Methods

This section describes the methods that can be called on the Team Cowboy API.

 

Important Notes:

      Each method below is designed to be called via an HTTP GET request or an HTTP POST request, but not both. If you receive an error response that the requested method could not be found, make sure you are properly calling the API with a GET or POST request.

      Each method below is designed to be called via a regular (HTTP) or secure (HTTPS) connection. If a method requires a secure/HTTPS connection, you will receive an error if you attempt to call it using a non-secure/HTTP connection. Be sure you are using the applicable API endpoint URL (regular or secure).

      ALL METHOD CALLS require a set of basic parameters as defined in the Required Parameters section. These basic parameters are not listed for each method below.

      JSON does not have a concept of associative arrays. Therfore, in cases where the documentation states that an associative array will be returned (i.e., an array with a specific value as the array index), it will be returned as an object if your response type is “json”. If your response type is “php”, the associative array will remain as such once the serialized PHP in the response is unserialized.

      The responses listed below for each method are what you should expect to be returned in the “body” portion of the response string as described in the Responses section of this document. All responses are assumed to be objects. Objects are not technically being returned but the serialized JSON or serialized PHP returned, when unserialized, should be an object in the respective language (an object in JSON or a StdClass object in PHP).

Authentication Methods

Auth_GetUserToken

Request Method:  POST, SSL

 

Retrieves a user token for a Team Cowboy user account for use with your API account. User tokens are used and required for most other API methods.

 

If a token does not yet exist for the API account/user pair, a new token will be created. Tokens cannot be retrieved for inactive user accounts. Additionally, if a user has disabled access from your API account/application, a token will not be returned, even if you have received one in the past..

 

Parameters

Parameter Name

Type

Description

username

string

Required. The username of the user you are getting a token for.

password

string

Required. The password of the user you are getting a token for.

 

Response Object

Property

Type

Description

userId

int

The ID of the user matched.

token

string (36)

A unique token for the user matched. Tokens are 36-character, lower-cased GUIDs.

 

Event Methods

Event_Get

Request Method:  GET

 

Retrieves details for a specific event. User must be an active team member on the team provided and the event must be associated with the team provided.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Required. Id of the team that the event is associated with.

eventId

int

Required. Id of the event to retrieve.

includeRSVPInfo

boolean

Optional. Whether or not to include RSVP information for the user.

 

Default value:  false

 

Response

Event object.

Event_GetAttendanceList

Request Method:  GET

 

Retrieves attendance list information for a specific event. This provides a list of team members and their RSVP statuses for the requested event.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Required. Id of the team that the event is associated with.

eventId

int

Required. Id of the event for the attendance list to retrieve.

 

Response

AttendanceList object.

Event_SaveRSVP

Request Method:  POST

 

Saves an event RSVP for a user. Note that rules surrounding RSVPs are complex and can vary from event-level rules to more complete team rules. These rules are taken into consideration when evaluating the parameter values below, so some parameter values may be ignored. For example, if a team does not permit additional male or female players from being included in RSVPs, these values, even if provided, will be ignored. Similarly, if a team does not allow certain RSVP statuses such as “available”, then providing “available” as the status parameter value will either throw an error or it will default to the next best fit RSVP status (e.g., “maybe” or “no”).

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Required. Id of the team that the event is associated with.

eventId

int

Required. Id of the event to retrieve.

status

string (enum)

Required. The RSVP status to save for the user.

 

NOTE: To remove a RSVP, pass “noresponse” to remove the RSVP (if RSVP removal is allowed for the event). To determine if RSVP removal is allowed for a given event, refer to Event.rsvpInstances[].rsvpDetails.allowRsvpRemoval

 

Valid values:  yes, maybe, available, no, noresponse

addlMale

int

Optional. The number of additional male players to include as “yes” in the RSVP. If this parameter is omitted from the request, any value present for additional male players on the RSVP is not updated (i.e., existing values will not be overwritten). To remove this value for the RSVP, pass 0 (zero).

addlFemale

int

Optional. The number of additional female players to include as “yes” in the RSVP. If this parameter is omitted from the request, any value present for additional female players on the RSVP is not updated (i.e., existing values will not be overwritten). To remove this value for the RSVP, pass 0 (zero).

comments

string

Optional. RSVP comments. If not provided, any existing RSVP comments will be cleared out for the user’s RSVP.

rsvpAsUserId

int

Optional. The user to RSVP for. This is used to allow a user to RSVP as a user that is in their list of linked users. If not provided, the RSVP will be saved for the user associated with the userToken parameter value.

 

Response

SaveRSVPResponse object.

 

Message Methods

Message_Get

Request Method:  GET

 

Retrieves information about a team message.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Required. Id of the team associated with the message.

messageId

int

Required. Id of the message to retrieve.

loadComments

boolean

Optional. Whether or not to load comments for the message.

 

Default value: false

 

Response

Message object.

Message_Delete

Request Method:  POST

 

Deletes a team message. The user attempting to delete the message must be a team admin for the team that the message is associated with, or they must be the author of the message.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Required. Id of the team associated with the message.

messageId

int

Required. Id of the message to delete.

 

Response

Boolean (true if the message was successfully deleted, false otherwise).

Message_Save

Request Method:  POST

 

Saves (adds or updates) a team message.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Required. Id of the team associated with the message to add/update.

messageId

int

Optional. Id of the message to update. If not provided, a new message will be added.

title

string

Required. The title of the message.

body

string

Required. The body of the message. HTML is allowed, although unsafe tags are stripped out (nearly all normal HTML tags are allowed).

isPinned

boolean

Optional. Whether or not the message should be pinned in the team’s list of mesages.

 

Default value:  false (this value is forced to false if the user adding/updating the message is not a team admin).

sendNotifications

boolean

Optional. Whether or not to send notifications when the message and any message comments are posted.

 

Default value:  false

isHidden

boolean

Optional. Whether or not the message is hidden in the team’s list of messages.

 

Default value:  false (this value is forced to false if the user adding/updating the message is not a team admin).

allowComments

boolean

Optional. Whether or not comments can be posted for the message..

 

Default value:  true

 

Response

Message object that was added or updated.

MessageComment_Delete

Request Method:  POST

 

Deletes a comment for a message. The user attempting to delete the comment must be a team admin for the team that the message comment is associated with, or they must be the author of the comment.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Required. Id of the team associated with the message.

messageId

int

Required. Id of the message that the comment is associated with.

commentId

int

Required. Id of the comment to delete.

 

Response

Boolean (true if the comment was successfully deleted, false otherwise).

MessageComment_Add

Request Method:  POST

 

Adds a new comment for a message. The message must allow comments to be posted or the request will not be successful.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Required. Id of the team associated with the message.

messageId

int

Required. Id of the message that the comment is associated with.

comment

string

Required. The text of the comment being added.

 

Response

MessageComment object for the comment that was added.

Team Methods

Team_Get

Request Method:  GET

 

Retrieves information about a team. The team requested must be accessible by the user represented by the user token being provided (i.e., you cannot retrieve team information for a team unless the user is an active member of that team).

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Required. Id of the team to retrieve.

 

Response

Team object.

Team_GetEvents

Request Method:  GET

 

Retrieves an array of events for a team’s season.The team requested must be accessible by the user represented by the user token being provided (i.e., you cannot retrieve team information for a team unless the user is an active member of that team).

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Required. Id of the team to retrieve events for.

seasonId

int

Optional. Id of the season to retrieve events for.

If not provided, events for all of the team’s seasons will be returned.

filter

string (enum)

Optional. An enumeration value indicating a special filter for retrieving events.

 

Valid values:

      past - returns events that have a start date before the current date in the team’s time zone

      future - returns events that start in the future, based on the current date/time in the team’s time zone

      specificDates - returns events bounded by a specific date range, specified by the “startDateTime” and “endDateTime” parameters. At least one of these parameters is required if using this filter value.

      nextEvent - returns the next event based on the current date/time. Note that this keys off of the start date/time of the event.

      previousEvent - returns the previous event based on the current date/time. Note that this keys off of the start date/time of the event.

 

If not provided, the filter defaults to “future”.

startDateTime

date/time

Required (if filter=specificDates). If provided, events will only be retrieved that have a start date on or after this value. The value provided is evaluated against the local date for the event.

 

Enter date/time in format:
YYYY-MM-DD HH:MM:SS

endDateTime

date/time

Required (if filter=specificDates). If provided, events will only be retrieved that have a start date on or before this value. The value provided is evaluated against the local date for the event.

 

Enter date/time in format:
YYYY-MM-DD HH:MM:SS

offset

int

Optional. The number of events to shift from those returned. This is typically used if you are requesting a specific number of events per page and you need to offset to a different page. This value is zero-based (i.e., for no offset, use 0, not 1).

 

Default value:  0

qty

int

Optional. The number of events to retrieve. Again, if using pagination in your application, this would typically be the page size, or you just want to reduce the response size (i.e., less events).

 

Default value:  10

 

Response

Array of Event objects.

Team_GetMessages

Request Method:  GET

 

Retrieves an array of Message Board posts for a specific team.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Required. Id of the team to retrieve messages for.

messageId

int

Optional. Id of the message to retrieve. If not provided, all messages are retrieved.

offset

int

Optional. The number of messages to shift from those returned. This is typically used if you are requesting a specific number of messages per page. This value is zero-based (i.e., for no offset, use 0, not 1).

 

Default value:  0

qty

int

Optional. The number of messages to retrieve. Again, if using pagination in your application, this would typically be the page size.

 

Default value:  10

sortBy

string (enum)

Optional. An enumeration value indicating how to sort the messages that are returned.

Valid values:

      title - message title

      lastUpdated - date/time when the message was last updated

      type - the message type (pinned or regular message)

 

Default value:  lastUpdated

sortDirection

string (enum)

Optional. The sort direction for the messages returned.

 

Valid values:  ASC, DESC

 

Default value:  The default value varies based on the sortBy parameter:

      title: ASC

      lastUpdated: DESC

      type: DESC

      No sortBy parameter: ASC

 

Response

Array of Message objects.

Team_GetRoster

Request Method:  GET

 

Retrieves roster members for a given team.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Required. Id of the team to retrieve.

userId

int

Optional. Id of a specific user/team member to retrieve. If omitted, all team members are returned.

includeInactive

boolean

Optional. Whether or not to include team members that are marked as “inactive” for a team (inactive team members cannot access the team but are visible from the Roster page for team admins).

 

Default value:  true

sortBy

string (enum)

Optional. Order to sort the team members returned. The valid values for this parameter vary depending on whether or not the user making the method call is an admin on the team.

 

Valid values (case-sensitive):

      If user is a team admin:  playerType, playerType_sex, sex, sex_playerType, email, email2, firstName, lastName, phone, tshirtSize, tshirtNumber, pantsSize, lastLogin, active, inviteStatus

      If user is not a team admin:  firstName, playerType, sex

 

Default value:  firstName

sortDirection

string (enum)

Optional. The sort direction for the team members returned.

 

Valid values:  ASC, DESC

 

Default value:  ASC

 

Response

Array of User objects.

Team_GetSeasons

Request Method:  GET

 

Retrieves schedule seasons for a team. The team requested must be accessible by the user represented by the user token being provided (i.e., you cannot retrieve team information for a team unless the user is an active member of that team).

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Required. Id of the team to retrieve seasons for.

 

Response

Array of Season objects.

Test Methods

Test_GetRequest

Request Method:  GET

 

This is a very basic testing method for checking that you are able to call the Team Cowboy API via a HTTP GET.

 

Parameters

Parameter Name

Type

Description

testParam

string

Optional. A string to send with the method. The value will be output in the response so you can verify that you sent a parameter successfully.

 

Response Object

Property

Type

Description

helloWorld

string

A string message confirming you called this test method successfully. If a value for “testParam” was provided, it will be output here as well.

 

Test_PostRequest

Request Method:  POST

 

Information for Test_PostRequest is the same as Test_GetRequest except that the request type must be POST.

 

User Methods

User_Get

Request Method:  GET

 

Retrieves user details.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token for the user to retrieve information for.

 

Response

User object.

User_GetNextTeamEvent

Request Method:  GET

 

Retrieves the next event on the user’s event schedule. By default, the event will be the next event from any of the teams that are visible in the user’s profile. The next event can be restricted to a specific team by providing a value for the teamId parameter in the method call.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Optional. A teamId to restrict the event returned to a specific team. If not provided, events for all of the user’s teams will be considered.

dashboardTeamsOnly

boolean

Optional. Whether or not to only consider the user’s Dashboard teams when retrieving the user’s next event.

 

Default value:  false

 

Response

Event object. If no next event is present, an empty object will be returned.

User_GetTeamEvents

Request Method:  GET

 

Retrieves an array of events for the teams that the user is an active member of. Events are only returned for teams that are visible in the user’s profile.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

startDateTime

date/time

Optional. If provided, events will only be retrieved that have a start date/time on or after this value. The value provided is evaluated against the local date/time for the event. If not provided, the current date/time is used.

 

Enter date/time in format:
YYYY-MM-DD HH:MM:SS

endDateTime

date/time

Optional. If provided, events will only be retrieved that have a start date/time on or before this value. The value provided is evaluated against the local date/time for the event. If not provided, the current date/time + 60 days is used.

 

Enter date/time in format:
YYYY-MM-DD HH:MM:SS

teamId

int

Optional. A teamId to restrict the events returned to a specific team. If not provided, events for all of the user’s teams are returned.

dashboardTeamsOnly

boolean

Optional. Whether or not to restrict the events retrieved only to those for teams on the user’s Dashboard.

 

Default value:  false

 

Response

Array of Event objects.

User_GetTeamMessages

Request Method:  GET

 

Retrieves an array of Message Board posts for the teams that the user is an active member of. Message Board posts are only returned for teams that are visible in the user’s profile.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

teamId

int

Optional. A teamId to restrict the messages that are returned to a specific team.

 

Default:  If this value is not provided, messages for all of the user’s teams are returned.

messageId

int

Optional. Id of the message to retrieve. If not provided, all messages are retrieved.

offset

int

Optional. The number of messages to shift from those returned. This is typically used if you are requesting a specific number of messages per page. This value is zero-based (i.e., for no offset, use 0, not 1).

 

Default value:  0

qty

int

Optional. The number of messages to retrieve. Again, if using pagination in your application, this would typically be the page size.

 

Default value:  10

sortBy

string (enum)

Optional. An enumeration value indicating how to sort the messages that are returned.

Valid values:

      title - message title

      lastUpdated - date/time when the message was last updated

      type - the message type (pinned or regular message)

 

Default value:  lastUpdated

sortDirection

string (enum)

Optional. The sort direction for the messages returned.

 

Valid values:  ASC, DESC

 

Default value:  The default value varies based on the sortBy parameter:

      title: ASC

      lastUpdated: DESC

      type: DESC

      No sortBy parameter: ASC

 

Response

Array of Message objects.

User_GetTeams

Request Method:  GET

 

Retrieves an array of teams that the user is an active member of.

 

Parameters

Parameter Name

Type

Description

userToken

string

Required. API account/user token. See the Auth_GetUserToken method.

dashboardTeamsOnly

boolean

Optional. Whether or not to restrict the teams retrieved only to those on the user’s Dashboard.

 

Default value:  false

 

Response

Array of Team objects.

Object Definitions

This section describes the objects that are returned in API method calls and their respective properties.

Activity

Description

An activity/sport that is typically associated with teams or team seasons.

Object Properties

Property

Type

Description

activityId

int

Activty Id

name

string

Activity name

 

AttendanceList

Description

Attendance list information for a given event.

Object Properties

Property

Type

Description

countsByStatus

array

An array of simple objects, each describing attendance count information by RSVP status.

 

Object properties:

      status (string) - The RSVP status name

      counts (object) - Object containing counts:

      byGender (object):

      m (int)

      f (int)

      other (int)

      byType (object)

      typeName1 (int)

      typeName2 (int)

      typeNameN (int)

      total (int)

       

 

Refer to the meta property of the AttendanceList object for a list of RSVP statuses.

meta

object

Object that contains meta information for looping through and displaying attendance list information.

 

Object properties:

      teamMemberTypes (array) - array of TeamMemberType objects.

      genders (array) - array containing simple objects describing the genders:

      gender (string) - gender name

      genderDisplay (string) - gender display value/title

      rsvpStatuses (array) - array of objects describing the RSVP statuses:

      status (string)

      statusDisplay (string)

      misc (object) – object with miscellaneous values:

      genderLabel_male (string) – display label to use for male gender, as defined by the team.

      genderLabel_female (string) – display label to use for male gender, as defined by the team.

      genderLabel_other (string) – display label to use for male gender, as defined by the team.

      groupBy (string) – preferred secondary grouping of team members in the Attendance List (after grouping by RSVP status). Possible values:  none (no sub-grouping), teamMemberType (group by team member type), gender (group by gender)

usersIdsByStatus

array

An array of simple objects that provides user IDs by RSVP status.

 

Object properties:

      status (string) - RSVP status name

      userIds (object) - object with properties listing userIds:

      byGender (object):

      m (array) - array of user Ids

      f (array) - array of user Ids

      byType (object)

      typeName1 (array) - array of user Ids

      typeName2 (array) - array of user Ids

      typeNameN (array) - array of user Ids

      all (array) - array of user Ids

 

Refer to the meta property for a list of RSVP statuses.

users

array

An array of users for the attendance list. Each array element is an object describing the user as well as attendance list information for the user in context of the event.

 

Object properties:

      user (object) - An abridged version of the User object.

      rsvpInfo (object) - AttendanceListUserInfo object.

 

AttendanceListUserInfo

Description

Attendance list/RSVP information for a given user in context of an event.

Object Properties

Property

Type

Description

status

string

RSVP status

statusDisplay

string

RSVP status display value

comments

string

Comments

canRSVP

boolean

True if the user can RSVP for the event based on the event, team member, and team settings.

hasResponded

boolean

True if an RSVP response has been recorded for the user (i.e., if the user has not yet responded for the event, this will be false).

addlMale

int

The number of additional male attendees that are a “yes” RSVP that this team member has included with their RSVP.

addlFemale

int

Same as addlMale, but for females.

addlDisplay

string

A string describing the additional male and/or female players.

dateCreatedLocal

date/time

The date/time when the RSVP was first saved, in the event’s timezone.

dateLastUpdatedLocal

date/time

The date/time when the RSVP was last updated, in the event’s timezone.

dateCreatedUtc

date/time

The date/time when the RSVP was first saved (UTC).

dateLastUpdatedUtc

date/time

The date/time when the RSVP was last updated (UTC).

 

ColorSwatch

Description

A color swatch that contains one or more colors. Typically color swatches are assigned to a team or opponent team for an event on a team’s event schedule.

Object Properties

Property

Type

Description

label

string

The label/title of the color swatch as a whole.

colorCount

int

The number of colors in the color swatch.

colors

array

An array of colors in the color swatch. Each array element is an object describing the color.

 

Object properties:

      name (string) - The name of the color.

      hexCode (string) - The HTML hex code for the color (e.g., #FFFFFF for white).

 

Event

Description

An event in a team’s event schedule.

Object Properties

Property

Type

Description

eventId

int

Event Id

team

object

Simple object with basic team information.

Object Properties:

      teamId (int) - Team Id

      name (string) - Team name

seasonId

int

Season Id

seasonName

string

Season name

eventType

string (enum)

Event type enumeration.

Possible values:  game, doubleheader, postseason, match, meet, tournament, jamboree, race, regatta, ride, bye, practice, scrimmage, pickup, meeting, other

eventTypeDisplay

string

Event type display

status

string (enum)

Event status enumeration.

Possible values:  active, postponed, canceled, forfeited

statusDisplay

string

Event status display

personNounSingular

string

Team member noun display (singular). E.g., player, competitor, attendee, etc.

personNounPlural

string

Team member noun display (plural). E.g., players, competitors, attendees, etc.

title

string

Title of the event. This varies based on the event type. For game-related events (game, meet, race, etc), this is the opponent name. For other events types, this is the event title.

titleFull

string

The full title of the event. This takes into consideration opponent names (for events where that is applicable), etc. For game-related events (game, meet, race, etc), this would be something like “Home vs. OpponentName”. For other events types, this is the event title or just the user-facing version of the event type (such as “Practice”).

titleLabel

string

The label to use for the event title. Like the title value itself, this varies based on the event type.

homeAway

string (enum)

Whether the event is home or away (enumeration).

Possible values:  home, away, NULL

result

object

Simple object describing the outcome/result of the event.

 

Object Properties:

      scoreEntered (bool) - True if a score has been entered for the event

      outcome (string, enum) - outcome for the event: win, loss, tie, NULL

      score1 (int) - Score entered for the main team

      score2 (int) - Score entered for the opponent team

      isWin (bool) - True if the event was a win

      isTie (bool) - True if the event was a tie

      isLoss (bool) - True if the event was a loss

      scoreDisplay (string) - Display of the outcome and the scores

      dhScoreEntered (bool) – Same as scoreEntered, but for the 2nd game in a doubleheader event

      dhOutcome (string, enum) – Same as outcome, but for the 2nd event in a doubleheader event

      dhScore1 (int) - Same as score1, but for the 2nd game in a doubleheader event

      dhScore2 (int) - Same as score2, but for the 2nd game in a doubleheader event

      dhIsWin (bool) - Same as isWin, but for the 2nd game in a doubleheader event

      dhIsTie (bool) - Same as isTie, but for the 2nd game in a doubleheader event

      dhIsLoss (bool) - Same as isLoss, but for the 2nd game in a doubleheader event

      dhScoreDisplay (string) - Same as scoreDisplay, but for the 2nd game in a doubleheader event

rsvpInstances

array

Array of RSVPInstance objects. This property is only present if RSVP instance information was loaded for the event -- see Event_Get().

comments

string

Event comments

options

array

Array of event options.

oneLineDisplay

string

One-line display of the event information. Automatically adjusts based on event type, start/end dates/times, etc.

oneLineDisplayShort

string

Same as oneLineDisplay, but a bit shorter

maleGenderDisplay

string

The display text to use for male genders on the team. This is based on team settings.

femaleGenderDisplay

string

The display text to use for female genders on the team. This is based on team settings.

dateTimeInfo

object

Simple object with describing date/time information for the event.

 

Object Properties:

      timezoneId (string) - Timezone Id for the event

      startDateLocal (date) - The start date of the event in the event’s timezone in the format YYYY-MM-DD

      startTimeLocal (time) - The start time of the event in the event’s timezone, in the format HH:MM:SS

      startDateTimeLocal (date/time) – the combined start date and time for the event in the event’s timezone, in the format YYYY-MM-DD HH:MM:SS

      startDateLocalDisplay (date) – The display version of the start date of the event in the event’s timezone

      startTimeLocalDisplay (time) - The display version of the start time of the event in the event’s timezone

      startDateTimeLocalDisplay (time) - The display version of the combined start date and time of the event in the event’s timezone

      startDateTimeUtc (date/time) - The start date/time of the event in UTC, in the format YYYY-MM-DD HH:MM:SS

      startTimeTBD (bool) - True if the start time is marked as “TBD”. Note that this is not the same as an event without a time. This indicates the event explicitly has the “Time TBD” flag set.

      [End Date/Time Values] -- same as above but for the event’s end date/time (e.g., instead of “startDateLocal”, use “endDateLocal”, etc.)

      inPast (bool) – True if the event is in the past

      inFuture (bool) – True if the event is in the future

location

object

Location object. If no properties are present, the event does not have a location set.

shirtColors

object

Simple object representing the team shirt colors.

 

Object Properties:

      team1 (object) - ColorSwatch object describing the color swatch for the main team (the team the event is assigned to). Value is null if no color swatch is present.

      team2 (object) - ColorSwatch object describing the color swatch for the opponent/other team. Value is null if no color swatch is present.

userMetaInfo

object

Simple object representing meta information about the API user in context of the event’s team.

 

Object Properties:

·       isTeamAdmin (bool) – True if the user is a team administrator on the event’s team

·       showOnDashboard (bool) – True if the user user has selected to show the event’s team on their Dashboard page

dateCreatedUtc

date/time

Date/time the event was created (UTC). See important notes in the Change Log (Revision 7.42) for information about this field.

dateLastUpdatedUtc

date/time

Date/time the event was last updated (UTC).

 

Location

Description

A location, typically associated with one or more events.

Object Properties

Property

Type

Description

locationId

int

Location Id

name

string

Location name

surface

object

Simple object describing the “surface” of the location.

 

Object Properties:

      type (string) - The surface type (grass, turf, dirt, etc)

      typeDisplay (string) - Display value for the surface type

      showType (bool) - True if it makes sense to show the surface type for the location (this takes into consideration whether a type is defined, etc.)

lights

object

Simple object describing lighting for the location.

 

Object Properties:

      lights (string) - Value for the lights setting for the location (yes, no, unknown, or na)

      lightsDisplay (string) - Display value for the lights setting for the location

      hasLights (bool) - True if the location has lights

address

object

Simple object describing the address for the location.

 

Object Properties:

      addressLine1 (string) - First address line

      addressLine2 (string) - Second address

      city (string) - City

      stateProvince (string) - State/province

      postalCode (string) - Zip/Postal code

      partOfTown (string) - Part of town (neighborhood, etc)

      displayMultLine (string) - Multi-line display for the address (lines separated by newlines)

      displaySingleLine (string) - Single-line display for the address

      googleMapsUrl (string) - Google Maps URL for the address

      googleMapsDirectionsUrl (string) - Google Maps “Get Directions” URL for the address

visibility

string

The visibility for the location (public or private)

visibilityDisplay

string

The display value for visibility.

comments

string

Location comments.

 

LinkedUser

Description

A Team Cowboy user account that is linked to or from another Team Cowboy user account.

Object Properties

Property

Type

Description

fromUserId

int

The User Id of the “from” user in the link.

toUserId

int

The User Id of the “to” user in the link.

username

string

Username

firstName

string

First name

lastName

string

Last name

fullName

string

Full name (first and last names combined)

displayName

string

Display name.

isActive

boolean

Whether or not the link is active in the user’s profile.

profilePhoto

object

Simple object with full URLs to the user’s profile photo.

 

Object Properties:

      thumbUrl (string) - thumbnail photo

teams

array

Array of simple objects representing the teams that the linked user is a member of.

 

Object Properties:

      teamId (int) - Team Id

      name (string) – The name of the team

      profilePhoto (object):

      Simple object with full URLs to the team’s photo.

      thumbUrl (string) - thumbnail photo

      meta (object) - Simple object with meta information about the user in context to the team:

      teamMemberType (object) - information describing the user’s team member type:

      name (string) - type name

      title (string) - type title/display name

      titleShort (string) - short version of type title/display name

      options (array) - Array of options specific to the user/team pair

 

Message

Description

A message for a team’s message board.

Object Properties

Property

Type

Description

messageId

int

The message Id.

title

string

The title of the message.

bodyHtml

string

The body of the message (HTML).

bodyText

string

A text approximation of the HTML message. Note that messages are natively stored as HTML, so the text version provided in this property may not be perfect or as the author intended it. In some cases, it may be preferred to convert HTML to text using your own code libraries in your applications.

isPinned

boolean

True if the message is a “pinned” message (pinned messages always show at the top of the message list on the main Team Cowboy web site).

allowComments

boolean

True if comments can be posted for the message.

commentCount

int

The number of comments that have been posted for the message.

team

object

Simple object describing the team that the message is assigned to.

 

Object Properties:

      teamId (int) - The team Id

      name (string) - The team name

postedBy

object

Simple object describing the user that posted the message.

 

Object Properties:

      userId (int) – The user’s Id

      firstName (string) - First name of the user

      lastName (string) - Last name of the user *

      fullName (string) - Full name of the user *

      gender (string) – Gender of the user (“m”, “f”, or “other”). *

      genderDisplay (string) – Display version of the user’s gender. *

      profilePhoto (object) - Simple object with full URLs to the team’s photo. *

      fullUrl (string) - full-size photo

      thumbUrl (string) - thumbnail photo

 

 

* Due to user privacy settings, the last name, profile photo URL(s), and/or gender values may not be present. This also affects the display of the full name if no last name is available (the full name will be the same as the first name).

comments

array

Array of MessageComment objects. Only present if comments are loaded for the message.

userMetaInfo

object

Simple object representing meta information about the API user in context of the team that the message applies to.

 

Object Properties:

·       isTeamAdmin (bool) – True if the user is a team administrator on the message’s team

·       showOnDashboard (bool) – True if the user user has selected to show the message’s team on their Dashboard page

·       canEdit (bool) – True if the user can edit/delete the message

dateCreatedLocal

date/time

Date/time the message was created (local time for the message’s team).

dateLastUpdatedLocal

date/time

Date/time the message was last updated (local time for the message’s team).

dateCreatedUtc

date/time

Date/time the message was created (UTC).

dateLastUpdatedUtc

date/time

Date/time the message was last updated (UTC).

 

MessageComment

Description

A comment for a post on a team’s message board.

Object Properties

Property

Type

Description

commentId

int

The message comment Id.

messageId

int

The Id of the message that the comment is associated with.

teamId

int

The Id of the team that the message is associated with.

timezoneId

string

The timezone Id for the comment (pulled from the team’s timezone).

postedBy

object

Simple object describing the user that posted the message comment.

 

Object Properties:

      firstName (string) - First name of the user

      lastName (string) - Last name of the user *

      fullName (string) - Full name of the user *

      gender (string) – Gender of the user (“m”, “f”, or “other”). *

      genderDisplay (string) – Display version of the user’s gender. *

      profilePhoto (object) - Simple object with full URLs to the team’s photo.

      thumbUrl (string) - thumbnail photo

 

* Due to user privacy settings, the last name, profile photo URL(s), and/or gender values may not be present. This also affects the display of the full name if no last name is available (the full name will be the same as the first name).

dateCreatedLocal

date/time

Date/time the comment was posted (local time for the message’s team).

dateLastUpdatedLocal

date/time

Date/time the comment was posted (local time for the message’s team).

dateCreatedUtc

date/time

Date/time the comment was posted (UTC).

dateLastUpdatedUtc

date/time

Date/time the comment was last posted(UTC).

 

RSVPInstance

Description

Information for an “RSVP instance” which is a representation of RSVP display values, rules, and other information that can be used to build user interface input controls for collecting a user’s RSVP for an event. An RSVP instance can be for the current user or it can be for one of the current users’ linked users.

Object Properties

Property

Type

Description

userId

int

Id of the user that the RSVP instance applies to.

displayName

string

Display string to use in the user interface. This is mean to be read from the current user’s point of view, so if the userId for the RSP instance is the current user, this will be something like, “Your status” whereas for any of the current user’s linked users, it will be the display name of the linked user.

teamMemberType

object

A TeamMemberType object for the user that the RSVP instance applies to.

rsvpDetails

object

Simple object describing RSVP information and other details for the current RSVP instance (e.g., the current user or another user they can RSVP on behalf of).

 

Object properties:

·       allowRSVP (bool) – Whether or not the user/instance is allowed to RSVP

·       allowRsvpRemoval (bool) – Whether or not the user/instance is allowed to remove their RSVP once it has been submitted

·       allowExtraPlayers (bool) – Whether or not the user/instance is allowed to include additional team members in their RSVP

·       allowedStatues (array)DEPRECATED, DO NOT USE! Original property was here but was misspelled. Use the “allowedStatuses” property instead. This property will be removed from API responses sometime after 1/1/2012.

·       allowedStatuses (array) – Array of strings representing the RSVP statuses that the user/instance is allowed to submit. Value will be “yes”, “maybe”, “available”, or “no”.

·       allowedStatusesDisplay (array) – Array of simple objects:

o   status (string) – Status name (corresponding with the value in the allowedStatuses property)

o   statusDisplay (string) – Display value for the status in context of the event (takes event type, past/future event, and other information into consideration)

·       status (string) – the current RSVP status for the user/instance. Value will be “yes”, “maybe”, “available”, “no”, or “noresponse”.

·       statusDisplay (string) – The user-facing RSVP status for the user/instance. This will vary based on the event type. For example, for a “Game” event type, a “yes” RSVP will be displayed as “Playing”.

·       statusDisplayShort (string) – A shorter version of the user-facing RSVP display value. This will often be the same as the “long” version, but not always.

·       addlMale (int) – The number of additional male team members on the RSVP for the user/instance

·       addlMaleDisplay (string) – The display value for the addlMale property. This will generally be the same if a value is present for addlMale, or will be blank if no additional male team members are present.

·       addlFemale (int) – The number of additional female team members on the RSVP for the user/instance

·       addlFemaleDisplay (string) – The display value for the addlFemale property. This will generally be the same if a value is present for addlFemale, or will be blank if no additional female team members are present.

·       comments (string) – RSVP comments provided for the user/instance

 

SaveRSVPResponse

Description

Response object returned from a call to the Event_SaveRSVP method.

Object Properties

Property

Type

Description

rsvpSaved

bool

True if the RSVP was saved, false otherwise.

statusCode

string (enum)

A status code indicating why the RSVP could not be saved. This value may be present if the RSVP is saved but will be blank.

 

Possible values:

      rsvpOverTotal - The event and/or team setting has a limit on the number of “yes” RSVPs that can exist for the event, and the RSVP you attempted to save would exceed that limit

      rsvpNotAllowed - The RSVP is not allowed per event and/or team settings (rules based on the event type, team member type, etc.)

      userNotOnTeam - The user you are trying to RSVP for is not on the team indicated

      commentsOverMaxLength - The comments provided are over the maximum length (150 characters)

      generalError - Some other error occurred and the RSVP could not be saved

 

Season

Description

A schedule season (event group) that is associated with a team.

Object Properties

Property

Type

Description

seasonId

int

Season Id

teamId

int

Team Id

name

string

Season name

startDateLocal

date/time

Season start date (in local time based on the timezone setting for the team).

startDateUtc

date/time

Season start date in UTC.

startDateInFuture

boolean

Whether or not the season start date is in the future.

activity

object

Activity object.

league

object

Simple object describing the league.

 

Object Properties:

      leagueId (int) - League Id

      name (string) - League name

      city (string) - City

      stateProvince (string) - State/province

      postalCode (string) - ZIP/Postal code

      countryIso2 (string) - ISO 2-letter country code

      websiteUrl (string) - Web site URL

leagueDivision

string

The team’s division that is listed for the season.

 

Team

Description

A team on the Team Cowboy web site.

Object Properties

Property

Type

Description

teamId

int

Team Id

name

string

Team name

shortName

string

Short team name. Will be truncated version of name if the value of name is long.

type

object

See object definition for TeamType.

activity

object

See object definition for Activity.

timezoneId

string

Timezone Id where the team is located.

city

string

City where the team is located

stateProvince

string

State/province where the team is located.

stateProvinceAbbrev

string

State/province abbreviation (e.g., “WA” for “Washington” or “ON” for “Ontario”).

country

string

Country where the team is located.

countryIso3

string

ISO3 value for the team’s country (e.g., “USA” for “United States of America”). See http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3

postalCode

string

Zip/Postal code where the team is located.

locationDisplayShort

 

string

String that can be used to output the team’s location, which includes the state/province, city, and country. The “short” version uses the state/province abbreviation and ISO3 value for the country.

locationDisplayLong

string

Same as locationDisplayShort, except uses full values for the state/province and country (instead of using abbreviation and ISO3 country code).

managerUser

object

Simple object describing the team member that is assigned as the manager for the team. Note that this team member may not necessarily have team administration privileges (the manager is for display purposes only). Also note that some fields below may not be populated based on permission and user privacy settings for the user accessing the API.

 

The value of this property will be NULL if no manager is defined for the team.

 

Object Properties:

      userId (int) – User Id

      firstName (string) – First name

      lastName (string) – Last name

      fullName (string) – Full name (first and last names combined)

      emailAddress (string) – E-mail address

captainUser

object

Simple object describing the team member that is assigned as the captain for the team.

 

See description and object properties for managerUser.

teamPhoto

object

Simple object with full URLs to the current team photo. Only returned if team has a photo.

 

Object Properties:

      fullUrl (string) - full-size photo URL

      smallUrl (string) - small size photo URL

      thumbUrl (string) - thumbnail photo URL

colorSwatches

object

Simple object describing 0 or more color swatches for the team.

 

Properties below will be null if no color swatch is defined for the team.

 

Object Properties:

·       home (ColorSwatch object) – “Home” color swatch for the team

·       away (ColorSwatch object) – “Away” color swatch for the team

·       alternate (ColorSwatch object) – “Alternate” color swatch for the team

options

object

Simple object with a subset of team options.

 

Object Properties:

·       misc (object) – Simple object:

o   showRecord (bool) – Whether or not to show record (wins/losses/ties) for event schedules.

o   (DEPRECATED – DO NOT USE)
attendanceListSeparateGenders (bool) – whether or not to separate genders when listing team members in the attendance list.

o   attendanceListMaleLabel (string) – The label to use for male team members on the team

o   attendanceListFemaleLabel (string) – The label to use for female team members on the team

o   hideGenders (bool) – Whether or not to hide the display of genders for the team

userProfileInfo

object

Simple object with profile information for the user that is specific to the team (i.e., information that may be overridden from the user’s core profile information).

 

NOTE: This information will only be present in the team object if the team was being loaded from a User method (such as User_GetTeams).

 

Object Properties:

      firstName (string) - First name

      lastName (string) - Last name

      fullName (string) - Full name (first and last name combined)

      displayName (string) - Display name

      emailAddress (string) - E-mail address 1

      emailAddress2 (string) - E-mail address 2

      phone1 (string) - Phone number 1

      phone2 (string) - Phone number 2

      gender (string) - Gender

      genderDisplay (string) - Gender display value

      shirtNumber (string) - Shirt number

      shirtSize (string) - Shirt size

      pantsSize (string) - Pants size

      profilePhoto (object):

      fullUrl (string) - full-size photo

      smallUrl (string) - small size photo

      thumbUrl (string) - thumbnail photo

      options (array) - Array of options specific to the user/team pair

      isTeamAdmin (boolean) – Whether or not the user is an administrator on the team

meta

object

Simple object with meta information about the user in context to the team.

 

NOTE: This information will only be present in the team object if the team was being loaded from a User method (such as User_GetTeams).

 

Object Properties:

      teamMemberType (object) - TeamMemberType

      isHiddenByUser (boolean) - true if the user has hidden the team from their profile

      showOnDashboard (boolean) - true if the user is showing the team on their dashboard

dateCreatedUtc

date/time

Date/time the team was created (UTC).

dateLastUpdatedUtc

date/time

Date/time the team was last updated (UTC).

 

TeamMemberType

Description

A team member type that is assigned to a team member (or is available to be assigned to a team member).

Object Properties

Property

Type

Description

name

string

The internal name of the type.

titleLongSingular

string

Display title (long version, singular tense).

titleLongPlural

string

Display title (long version, plural tense).

titleShortSingular

string

Display title (short version, singular tense).

titleShortPlural

string

Display title (short version, plural tense).

showTeamMembersOnRoster

boolean

True if team members associated with the team member type should be displayed on the team roster (and in other places where the team roster information is used). This setting comes from the team’s preferences, so it should be respected at all times when displaying information.

showTeamMembersOnAttList

boolean

True if team members associated with the team member type should be displayed on the attendance list for the team’s events. This setting comes from the team’s preferences, so it should be respected at all times when displaying information.

showTitleOnAttList

boolean

True if the display title should be shown in the attendance list for the team’s events. This setting comes from the team’s preferences, so it should be respected if at all possible.

 

TeamType

Description

Team type (adult, youth, etc.).

Object Properties

Property

Type

Description

name

string

Type name

title

string

Title/display name.

User

Description

A user in the Team Cowboy system. Users may be on one or more teams (or no teams at all).

 

IMPORTANT NOTE:  User profile information can be overridden for specific teams that the user is a member of. Because of this, profile information returned in a User object will either be for the core user profile or it will be for the user in context to a specific team. This is based on the API method that was called. For example, the User object returned from the User_Get method call will be in context of the user themselves whereas the array of User objects returned from a Team_GetRoster method call will be in context of the team passed with the method call via the teamId parameter.

 

Also note that some method calls that return User objects may return an abridged version of the object which has fewer properties populated. For example, Event_GetAttendanceList returns an AttendanceList object which includes and object that has a User object as its property. This User object does not include all of the properties listed below (such as detailed contact information and profile information) because that information is not relevant to displaying the attendance list.

Object Properties

Property

Type

Description

userId

int

User Id

firstName

string

First name

lastName

string

Last name

fullName

string

Full name (first and last names combined)

displayName

string

Display name

emailAddress1

string

E-mail address 1

emailAddress2

string

E-mail address 2

phone1

string

Phone number 1

phone2

string

Phone number 2

gender

string

Gender

 

Possible values:

      mMale

      f – Female

      other – Other/Not specified

genderDisplay

string

Gender display value

birthDate_month

int

Birthdate month (01 through 12)

birthDate_day

int

Birthdate day (01 through 31)

birthDate_year

int

Birthdate year (4-digit year)

shirtNumber

string

Shirt number

shirtSize

string

Shirt size (may be a numeric size or a standard size like S, M, L, etc.)

pantsSize

string

Pants size (may be a numeric size or a standard size like S, M, L, etc.)

options

array

An array of options that pertain to the user.

 

NOTE: This property is only populated for the user that is associated with the user token passed in the API call (i.e., only the current user’s options are populated).

profilePhoto

object

Simple object with full URLs to the user’s profile photo.

 

Object Properties:

      fullUrl (string) - full-size photo

      smallUrl (string) - small size photo

      thumbUrl (string) - thumbnail photo

teamMeta

object

Simple object describing team-specific information. This property is only present if the User is being returned in context to a team or event attendance list.

 

NOTE:  If reading user information from a call to the event attendance list (e.g., Event_GetAttendanceList), only the teamMemberType property will be populated below. All other values will not be present.

 

Object Properties:

      teamMemberType (object) - TeamMemberType

      notes (string) - Admin-only notes for the team member

      isTeamAdmin (bool) - Whether or not the user is an admin on the team

      invite (object) - information describing the invitation status for the user:

      status (string) - invitation status (accepted, rejected, pending)

      guid - unique invitation GUID

      dateSentLocal (date/time) - Date/time the invite was sent (in the team’s timezone)

      dateLastUpdatedLocal (date/time) - Date/time the invite was last updated (in the team’s timezone)

      dateSentUtc (date/time) - Date/time the invite was sent (UTC)

      dateLastUpdatedUtc (date/time) - Date/time the invite was last updated (UTC)

      options (array) - Array of options specific to the user on the team

linkedUsers

object

Simple object describing users that are linked to and/or from the user. Object will be empty if the user has no linked users. This property is not present if the User is being returned in context to a team.

 

Object Properties:

      linkedTo (array) - An array of LinkedUser objects representing the users that the user is linked to

      linkedBy (array) - An array of LinkedUser objects representing the users that are linked to the user

dateCreatedUtc

date/time

Date/time the user was created (UTC). This property is not present if the User is being returned in context to a team.

dateLastUpdatedUtc

date/time

Date/time the user was last updated (UTC).

dateLastSignInUtc

date/time

Date/time the user last signed in (UTC).

 

Document Revision History

November 18, 2013 (Rev 8.12)

·       Object changes:

o   Event – Additional fields are now present for the Event.result object to provide information about the 2nd event for a doubleheader event type. Additionally, the new fields are always present whether the event is a “doubleheader” event type or not. Before, the dhScoreEntered and dhOutcome fields were present in the Event.result object, but only if the event was a “doubleheader” event type. The new fields that are now present (in addition to dhScoreEntered and dhOutcome) are:  dhScore1, dhScore2, dhIsWin, dhIsTie, dhIsLoss, and dhScoreDisplay.

June 17, 2013 (Rev 8.11)

·       Object changes:

o   Event – New value added in eventType enumeration (“ride”).

September 27, 2012 (Rev 8.10)

·       Object changes:

o   AttendanceList – The AttendanceList.meta (object) property has a new property: misc (object). This object provides additional miscellaneous information that can be used when displaying the attendance list. Specifically, AttendanceList.meta.misc.groupBy is used to determine sub-grouping that should be taken into consideration when displaying a team’s attendance list (teams can define this option in their Team Settings).

o   Team – The Team.options.misc.attendanceListSeparateGenders (bool) value is now deprecated and should no longer be used. It now always returns true.

June 6, 2012 (Rev 8.00)

·       Object changes:

o   Message – The postedBy property of this object now includes gender and genderDisplay properties (both strings). The postedBy.profilePhoto property object also now includes fullUrl (string), which is the URL to the full-size version of the user’s profile photo.

o   MessageComment – The postedBy property of this object now includes gender and genderDisplay properties (both strings). The postedBy.profilePhoto property object also now includes fullUrl (string), which is the URL to the full-size version of the user’s profile photo.

o   User – The abridged version of the User object (returned from some function calls) now includes the gender and genderDisplay properties.

May 4, 2012 (Rev 7.9)

·       Object changes:

o   Message – Added a new userMetaInfo property (object). This includes some basic meta information for the user in context of the message’s team.

May 4, 2012 (Rev 7.8)

·       Method changes:

o   User_GetTeams – Added new parameter, dashboardTeamsOnly (bool) to only return teams on the user’s Dashboard.

o   User_GetTeamEvents – Added new parameter, dashboardTeamsOnly (bool) to only return events for teams on the user’s Dashboard.

o   User_GetNextTeamEvent – Added new parameter, dashboardTeamsOnly (bool) to only return the next event from teams on the user’s Dashboard.

·       Object changes:

o   Event – Added a new userMetaInfo property (object). This includes some basic meta information for the user in context of the event’s team.

o   RSVPInstance – Modified the rsvpDetails property (object) to include a new userMetaInfo property (object). This is an array of simple objects that provides the “display” value for the RSVP statuses.

April 29, 2012 (Rev 7.7)

·       Object changes:

o   Event:

§  New Event.titleFull property. This provides the full title of the event (without date/time information)

§  4 new properties were added to Event.dateTimeInfo:  startDateLocalDisplay, startDateTimeLocalDisplay, endDateLocalDisplay, endDateTimeLocalDisplay. These properties contain “user friendly” views for the event date and combined event date/time.

o   User – If querying the API for an event attendance list, the User objects returned in the AttendanceList.users array now includes the teamMeta property (object). Within that property, the teamMemberType property is set to provide basic information about the user’s team member type (for the team associated with the event that attendance list information was retrieved for).

·       Method changes:

o   Event_SaveRSVP – RSVPs can now be removed by passing “noresponse” as the RSVP status. Note, however, that you should check to ensure RSVP removal is allowed before attempting this, or you the method call will be unsuccessful. See the notes in “status” field for the Event_SaveRSVP method.

·       Other changes:

o   Miscellaneous documentation edits unrelated to API functionality.

April 27, 2012 (Rev 7.61)

·       Object changes:

o   Message – Added new “bodyText” property. This is an approximated text version of the HTML message body. See property notes for important information.

April 27, 2012 (Rev 7.6)

·       New object:

o   TeamType – Describes the type of team (adult, youth, etc.).

·       Object changes:

o   ColorSwatch – Added new “colorCount” property (int). This value provides the number of colors in the color swatch.

o   Team:

§  Added new “type” property (object), which describes the team type. See new TeamType object above.

§  Added a new “managerUser” property (object), which describes the team member that is designated as the manager for the team

§  Added a new “captainUser” property (object), which describes the team member that is designated as the captain for the team

§  Added a new “colorSwatches” property (object), which describes 0 or more color swatches for the team.

§  Added a new property to the “options” property:  misc.hideGenders (bool) – indicates whether or not to hide the display of genders for the team.

April 15, 2012 (Rev 7.51)

·       Object changes:

o   RSVPInstance – Added a new “allowRsvpRemoval” property (boolean) to the rsvpDetails property. This new property indicates if the user/instance is allowed to remove their RSVP once it has been submitted.

February 11, 2012 (Rev 7.5)

·       Object changes:

o   Team – Added a new “isTeamAdmin” property (boolean) to the Team.userProfileInfo property. This new property indicates if the user is an administrator on the team.

o   Message – Added a new “userId” property (int) to the Message.postedBy object. This new property is the Id of the user that posted the message.

·       Method changes:

o   Team_GetMessages – Added a new messageId parameter (int, optional) which can be used to retrieve a specific message. If not provided, all messages are retrieved (this was the default action before this parameter was added).

o   User_GetTeamMessages – Added a new messageId parameter (int, optional) which can be used to retrieve a specific message. If not provided, all messages that the user can read are retrieved (this was the default action before this parameter was added).

·       Other changes:

o   Miscellaneous edits unrelated to API functionality.

February 3, 2012 (Rev 7.42)

·       Object changes:

o   Event – A new “dateCreatedUtc” field has been added to the object. Please note that prior to this update, Team Cowboy was not recording the date/time when an event was created, so for events created in the system before February 3, 2012, the date/time when an event was created was set to the value that was present at the time for the date/time when an event was last updated. In reality, these two values may be the same if the event was created initially and has never been updated. If the event was updated prior to February 3, 2012, however, there is no way to determine if that was the case.

·       Other changes:

o   The change log for this documentation (this section) has been moved to the bottom of the document.

February 2, 2012 (Rev 7.41)

·       Object changes:

o   User – A recent release on the main web site introduced the ability to enter a birth date for user profiles and team-specific profiles from the Roster page. These new fields are now included in responses that return the User object. The new properties are as follows:

§  birthDate_month

§  birthDate_day

§  birthDate_year

August 10, 2011 (Rev 7.40)

·       Object changes:

o   Team:

§  Several properties were already in the API but were missing from the documentation and have now been added:

·       stateProvince

·       stateProvinceAbbrev

·       country

·       countryIso3

·       locationDisplayShort

·       locationDisplayLong

§  A new property, “options”, has been added to the Team object

·       Bug fix:

o   AttendanceListUserInfo – The “hasResponded” property was always returning “true” whether the user had responded or not. It now properly only returns “true” if the user has a valid RSVP present for the event.

July 29, 2011 (Rev 7.34)

·       Method changes:

o   Event_SaveRSVP – A change was made to the behavior of the addlMale and addlFemale method parameters. If these parameters are omitted from the method call, any existing values in the RSVP are preserved (i.e., values for additional players are not removed from the RSVP). To remove additional player values, include these parameters and pass values of 0 (zero).

July 23, 2011 (Rev 7.33)

·       Object changes:

o   RSVPInstance – this object was missing documentation for the rsvpDetails property. Documentation has been added for the missing property.

§  The rsvpDetails.allowedStatuses was misspelled as rsvpDetails.allowedStatues. The misspelled property will remain in the API but should be considered deprecated and will no longer be present in API responses after 1/1/2012.

June 18, 2011 (Rev 7.32)

·       Miscellaneous documentation edits (No functionality changes).

June 14, 2011 (Rev 7.31)

·       Miscellaneous documentation edits (No functionality changes).

June 9, 2011 (Rev 7.3)

·       API is officially out of BETA.

o   Nonce values are now enforced on API requests (in the BETA, Nonce checking was disabled)

o   Timestamp values are now enforced to ensure they are within 120 seconds of the server time (in the BETA, Timestamp range checking was effectively disabled). Be sure the system clock for the system making API calls has time set correctly.

May 3, 2011 (Rev 7.2)

·       Method changes:

o   Team_GetMessages – (Bug fix) This method returns an array of Message objects. The properties within the Message.postedBy object were not being set properly and values were not present.

o   User_GetTeamMessages – (Bug fix) This method returns an array of Message objects. The properties within the Message.postedBy object were not being set properly and values were not present.

·       Object changes:

o   Team – (Documentation fix) The Team.teamPhoto object properties were documented incorrectly as full, small, and thumb. They should have been fullUrl, smallUrl, and thumbUrl.

o   Event – (Documentation fix) The Event.dateTimeInfo object inPast and inFuture properties were being returned by the API but were missing from the documentation

o   Event – (Documentation fix) The Event.maleGenderDisplay and Event.femaleGenderDisplay properties were being returned by the API but were missing from the documentation

April 25, 2011 (Rev 7.1)

·       Object changes:

o   LinkedUser – (Documentation fix) The definition of the team simple object within the LinkedUser.teams array was missing the “name” property (it was being returned properly by the API but was missing from the documentation).

o   LinkedUser – (Bug fix) The definition of the team simple object within the LinkedUser.teams array includes a profilePhoto object. This object contains a “thumbUrl” property. The value of this property was improperly returning the thumbnail URL of the user when it should have been returning the thumbnail URL for the team.

March 11, 2011 (Rev 7.0)

·       Object changes:

o   TeamMemberType – The “”showTitleInAttList” property has been renamed to “showTitleOnAttList”. Also, two new properties were added: “showTeamMembersOnRoster” and “showTeamMembersOnAttList”

March 10, 2011 (Rev 6.0)

·       New objects:

o   ColorSwatchdefines a color swatch (e.g., a color swatch that is assigned to a team or opponent for an event)

·       Object changes:

o   EventshirtColors property is still an object with “team1” and “team2” properties, but the properties are now set to the new ColorSwatch object.

February 15, 2011 (Rev 5.0)

·       Method changes:

o   User_GetTeamsarray of teams returned is no longer indexed by teamI

o   User_GetTeamEventsarray of events returned is no longer indexed by eventId

o   User_GetTeamMessagesarray of messages returned is no longer indexed by messageId

o   Team_GetSeasonsarray of seasons returned is no longer indexed by seasonId

o   Team_GetEventsarray of events returned is no longer indexed by eventId

o   Team_GetRosterarray of team members returned is no longer indexed by userId

o   Team_GetMessagesarray of messages returned is no longer indexed by messageId

·       Object changes:

o   AttendanceList - "userssByStatus" property renamed to "usersIdsByStatus" and other indexing/structure changes (review documentation below for current object definition).

o   Message - comments property is still an array, but the array is no longer indexed by commentId

o   User - linkedUsers property (object) still has “linkedTo” and “linkedBy” properties which are arrays of users, but the array is no longer indexed by userId

February 14, 2011 (Rev 4.0)

·       New methods:

o   Team Methods:

§  Team_GetMessages()

§  Team_GetRoster()

o   Event Methods:

§  Event_Get()

§  Event_GetAttendanceList()

§  Event_SaveRSVP()

o   Message/Message Comment Methods:

§  Message_Get()

§  Message_Delete()

§  Message_Save()

§  MessageComment_Add()

§  MessageComment_Delete()

·       Method changes:

o   User Methods:

§  Added “sortDirection” parameter for User_GetTeamMessages()

o   New Objects:

§  AttendanceList - attendance list/RSVP information for a given event