getCompaniesByInfo

Provides detailed information about a company.

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

Client API Syntax

https://secure2.convio.net/organization/site/CRTeamraiserAPI?method=getCompaniesByInfo &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 ] [ &company_id=value ] [ &company_name=value ] [ &event_type=value ] [ &fr_id=value ] [ &include_cross_event=value ] [ &list_ascending=value ] [ &list_category_id=value ] [ &list_filter_column=company_name | total | fr_id | company_id | coordinator_cons_id | goal | national | regional | classification_name ] [ &list_filter_text=value ] [ &list_page_offset=value ] [ &list_page_size=value ] [ &list_record_offset=value ] [ &list_sort_column=company_name | total | fr_id | company_id | coordinator_cons_id | goal | national | regional | classification_name ]

Usage Notes

This method requires that you provide at least one of the following parameters:
  • fr_id
  • company_id
  • company_name
  • event_type
Note: Only active, participating companies are returned. Prospect or Sponsor-only companies will not be returned.
Note: When searching by company_name or event_type, you must supply a minimum number of characters to search on. Default is 3, but this may be set by the Site Data Parameter F2F_PART_FINDER_MIN_CRITERIA.

Amounts and Counts

The Amount field will only be included in the response in the following conditions:
  • The request included the fr_id parameter or the company_id parameter and the company is a Local Company.
  • The request included the fr_id parameter, the include_cross_event parameter set to true, and the company is a National or Regional Company.
The way amounts are displayed in status indicators may vary from event to event based on the event configuration. A calculated amount for cross-event companies respecting that configuration is not available at this time.

For Cross-Event Companies, if you specify the fr_id the teamCount and participantCount fields in the response will be limited to that teams and participants associated to that company in the specified TeamRaiser event. If you do not specify the fr_id, the teamCount and participantCount will be the count of all teams and participants associated to that National or Regional Company across all the TeamRaiser events that National or Regional Company is associated with.

Client API Parameters

Common Client Parameters

See topic Common Parameters.

company_id

Optional. The id of the company.

Type xsd:nonNegativeInteger.

company_name

Optional. The public name of the company.

Type xsd:string.

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.

fr_id

Optional. The TeamRaiser event ID.

Type xsd:nonNegativeInteger.

include_cross_event

Optional. Tells us if we want to make sure to include Cross-Event Companies in our queries

Type xsd:boolean.

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.

Options are:
  • company_name
  • total
  • fr_id
  • company_id
  • coordinator_cons_id
  • goal
  • national
  • regional
  • classification_name
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.

Options are:
  • company_name
  • total
  • fr_id
  • company_id
  • coordinator_cons_id
  • goal
  • national
  • regional
  • classification_name

Response

See topic HTTP Status Codes.

XML response 
<?xml version="1.0" encoding="UTF-8"?>
<getCompaniesResponse 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>
  <company>
    <eventId>1000</eventId>
    <companyId>2000</companyId>
    <companyName>sampleCompany0</companyName>
    <eventType>eventType0</eventType>
    <coordinatorId>1000</coordinatorId>
    <goal>4000</goal>
    <amountRaised>5000</amountRaised>
    <companyURL>www.blackbaud.com0</companyURL>
    <companyType>National</companyType>
    <teamCount>813</teamCount>
    <participantCount>985</participantCount>
  </company>
  <company>
    <eventId>1001</eventId>
    <companyId>2001</companyId>
    <companyName>sampleCompany1</companyName>
    <eventType>eventType1</eventType>
    <coordinatorId>1001</coordinatorId>
    <goal>4001</goal>
    <amountRaised>5001</amountRaised>
    <companyURL>www.blackbaud.com1</companyURL>
    <companyType>National</companyType>
    <teamCount>398</teamCount>
    <participantCount>895</participantCount>
  </company>
  <company>
    <eventId>1002</eventId>
    <companyId>2002</companyId>
    <companyName>sampleCompany2</companyName>
    <eventType>eventType2</eventType>
    <coordinatorId>1002</coordinatorId>
    <goal>4002</goal>
    <amountRaised>5002</amountRaised>
    <companyURL>www.blackbaud.com2</companyURL>
    <companyType>National</companyType>
    <teamCount>46</teamCount>
    <participantCount>796</participantCount>
  </company>
</getCompaniesResponse>
JSON response 
{"getCompaniesResponse":{"company":[{"eventId":"1000","companyURL":"www.blackbaud.com0","amountRaised":"5000","participantCount":"359","companyType":"National","eventType":"eventType0","companyId":"2000","companyName":"sampleCompany0","teamCount":"125","goal":"4000","coordinatorId":"1000"},{"eventId":"1001","companyURL":"www.blackbaud.com1","amountRaised":"5001","participantCount":"250","companyType":"National","eventType":"eventType1","companyId":"2001","companyName":"sampleCompany1","teamCount":"861","goal":"4001","coordinatorId":"1001"},{"eventId":"1002","companyURL":"www.blackbaud.com2","amountRaised":"5002","participantCount":"906","companyType":"National","eventType":"eventType2","companyId":"2002","companyName":"sampleCompany2","teamCount":"142","goal":"4002","coordinatorId":"1002"}],"totalNumberResults":"3"}}

Examples

To retrieve local companies associated with a TeamRaiser with an event ID (fr_id) of 1000: 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=api_key&v=1.0&method=getCompaniesByInfo&fr_id=1000

To retrieve local companies and cross-event companies associated with a TeamRaiser with an event ID (fr_id) of 1000: 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=api_key&v=1.0&method=getCompaniesByInfo&fr_id=1000&include_cross_event=true

To retrieve details of a local company with a local company ID (company_id) of 1000 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=api_key&v=1.0&method=getCompaniesByInfo&company_id=1000

To retrieve details of a national company with a national company ID (company_id) of 1000: 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=api_key&v=1.0&method=getCompaniesByInfo&company_id=1000&include_cross_event=true

Note that if you do not include &include_cross_event=true in the above example, the call only returns a count of companies that match the criteria, and does not include details of the national company. Including include_cross_event=true does not return the Amount field when the fr_id is not provided. The teamCount and participantCount would include all teams and participants across all events.

Include the event ID (fr_id) to retrieve the amount of money raised by the company. The amountRaised includes offline cash and check donations given directly to the national company. Including fr_id also changes the teamCount and participantCount to only count teams and participants within that TeamRaiser. 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=api_key&v=1.0&method=getCompaniesByInfo&fr_id=1000&company_id=1000&include_cross_event=true

To search for companies where "National" appears in the company name: 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=api_key&v=1.0&method=getCompaniesByInfo&company_name=National
Note: If you have 2 Cross-Event Companies with "National" in their name and one Local company with "National" in the name, this will return a count of 3 but only include the details of the Local Company.

Fixing the above and searching for companies where "National" appears in the company name and retrieve the details of all 3 companies: 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=api_key&v=1.0&method=getCompaniesByInfo&company_name=National&include_cross_event=true

Searching for Companies in the event type of "Walkfest": 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=api_key&v=1.0&method=getCompaniesByInfo&event_type=Walkfest
Note: Since local companies cannot be associated to event types, this will return a count of the cross-event companies associated to "Walkfest", but will not include the details of those companies.

Fixing the above to return the company details for Cross-Event Companies in the event type of "Walkfest": 

https://demo-secure.convio.net/demo829/site/CRTeamraiserAPI?api_key=api_key&v=1.0&method=getCompaniesByInfo&event_type=Walkfest&include_cross_event=true
Parent topic: TeamRaiser API
Previous topic: getCaptainsMessage
Next topic: getCompanyDonationByDay

Leave a Comment

Nickname
Comment
Enter this word:
Change