getGroupMembers

This method returns the constituents in a group when called from another application or server. It is only available when called using an administrator account.

Post URL

Deconstructing the URL
* In most cases secure2.convio.net matches a client's secure domain. However, in some cases this will be different. If your organization uses Convio for fundraising, the correct secure domain for the API is identical to the secure domain for your fundraising forms. So if the sample above does not work, look for the unique secure domain used for your organization and replace the secure2.convio.net portion above with this URL.

*Here, organization is a client's unique identifier in the Convio system. Every client has a unique value that represents their instance of the product. If you're organization uses a custom secure URL for donations, the organization portion of the URL may not be necessary, contact support for assistance.

Example: https://demo-secure.convio.net/demo829/site/SRConsAPI. Here you'll notice that demo-secure.convio.net is used for the domain, and demo829 is used for the organization.

Authentication

Authenticating Convio Server API calls is a three-stage process. First, the IP address of the server invoking the API call will be checked against the list of allowed IP ranges, per the Convio Site Configuration parameters. If the API is being invoked from a server in the allowed IP range, then the login_name and login_password parameters will be used to authenticate with the Convio site. Finally, once the login credentials have been verified, the account specified by the login credentials will be examined to ensure that it has the Contact Management “Use Convio API” permission. If all the above hold, the caller will be authenticated and the API call will proceed. If any of the above fail, then the call will not be authenticated and an error message will be returned.

Parameters

The following parameters for this method include the following:

Name	Description
api_key	Required. An arbitrary value that must be passed when invoking the Convio Client and Server APIs. The value passed by the caller must match the value in the CONVIO_API_KEY site configuration parameter, which is unique for each Convio site.
v	Required. API version to invoke. Must be "1.0".
method	Required. Specifies which method to perform. To invoke this method use the value “getGroupMembers”.
response_format	Optional. Specifies the format in which to return the response. Can be either "xml" (the default value) or "json".
login_name	Required. Specifies the user name of the account to authenticate. If either login_name or login_password is not specified, then authentication is done solely by looking for a session cookie.
login_password	Required. Specifies the password of the account to authenticate.
group_id	Required. The ID of the group for which to return the members.
max_number	Optional. Specifies the maximum number of members to return. Note: to maintain performance standards Convio may limit returns to a value less than specified with this parameter, resulting in fewer results than expected.
fields	Optional. Specifies a comma-separated list of names of fields to retrieve for each member. If not specified, then the name, address, email address, and constituent and member IDs are returned if they are in use and visible to the caller. Use "dot" notation to refer to nested elements of the XML schema. For example, use "name.first" to request the "first" element of the "name" element (the user's first name).

Response

Success

The HTTP status code of 200 indicates a successful invocation. The response is formatted as XML by default, but the response_format input parameter can be used to specify either XML or JSON formatting. For example:

XML format:

<getConsGroupsResponse 
  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">
      <total_number>46</total_number>
      <number_returned>40</number_returned>
      <member>
        <cons_id>1001006</cons_id>
        <member_id>M0031189</member_id>
        <name>
        <first>John</first>
        <last>Bigboote</last>
        </name>
        <primary_address>
          <street1 xsi:nil="true"/>
          <city>Grovers Mills</city>
          <state>NJ</state>
          <zip>08561</zip>
        </primary_address>
        <email>
          <primary_address>devnull+bigboote@convio.com</primary_address>
        </email>
      </member>
      <member>
      ...
      </member>
</getConsGroupsResponse>

JSON format:

{"getGroupMembersResponse": {"member":[ {"member_id":"M0031189", 
"primary_address":{"street1":null,"state":"NJ","zip":"08561",
"city":"Grovers Mills"},"cons_id":"1001006", "email":
{"primary_address":devnull+bigboote@convio.com}, 
"name":{"last":"Bigboote","first":"John"}}, ...}

Elements of the response include:

total_number: the total number of members in the group
number_returned: the number of member records returned in this response. This may be less than the "total_number" if any of the following are true:
- The total number of members of the group is more than the maximum number specified by the "max_number" request parameter.
- The total number of members of the group is more than the maximum number allowed by the API for performance reasons.
- The caller does not have permission to view some of the members' records.
member: each "member" element describes a constituent who is a member of the group. In the JSON format, the "member" field is an array.

Error

If an error occurs during processing, the structure of the response is an "errorResponse" element. It contains two other elements: a "code" element and a "message" element. The "code" element contains a number corresponding to the error conditions documented on the error list page. The "message" element contains a text message that may provide further detail about the error. For example:

XML format:

<errorResponse 
  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">
<code>16</code>
<message>The specified group does not exist.</message>
</errorResponse>

JSON format:

{"errorResponse":{"code":"16",
"message":"The specified group does not exist."}}

See the complete list of HTTP Status codes and Error codes for calling from another application.

Client Community
Log in to chat with other clients and partners using APIs and share code snippets.