getUser

This method returns a constituent record. Use this method when calling from another application or server.  Please review the authentication and security guidance before using this or any other API method available in the site configuration.

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/CRConsAPI.  Here you'll notice that demo-secure.convio.net is used for the domain, and demo829 is used for the organization. 

Authentication

The caller must be logged in to the Convio site. Furthermore, to prevent certain scripting attacks, the call must include a special authentication token to verify that the call is from a trusted host. Currently, this token can only be included when making the call from a page served by the Convio system.

Learn about the Authentication Token on the configuration page.

Parameters

The definition of all constituent record fields that can be retrieved is defined in an XML Schema document (crm.public.v1.xsd). However, many of those fields might not be in use for the site and some of them might not be visible to the user requesting the record. Use the listUserFields API method to list the fields that can be retrieved.

The following parameters also apply:

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 “getUser”.

response_format

Optional. Specifies the format in which to return the response. Can be either "xml" (the default value) or "json".

redirect Optional. Specifies a URL to which to redirect after processing.

fields

Optional. Specifies a comma-separated list of names of fields to retrieve. If not specified, then all fields in use and visible to the caller are returned. 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 is 200. The response is formatted as XML by default, but the response_format input parameter can be used to specify either XML or JSON formatting. A successful invocation might appear as follows:

XML format: 
<getConsResponse 
  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">


<cons_id>1001172</cons_id>
<name>
   <title xsi:nil="true"/>
   <first>Zaphod</first>
   <last>Beeblebrox</last>
</name>
<email>
   <primary_address>zaphod@convio.com</primary_address>
</email>


</getConsResponse>

 

JSON format: 
{"getConsResponse":{"cons_id":"1001172",
"email":{"primary_address":zaphod@convio.com}, 
"name":{"last":"Beeblebrox","title":null,"first":"Zaphod"}}}

 

Notes:

  • If a field is not included in the response, it is either not enabled for the site or it is invisible to the caller.
  • If the field is included but has no value (xsi:nil="true" in an XML response or null in a JSON response), then the field is visible and has a null value for the retrieved record.
  • If a composite element (one that can contain nested elements), such as "name" or "email" in the example above, is nil then all of its contained fields are either disabled or have nil values for this record.

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 user does not exist.</message>


</errorResponse>

 

JSON format: 
{"errorResponse":{"code":"16",
"message":"The specified user 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.

Community