createOrUpdate

This method provides a convenience wrapper around the Convio Client create and update APIs. When called, this method will first try to locate* and update an existing record, and if no existing record can be found, will create a new record. See the create and update documentation for further detailed discussion of those APIs. Use this method 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.

*Notes:

If the cons_id is included and a match is found, the record is updated. If no match is found, then nothing further is done (no new record is created).
If the record is requested by a search of member ID or email address and is not found, then a new record is created as by the create method.
If a match is found for the member_id, and there is only one match, then the record is updated; if more than one record is matched, an error is returned.
If a match is found for primary_email, and there is only one match, the record is updated; if more than one record is matched, and:
- If the site is configured to enforce unique email, then an error is returned.
- If enforce unique email is not enabled, then a new record is created.

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

This method accepts all parameters accepted by the update and create methods. These parameters include the constituent record fields (which are customizable for each organization)* plus the following:

Name	Description
api_key	Required. Contact Convio to obtain the value to send.
v	Required. API version to invoke. Must be "1.0".
method	Required. Specifies which method to perform.
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 redirect to send back to the browser after processing.
cons_id	The internal constituent ID of the user.
member_id	The external member ID of the user.
primary_email	Required to create a record. The email address of the user.
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.
source	Text to associate with the record to identify how or from where the record was added.
no_welcome	Specifies whether to send a "welcome" auto-responder email to the new user. If the value is "f" or "false" (ignoring case) and the site is configured to send welcome auto-responders to new users, then one will be sent.

* The constituent record fields that can be set by the caller can be retrieved using the listUserFields API method.

** Changed 3/27/08. This parameter is only available when making server-side API calls for security purposes.

Code Examples

AJAX Two-Step Registration Form - this example provides step by step instructions to create a two-step registration form from within a Convio powered page. Cick the link to see an example and find instructions for implementing on your site.

Response

Success

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 return might look like the following:

XML format:

<createConsResponse 
  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>New user added.</message> 
</createConsResponse>

JSON format:

{"createOrUpdateConsResponse ":{
"message":"New user added.","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: