createOrUpdate

This method provides a convenience wrapper around the 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.

Client ServletServer ServletHTTP Methods SupportedRequires Authentication
CRConsAPI SRConsAPI POST Yes.

Client API Syntax

https://secure2.convio.net/organization/site/CRConsAPI?method=createOrUpdate &api_key=value &v=value [ &auth=value ] [ &center_id=value ] [ &error_redirect=value ] [ &redirect=value ] [ &response_format=xml | json ] [ &sign_redirects=value ] [ &source=value ] [ &sub_source=value ] [ &success_redirect=value ] [ &suppress_response_codes=value ] [ &add_center_ids=value ] [ &add_center_opt_in_ids=value ] [ &add_group_ids=value ] [ &add_interest_ids=value ] [ &cons_id=value ] [ &interaction_body=value ] [ &interaction_cat_id=value ] [ &interaction_count=value ] [ &interaction_subject=value ] [ &member_id=value ] [ &no_welcome=value ] [ &primary_email=value ] [ &remove_center_ids=value ] [ &remove_center_opt_in_ids=value ] [ &remove_group_ids=value ] [ &remove_interest_ids=value ] [ &suppress_cleaning=value ] [ &auth=value ] [ &sso_auth_token=value ]

Server API Syntax

https://secure2.convio.net/organization/site/SRConsAPI?method=createOrUpdate & api_key =value & login_name =value & login_password =value & v =value [ & center_id =value ] [ & response_format =xml |json ] [ & source =value ] [ & sub_source =value ] [ & suppress_response_codes =value ] [ & add_center_ids =value ] [ & add_center_opt_in_ids =value ] [ & add_group_ids =value ] [ & add_interest_ids =value ] [ & cons_id =value ] [ & interaction_body =value ] [ & interaction_cat_id =value ] [ & interaction_count =value ] [ & interaction_subject =value ] [ & member_id =value ] [ & no_welcome =value ] [ & primary_email =value ] [ & remove_center_ids =value ] [ & remove_center_opt_in_ids =value ] [ & remove_group_ids =value ] [ & remove_interest_ids =value ] [ & suppress_cleaning =value ]

Usage Notes

The createOrUpdate method provides a convenience wrapper around create and update. This method attempts to locate an existing constituent record in the Luminate Online Constituent 360 database using the value of the cons_id, member_id, or primary_email parameters, and either updates the record, if found, or creates a new record with if possible with the information provided.

If called as a Client API, this method requires authentication. If the Client API operates on behalf of a logged-in non-administrative user (regular constituent), it has the same effect as the update method operating on the logged-in user's record. The Client API for this method cannot be used in the context of a non-administrative user to create a record; use the create method instead.

If a Server API call or Client API call using the authorization token of an administrator session fails to locate an existing record, it will attempt to create a new record for the constituent with the following initial state:

  • origin = "Constituent API" (35)
  • active = "Active" (1)
  • active_detail = "Known" (2) if a "welcome" auto-responder is sent, "Unknown" (1) if not sent.
  • donor_status = "Non-Donor" (1)

Notes:

  1. If a cons_id is included and a match is found, the record is updated. If no match is found, an error is returned indicating that the specified record does not exist.
  2. If the record requested by member_id or primary_email and is not found, the system will attempt to add a new record as by the create method.
  3. If a match is found for member_id, and there is only one match, then the record is updated; if more than one record is matched, an error is returned.
  4. 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.

The list of constituent record fields that can be set is customizable for each organization. It is different for administrative users (via the Server API) and non-administrative users (via Client API).

The listUserFields method will return the list of the Constituent record fields the caller may view or add.

When creating a new record by this method, sending a "welcome" auto-responder by specifying the parameter 'no_welcome=false' also sets 'active_detail=known' for the constituent's initial state.

This method automatically invokes logInteraction to log an interaction for the target constituent.

Note: This method will not allow you to add the created constituent directly to an Interest Opt-In or Opt-Out group. You should instead add or remove the interest to the constituent, which will adjust the group membership as appropriate.

Client API Parameters

Common Client Parameters

See topic Common Parameters.

add_center_ids

Optional. Comma-separated list of numeric IDs of centers to add the user to.

Type xsd:string.

add_center_opt_in_ids

Optional. Comma-separated list of numeric IDs of centers for which the user should be opted in to email communications.

Type xsd:string.

add_group_ids

Optional. Comma-separated list of numeric IDs of groups to which the user will be added. A constituent can be added to a maximum of 1000 groups in a single call. This parameter is only available when called using an administrator account, and cannot be used for pre-defined groups (those with IDs less than 1000). This parameter cannot be used for administrator security groups. 

Type xsd:string.

add_interest_ids

Optional. Comma-separated list of numeric IDs of email interests to add the user to. If the added interest is specific to a center, the constituent is also added to that center automatically.

Type xsd:string.

cons_id

Optional. The constituent ID (Luminate Online ID) that uniquely identifies the constituent. This value is automatically assigned when a new constituent record is created. It can be used to uniquely identify a constituent record to read or update it. Only available when called using an administrator account.

Type xsd:string.

interaction_body

Optional. Text describing or associated with the interaction.

Type xsd:string.

interaction_cat_id

Optional. The Security Category associated with this interaction. The default is 0, which corresponds to the "General" category.

Type xsd:nonNegativeInteger.

Default is 0.

interaction_count

Optional. The number of times the constituent performed this interaction.

Type xsd:nonNegativeInteger.

Default is 1.

interaction_subject

Optional. Short, descriptive subject of the user interaction. Can be up to 80 characters in length.

Type xsd:string.

member_id

Optional. The member ID (Client ID) that uniquely identifies the constituent.

Type xsd:string.

no_welcome

Optional. Only used when creating new records. 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. By default, this value is "true", meaning that no auto-responder email will be sent.

Type xsd:boolean.

Default is true.

primary_email

Optional. The primary email address that uniquely identifies the constituent. Required to create a new constituent record. Optional when updating a record.

Type xsd:string.

remove_center_ids

Optional. Comma-separated list of numeric IDs of centers to remove the user from.

Type xsd:string.

remove_center_opt_in_ids

Optional. Comma-separated list of numeric IDs of centers for which the user should be opted out of email communications.

Type xsd:string.

remove_group_ids

Optional. Comma-separated list of numeric IDs of groups to remove the user from. Only valid when updating records. Only available when called using an administrator account. Cannot be used for pre-defined groups (those with IDs less than 1000). Cannot be used for administrator security groups.

Type xsd:string.

remove_interest_ids

Optional. Comma-separated list of numeric IDs of email interests to remove the user from. Only valid when updating records.

Type xsd:string.

suppress_cleaning

Optional. Specifies whether data cleaning/standardization should be turned on or off. This parameter is intended for performance tuning for server side batch APIs calls.

Type xsd:boolean.

Server API Parameters

Common Server Parameters

See topic Common Parameters.

add_center_ids

Optional. Comma-separated list of numeric IDs of centers to add the user to.

Type xsd:string.

add_center_opt_in_ids

Optional. Comma-separated list of numeric IDs of centers for which the user should be opted in to email communications.

Type xsd:string.

add_group_ids

Optional. Comma-separated list of numeric IDs of groups to which the user will be added. A constituent can be added to a maximum of 1000 groups in a single call. This parameter is only available when called using an administrator account, and cannot be used for pre-defined groups (those with IDs less than 1000). This parameter cannot be used for administrator security groups. 

Type xsd:string.

add_interest_ids

Optional. Comma-separated list of numeric IDs of email interests to add the user to. If the added interest is specific to a center, the constituent is also added to that center automatically.

Type xsd:string.

cons_id

Optional. The constituent ID (Luminate Online ID) that uniquely identifies the constituent. This value is automatically assigned when a new constituent record is created. It can be used to uniquely identify a constituent record to read or update it. Only available when called using an administrator account.

Type xsd:string.

interaction_body

Optional. Text describing or associated with the interaction.

Type xsd:string.

interaction_cat_id

Optional. The Security Category associated with this interaction. The default is 0, which corresponds to the "General" category.

Type xsd:nonNegativeInteger.

Default is 0.

interaction_count

Optional. The number of times the constituent performed this interaction.

Type xsd:nonNegativeInteger.

Default is 1.

interaction_subject

Optional. Short, descriptive subject of the user interaction. Can be up to 80 characters in length.

Type xsd:string.

member_id

Optional. The member ID (Client ID) that uniquely identifies the constituent.

Type xsd:string.

no_welcome

Optional. Only used when creating new records. 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. By default, this value is "true", meaning that no auto-responder email will be sent.

Type xsd:boolean.

Default is true.

primary_email

Optional. The primary email address that uniquely identifies the constituent. Required to create a new constituent record. Optional when updating a record.

Type xsd:string.

remove_center_ids

Optional. Comma-separated list of numeric IDs of centers to remove the user from.

Type xsd:string.

remove_center_opt_in_ids

Optional. Comma-separated list of numeric IDs of centers for which the user should be opted out of email communications.

Type xsd:string.

remove_group_ids

Optional. Comma-separated list of numeric IDs of groups to remove the user from. Only valid when updating records. Only available when called using an administrator account. Cannot be used for pre-defined groups (those with IDs less than 1000). Cannot be used for administrator security groups.

Type xsd:string.

remove_interest_ids

Optional. Comma-separated list of numeric IDs of email interests to remove the user from. Only valid when updating records.

Type xsd:string.

suppress_cleaning

Optional. Specifies whether data cleaning/standardization should be turned on or off. This parameter is intended for performance tuning for server side batch APIs calls.

Type xsd:boolean.

Response

See topic HTTP Status Codes.

XML response
<?xml version="1.0" encoding="UTF-8"?>
<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>1001002</cons_id>
  <message>User updated.</message>
</createOrUpdateConsResponse>
JSON response 
{"createOrUpdateConsResponse":{"message":"User updated.","cons_id":"1001002"}}
Parent topic: Constituent API
Previous topic: create
Next topic: getGroupMembers

Leave a Comment

Nickname
Comment
Enter this word:
Change