getParticipants

Provides a list of TeamRaiser participants in the specified TeamRaiser event or events of the specified Event Type with details about the participant, team, event, goals, and progress. Add optional parameters to focus, filter, and sort the resulting list.

Client Servlet	Server Servlet	HTTP Methods Supported	Requires Authentication
CRTeamraiserAPI	SRTeamraiserAPI	GET, POST	Server.

Client API Syntax

https://secure2.convio.net/organization/site/CRTeamraiserAPI?method=getParticipants &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=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 ] [ &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 ] [ &modify_end_date=value ] [ &modify_start_date=value ] [ &public_event_type=value ] [ &registration_end_date=value ] [ &registration_start_date=value ] [ &screenname=value ] [ &team_id=value ] [ &team_name=value ]

Server API Syntax

https://secure2.convio.net/organization/site/SRTeamraiserAPI?method=getParticipants & 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 ] [ & 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 ] [ & modify_end_date =value ] [ & modify_start_date =value ] [ & public_event_type =value ] [ & registration_end_date =value ] [ & registration_start_date =value ] [ & screenname =value ] [ & team_id =value ] [ & team_name =value ]

Usage Notes

This method may take up to 15 minutes following registration to return all pertinent data for a newly registered participant.

Search

This method only returns information for active TeamRaisers, events, and participants unless you include full_search=TRUE in the call. Participant status is always active by default but can be manually changed to inactive by an administrator. An active event accepts gifts, accepts registrations, or accepts gifts and registrations.

The server call can be made with only the fr_id or event_type parameter and returns all participants associated with that TeamRaiser. The client call must include fr_id or event_type and at least one of the following values: first_name, last_name, team_name, or screenname. The client call returns results specific to the participant or team matching these values.

Use optional participant, team, and event parameters in client or server calls to search for specific participants. The search requires a minimum of three characters. Matches are based on results containing the search term and does not require the data begin with the search term. The three required characters may be split between first and last name parameters. For example, first_name=mi last_name=j is a valid set of search parameters that return both Michael Johnson and Emily Wojcik.

You can use the Site Data Parameter F2F_PART_FINDER_MIN_CRITERIA to change minimum character requirement.

Paginating the List

The list_page_size parameter specifies the number of results to be retrieved for that page. If you omit this parameter, the default value of 25 will be used. One of the following two offset parameters is required for pagination.

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

Use the list_filter_text parameter to remove all data containing specific text from the resulting list. This requires an exact text match and is case sensitive.

Use list_filter_text with list_filter_column to only remove data containing specific text in a specific field.

Sorting the List

Use the list_sort_column parameter to set the element to be sorted by. Use the list_ascending parameter to set the sorting order.

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. Constituent 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.

last_name

Optional. Constituent 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.

modify_end_date

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

Type xsd:dateTime.

modify_start_date

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

Type xsd:dateTime.

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.

registration_end_date

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

Type xsd:dateTime.

registration_start_date

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

Type xsd:dateTime.

screenname

Optional. Constituent screen name.

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

Type xsd:dateTime.

creation_start_date

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. Constituent first name.

Type xsd:string.

fr_id

Optional. The TeamRaiser event ID.

Type xsd:nonNegativeInteger.

full_search

Type xsd:boolean.

last_name

Optional. Constituent 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.

modify_end_date

Type xsd:dateTime.

modify_start_date

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

Type xsd:dateTime.

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.

registration_end_date

Type xsd:dateTime.

registration_start_date

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

Type xsd:dateTime.

screenname

Optional. Constituent screen name.

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


<?xml version="1.0" encoding="UTF-8"?>
<getParticipantsResponse xsi:schemaLocation="http://convio.com/crm/v1.0 http://service.convio.net/xmlschema/crm.public.v1.xsd" xmlns="http://convio.com/crm/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <totalNumberResults>3</totalNumberResults>
  <participant>
    <name>
      <first>Participant</first>
      <last>Sample01</last>
    </name>
    <aTeamCaptain>false</aTeamCaptain>
    <teamId xsi:nil="true"/>
    <teamName/>
    <donationUrl>http://example.com/donateurl</donationUrl>
    <personalPageUrl>http://example.com/personalpageurl</personalPageUrl>
    <teamPageUrl/>
    <consId>1001000</consId>
    <personalPagePrivate>false</personalPagePrivate>
    <amountRaised>5180</amountRaised>
    <goal>105060</goal>
    <eventName>Event 1000</eventName>
    <eventId>1000</eventId>
  </participant>
  <participant>
    <name>
      <first>Participant</first>
      <last>Sample11</last>
    </name>
    <aTeamCaptain>false</aTeamCaptain>
    <teamId xsi:nil="true"/>
    <teamName/>
    <donationUrl>http://example.com/donateurl</donationUrl>
    <personalPageUrl>http://example.com/personalpageurl</personalPageUrl>
    <teamPageUrl/>
    <consId>1001001</consId>
    <personalPagePrivate>false</personalPagePrivate>
    <amountRaised>5181</amountRaised>
    <goal>105061</goal>
    <eventName>Event 1001</eventName>
    <eventId>1001</eventId>
  </participant>
  <participant>
    <name>
      <first>Participant</first>
      <last>Sample21</last>
    </name>
    <aTeamCaptain>true</aTeamCaptain>
    <teamId>1002</teamId>
    <teamName>Sample Team Name</teamName>
    <donationUrl>http://example.com/donateurl</donationUrl>
    <personalPageUrl>http://example.com/personalpageurl</personalPageUrl>
    <teamPageUrl>http://example.com/teampageurl</teamPageUrl>
    <consId>1001002</consId>
    <personalPagePrivate>false</personalPagePrivate>
    <amountRaised>5182</amountRaised>
    <goal>105062</goal>
    <eventName>Event 1002</eventName>
    <eventId>1002</eventId>
  </participant>
</getParticipantsResponse>

JSON response

{"getParticipantsResponse":{"totalNumberResults":"3","participant":[{"teamName":{},"eventId":"1000","goal":"105060","personalPagePrivate":"false","amountRaised":"5180","donationUrl":"http://example.com/donateurl","aTeamCaptain":"false","consId":"1001000","teamId":null,"name":{"last":"Sample01","first":"Participant"},"eventName":"Event 1000","personalPageUrl":"http://example.com/personalpageurl","teamPageUrl":{}},{"teamName":{},"eventId":"1001","goal":"105061","personalPagePrivate":"false","amountRaised":"5181","donationUrl":"http://example.com/donateurl","aTeamCaptain":"false","consId":"1001001","teamId":null,"name":{"last":"Sample11","first":"Participant"},"eventName":"Event 1001","personalPageUrl":"http://example.com/personalpageurl","teamPageUrl":{}},{"teamName":"Sample Team Name","eventId":"1002","goal":"105062","personalPagePrivate":"false","amountRaised":"5182","donationUrl":"http://example.com/donateurl","aTeamCaptain":"true","consId":"1001002","teamId":"1002","name":{"last":"Sample21","first":"Participant"},"eventName":"Event 1002","personalPageUrl":"http://example.com/personalpageurl","teamPageUrl":"http://example.com/teampageurl"}]}}

Examples

To perform an search for all participants named "Jane" in the TeamRaiser Event with the fr_id=1010:

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=MyAPIKey&v=1.0&method=getParticipants&first_name=jane&fr_id=1010

Searching the event with fr_id=1010, looking for participants with a first name containing "J", a last name containing "Doe", and only retrieving the first page of results, displaying 10 results per page:

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?method=getParticipants&api_key=ACSAPI&response_format=xml&v=1.0&fr_id=1000&first_name=j&last_name=doe&list_page_size=10&list_page_offset=0

Comments

Submitted by CMad at 12:12 PM on October 1, 2014

This documentation contains conflicting information. The FR_ID is listed as optional as a parameter but the usage notes seem to indicate it is only run on a per TeamRaiser basis. Testing with no FR_ID present returns an error

Submitted by GoSensGo at 08:59 PM on April 6, 2012

amountRaised is not returned in the first example.

Luminate Online

getParticipants

Client API Syntax

Server API Syntax

Usage Notes

Client API Parameters

Server API Parameters

Response

Examples

Comments

Leave a Comment