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 another application or server.

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

Authentication

The calling server initially establishes trust by checking its IP address against the list of allowed servers specified in the configuration of the API for the site. The server then specifies the login_name and login_password parameters with each API call to methods requiring authentication. These login credentials can be for an administrative account having broad permission to manage constituent records or they can be for the constituent record being accessed.

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".

login_name

Optional. Specifies the user name of the account to authenticate. If either login_name or login_password are not specified, then authentication is done solely by looking for a session cookie.

login_password

Optional. Specifies the password of the account to authenticate.

cons_id

The internal constituent ID of the user.

member_id

The external member ID of the user.

primary_email

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.

 

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: 
<createOrUpdateConsResponse 
  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 there is an error, the response contains an error code and message that may help explain the reason for the failure. 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>12</code>


  <message>Specified user name is already in use.</message>


</errorResponse>

 

JSON format: 
{"errorResponse":{"code":"12","message":
"Specified user name is already in use."}}

 

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