update

This method updates an existing user record and returns the record's unique identifier. Use this method to update an existing user record when calling from a Web Client. 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 list of constituent record fields that can be updated is customizable for each organization and is different for administrative and non-administrative users. The fields that can be updated by the caller can be retrieved using the listUserFields API method.

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 "update"
response_format	Optional. Specifies the format in which to return the response. Can be either "xml" (the default value) or "json".
cons_id	The internal constituent ID of the user. Restrictions: Only available when called using administrator accounts.
member_id	The external member ID of the user. Restrictions: Only available when called using administrator accounts.
primary_email	The email address of the user. Restrictions: Only available when called using administrator accounts.
add_center_ids	Comma-separated list of numeric IDs of centers to add the user to.
add_group_ids	Comma-separated list of numeric IDs of groups to add the user to. Restrictions: Only available when called using administrator accounts. Cannot be used for pre-defined groups (those with an ID less than 1000) Cannot be used for administrator security groups.
add_interest_ids	Comma-separated list of numeric IDs of email interests to add the user to.
remove_center_ids	Comma-separated list of numeric IDs of centers to remove the user from.
remove_group_ids	Comma-separated list of numeric IDs of groups to remove the user from. Restrictions: Only available when called using administrator accounts. Cannot be used for pre-defined groups (those with an ID less than 1000) Cannot be used for administrator security groups.
remove_interest_ids	Comma-separated list of numeric IDs of email interests to remove the user from.

If the requester is an administrator, then one of cons_id, member_id, or primary_email must be specified in order to locate the record to update.

If cons_id is given, then it is the only thing used to search.
If cons_id is absent and member_id is given, then it is the only thing used to search.
- If one record matches member_id, it is updated (including changing its email address if email is also included – if the email matches a different record and the site does not allow duplicate emails, then there will be an error).
- If multiple records match member_id, then this is an error and no record is updated.
- If no records match member_id, then primary_email is searched. If exactly one match is found, then that record is updated. If that record does not have a member ID on it, then the record is updated with the member ID in the request.
If cons_id and member_idare absent, then primary_email is searched and a record is updated if exactly one match is found.

If the requester is not an administrator, then the requester's own record is updated regardless of what cons_id is specified. If member_id or primary_email are specified, then they will become the new values of the requester's record.

Code Examples

Javascript with HTML (right click and select 'Save Target' or 'Save Link' As...)

Response

Success

A successful invocation sends either a URL redirect (if the redirect parameter was specified) or an identifier for the new record is returned. 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. For example:

XML format:

<updateUserResponse
  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>1002001</cons_id>
<message>User updated.</message>
</updateUserResponse>

JSON format:

{"updateConsResponse ":{"message":"User updated.","cons_id":"1002001"}}

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: