getTeamsByInfo

Provides detailed information about a team.

Client ServletServer ServletHTTP Methods SupportedRequires Authentication
CRTeamraiserAPI SRTeamraiserAPI GET, POST Server.

Client API Syntax

https:// secure2.convio.net/organization /site/CRTeamraiserAPI ?method=getTeamsByInfo  &api_key=value  &v=value  [ &center_id=value ] [ &error_redirect=value ] [ &redirect=value ] [ &response_format=xml | json ] [ &sign_redirects=value ] [ &source=value ] [ &sub_source=value ] [ &success_redirect= ] [ &suppress_response_codes=value ] [ &creation_end_date=value ] [ &creation_start_date=value ] [ &event_type=value ] [ &event_type2=value ] [ &event_type3=value ] [ &first_name=value ] [ &fr_id=value ] [ &full_search=value ] [ &include_unreturned_teams=value ] [ &last_name=value ] [ &list_ascending=value ] [ &list_category_id=value ] [ &list_filter_column=value ] [ &list_filter_text=value ] [ &list_page_offset=value ] [ &list_page_size=value ] [ &list_record_offset=value ] [ &list_sort_column=value ] [ &public_event_type=value ] [ &screenname=value ] [ &team_company=value ] [ &team_company_id=value ] [ &team_division=value ] [ &team_id=value ] [ &team_name=value ]

Server API Syntax

https://secure2.convio.net/organization/site/SRTeamraiserAPI ?method=getTeamsByInfo  & api_key =value  & login_name =value  & login_password =value  & v =value  [ & center_id =value ] [ & response_format =xml |json ] [ & source =value ] [ & sub_source =value ] [ & suppress_response_codes =value ] [ & creation_end_date =value ] [ & creation_start_date =value ] [ & event_type =value ] [ & event_type2 =value ] [ & event_type3 =value ] [ & first_name =value ] [ & fr_id =value ] [ & full_search =value ] [ & include_unreturned_teams =value ] [ & last_name =value ] [ & list_ascending =value ] [ & list_category_id =value ] [ & list_filter_column =value ] [ & list_filter_text =value ] [ & list_page_offset =value ] [ & list_page_size =value ] [ & list_record_offset =value ] [ & list_sort_column =value ] [ & public_event_type =value ] [ & screenname =value ] [ & team_company =value ] [ & team_company_id =value ] [ & team_division =value ] [ & team_id =value ] [ & team_name =value ]

Usage Notes

This method returns a list of TeamRaiser teams. You can retrieve information for a single team specified in the team_id parameter, or retrieve a list of teams filtered by other parameters.

If you do not supply the team_id, you must include at least one of the following filter parameters:

  • company_name 
  • company_id 
  • event_type 
  • event_type2 
  • event_type3 
  • fr_id 
  • team_divsion 

Filters are conjoined using AND logic; the API returns the intersection of the filtered result sets.

Note: You must supply fr_id in order to retrieve performance data (amountRaised).

Note: Use the optional parameter include_unreturned_teams, to include unreturned teams from the previous, associated TeamRaiser. You must supply the fr_id of a TeamRaiser configured for recurring teams. Do not include any of the event_type or public_event_type filters.

This method returns data for teams associated with events that are Unpublished, Accepting Registrations Only, Accepting Registrations and Gifts, Accepting Gifts Only, or Closed. It does not return data for teams associated with Deleted or Archived events. If the associated event is not accepting registrations, the joinTeamURL element of the response document will be null. If the event is not accepting gifts, the teamDonateURL element will be null. Both elements will be null for Unpublished or Closed events.

Note: When searching on company, team, or team captain name, the search is a "contains" search, and is case insensitive. A search for first_name=jo will return participants with a First name of "Jon", "John", "Joan", etc.

To search by team captain, you must include a certain number of characters in order for the system to be able to perform the search. The default minimum characters comes from the Site Data Parameter F2F_PART_FINDER_MIN_CRITERIA. If that SDP is not set to a number, the search defaults to requiring a minimum of 3 characters. This minimum number of characters is applied to a combination of the first_name and last_name parameters.

Note: If the minimum characters is 3, then you must provide at least 3 characters total between the first_name and last_name parameters. A search for first_name=n &last_name=ng would be successful, but a search for first_name=n &last_name=n would generate an error.

Additionally, the list of Teams that is returned supports several parameters allowing finer control of the results, including additional filtering, pagination, and sorting.

Paginating the List takes two parameters: list_page_size, which specifies the number of results to be retrieved for that page. You must also provide one of the following two parameters:

  • list_page_offset: specifies which page of the results to retrieve. The first page of results has a list_page_offset of 0, page 2 has a list_page_offset of 1, and so on.
  • list_record_offset: specifies which record the page should start with. This also uses numbering from 0, so the first record has a list_record_offset of 0, the 2nd record has a list_record_offset of 1, and so on.

Filtering the List takes two parameters:

  • list_filter_column: name of the element to be filtered on.
  • list_filter_text: text that the element specified by list_filter_column must contain.

Note: list_filter_text performs an exact match, and is case sensitive.

Sorting the List takes two parameters:

  • list_sort_column: name of the element to be sorted by.
  • list_ascending: Boolean value indicating whether the sort should be in ascending order.

Note: You can paginate, filter, and sort the list all in one call.

Client API Parameters

Common Client Parameters

See topic Common Parameters.

creation_end_date

Optional. The end date of a date range in which to return participants who had a registration record created within the date range. Format the date as YYYY-MM-DD per ISO 8601 specifications, such as, 2022-09-30.

Type xsd:dateTime.

creation_start_date

Optional. The start date of a date range in which to return participants who had a registration record created within the date range. Format the date as YYYY-MM-DD per ISO 8601 specifications, such as, 2022-09-30.

Type xsd:dateTime.

event_type

Optional. The name of the Primary Event Type to limit search results to. Omit this parameter to search on all Primary Event Types. Defaults to null.

Type xsd:string.

event_type2

Optional. The name of the Event Type 2 to limit search results to. Omit this parameter to search on events with any Event Type 2. Defaults to null.

Type xsd:string.

event_type3

Optional. The name of the Event Type 3 to limit search results to. Omit this parameter to search on events with any Event Type 3. Defaults to null.

Type xsd:string.

first_name

Optional. Team Captain first name.

Type xsd:string.

fr_id

Optional. The TeamRaiser event ID.

Type xsd:nonNegativeInteger.

full_search

Optional. If TRUE, returns all events regardless of event status, otherwise returns only published events. Possible status values include: Unpublished = 0, Accepting Registrations Only = 1, AcceptingRegistrations and Gifts = 2, Accepting Gifts Only= 3, Closed = 4, Archived = 8, Deleted = 9.

Type xsd:boolean.

include_unreturned_teams

Optional. If true, returns previous teams which have not been reformed for a given Teamraiser.

Type xsd:boolean.

Default is false.

last_name

Optional. Team Captain last name.

Type xsd:string.

list_ascending

Optional. Whether the list should be sorted in ascending order.

Type xsd:boolean.

Default is true.

list_category_id

Optional. Security Category filter.

Type xsd:integer.

list_filter_column

Optional. The database column that will be used to match the filter text (used with "list_filter_text").

Type xsd:string.

list_filter_text

Optional. The text that will be used to filter results.

Type xsd:string.

list_page_offset

Optional. The requested page number (used with "list_page_size"). The first page (default) is zero. Only one of "list_record_offset" or "list_page_offset" should be used in a request.

Type xsd:integer.

list_page_size

Optional. The number of results in each page (used with "list_record_offset" or "list_page_offset").

Type xsd:integer.

Default is 25.

list_record_offset

Optional. The requested initial record number (used with "list_page_size"). The first record (default) is zero. Only one of "list_record_offset" or "list_page_offset" should be used in a request.

Type xsd:integer.

list_sort_column

Optional. The column to sort with (used with "list_ascending").

Type xsd:string.

public_event_type

Optional. The case-sensitive name of the Public Event Type to limit search results to. Omit this parameter to search on events with any Public Event Type. Defaults to null.

Type xsd:string.

screenname

Optional. Team Captain screen name.

Type xsd:string.

team_company

Optional. The name of the team company.

Type xsd:string.

team_company_id

Optional. The id of the team company.

Type xsd:nonNegativeInteger.

team_division

Optional. The team division.

Type xsd:string.

team_id

Optional. A unique team ID.

Type xsd:nonNegativeInteger.

team_name

Optional. A unique team name.

Type xsd:string.

Server API Parameters

Common Server Parameters

See topic Common Parameters.

creation_end_date

Optional. The end date of a date range in which to return participants who had a registration record created within the date range. Format the date as YYYY-MM-DD per ISO 8601 specifications, such as, 2022-09-30.

Type xsd:dateTime.

creation_start_date

Optional. The start date of a date range in which to return participants who had a registration record created within the date range. Format the date as YYYY-MM-DD per ISO 8601 specifications, such as, 2022-09-30.

Type xsd:dateTime.

event_type

Optional. The name of the Primary Event Type to limit search results to. Omit this parameter to search on all Primary Event Types. Defaults to null.

Type xsd:string.

event_type2

Optional. The name of the Event Type 2 to limit search results to. Omit this parameter to search on events with any Event Type 2. Defaults to null.

Type xsd:string.

event_type3

Optional. The name of the Event Type 3 to limit search results to. Omit this parameter to search on events with any Event Type 3. Defaults to null.

Type xsd:string.

first_name

Optional. Team Captain first name.

Type xsd:string.

fr_id

Optional. The TeamRaiser event ID.

Type xsd:nonNegativeInteger.

full_search

Optional. If TRUE, returns all events regardless of event status, otherwise returns only published events. Possible status values include: Unpublished = 0, Accepting Registrations Only = 1, AcceptingRegistrations and Gifts = 2, Accepting Gifts Only= 3, Closed = 4, Archived = 8, Deleted = 9.

Type xsd:boolean.

include_unreturned_teams

Optional. If true, returns previous teams which have not been reformed for a given Teamraiser.

Type xsd:boolean.

Default is false.

last_name

Optional. Team Captain last name.

Type xsd:string.

list_ascending

Optional. Whether the list should be sorted in ascending order.

Type xsd:boolean.

Default is true.

list_category_id

Optional. Security Category filter.

Type xsd:integer.

list_filter_column

Optional. The database column that will be used to match the filter text (used with "list_filter_text").

Type xsd:string.

list_filter_text

Optional. The text that will be used to filter results.

Type xsd:string.

list_page_offset

Optional. The requested page number (used with "list_page_size"). The first page (default) is zero. Only one of "list_record_offset" or "list_page_offset" should be used in a request.

Type xsd:integer.

list_page_size

Optional. The number of results in each page (used with "list_record_offset" or "list_page_offset").

Type xsd:integer.

Default is 25.

list_record_offset

Optional. The requested initial record number (used with "list_page_size"). The first record (default) is zero. Only one of "list_record_offset" or "list_page_offset" should be used in a request.

Type xsd:integer.

list_sort_column

Optional. The column to sort with (used with "list_ascending").

Type xsd:string.

public_event_type

Optional. The case-sensitive name of the Public Event Type to limit search results to. Omit this parameter to search on events with any Public Event Type. Defaults to null.

Type xsd:string.

screenname

Optional. Team Captain screen name.

Type xsd:string.

team_company

Optional. The name of the team company.

Type xsd:string.

team_company_id

Optional. The id of the team company.

Type xsd:nonNegativeInteger.

team_division

Optional. The team division.

Type xsd:string.

team_id

Optional. A unique team ID.

Type xsd:nonNegativeInteger.

team_name

Optional. A unique team name.

Type xsd:string.

Response

See topic HTTP Status Codes.

XML response
            
            
                    1
                    
                    Sample Team Name
                    15850
                    50000
                    12345
                    1001001
                    Earl
                    Campbell
                    The Tyler Rose
                    false
                    1000
                    Blackbaud
                    7
                    South Central
                    false
                    false
                    12345
                    0
                    http://blackbaud.com/goto/myTeam
                    http://convio.com/site/TRR/ABC/General/2053821550?pg=tfind&fr_id=1000&fr_tjoin=1003
                    
                    
                    1000
                    Austin fun run
                    http://convio.com/site/TRR/ABC/General/2053821550?pg=team&fr_id=1000&team_id=1003
                    0
                
            
        
JSON response
            {"getTeamSearchByInfoResponse":{
                "totalNumberResults":"1","team":{
                    "joinTeamURL":"http://convio.com/site/TRR/ABC/General/2053821550?pg=tfind&fr_id=1000&fr_tjoin=1003",
                    "companyName":"Blackbaud",
                    "divisionName":"South Central",
                    "captainScreenname":"The Tyler Rose",
                    "isCaptainAnon":"false","numMembers":"7",
                    "isHonoraryTeam":"false",
                    "teamDonateURL":null,
                "redirectShortcutURL":"http://blackbaud.com/goto/myTeam",
                "EventId":"1000",
                "eventName":"Austin fun run",
                "id":"12345",
                "captainConsId":"1001001",
                "goal":"50000",
                "teamEcommerceURL":null,
                "amountRaised":"15850",
                "captainFirstName":"Earl",
                "maxTeamSize":"0",
                "companyId":"1000",
                "requiresPassword":"false",
                "name":"Sample Team Name",
                "previousTeamId":"0",
                "captainLastName":"Campbell",
                "originalTeamId":"12345",
                "teamPageURL":"http://convio.com/site/TRR/ABC/General/2053821550?pg=team&fr_id=1000&team_id=1003"
                }
            }}
        

Examples

To perform a search for all teams with a team captain named "Jane" and the company name "Blackbaud" in any event:

            https://secure2.convio.net/myorg/site/CRTeamraiserAPI?method=getTeamsByInfo&api_key=MyAPIKey&v=1.0&first_name=Jane&company_name=Blackbaud
        

To search the event with fr_id=1000, looking for teams with a first name containing "J", the last name containing "Doe", and to retrieve the first page of results, displaying 10 results per page:

            https://secure2.convio.net/myorg/site/CRTeamraiserAPI?method=getTeamsByInfo&api_key=MyAPIKey&v=1.0&fr_id=1000&team_name=j&list_page_size=10&list_page_offset=0
        

Comments

Submitted by Dax at 06:11 PM on September 29, 2013
You guys really need to specify what the actual names of the reference columns are for use in the "list_sort_column" and "list_filter_column" fields. It's currently not clear at all what fields can be used and what they should be named. For instance, if I try to run getTeamsByInfo and use set "list_sort_column" to "name", I get an error response code: 1 in the response. If I set it to "team_name" however, everything is returned as expected. Incongruously, if I set "list_sort_column" to "team_goal", I get an error response code: 1, but when I set it to "goal", everything again is returned as expected. The behavior is inconsistent, and making these calls is a lot like poking around in the dark with a stick. I've still yet to "guess" what the appropriate name for "amountRaised" is supposed to be. Help would be appreciated!

Leave a Comment

Nickname
Comment
Enter this word: