addOrUpdateContactsIncremental

The addOrUpdateContactsIncremental function allows you to add a new contact or update data associated with an existing contact without replacing the existing contact’s list membership.

Overview

With the exception of how list membership is managed, this call works exactly like the addOrUpdateContacts function.

Syntax

writeResult = bApi.addOrUpdateContacts(contactObject[] contacts);

Attributes

Name Type Required Description
id string No if the email or mobileNumberis provided. The id can be used to reference a specific contact to update, but the iditself can not be updated.
email string No if the idor mobileNumberis provided. The email address stored for the contact. The email address can be used to reference a specific contact and can also be updated.
mobileNumber string No if the email or idis provided. The mobile number stored for the contact. The mobile number can be used to reference a specific contact and can also be updated. A valid country code must be included when adding or updating a mobile number for a contact.
status string No; default for adding is onboarding The status of the contact. For adding, the status is automatically set to onboarding, unless you specifically set the status as unconfirmed or transactional. If you want to update an existing contact’s status, you must use the updateContacts function.
messagePrefence string No; default is html The message preference for the contact. A contact can have a message preference of text or html. Only applies to adds. The message preference is ignored in the case of an update
source string No; default is api The source or where the contact came from. The source can be manual, import, api, webform, or sforcereport (Salesforce report).
customSource string No; default is empty A source you define that states where the contact came from.
listIds string, array. Use an array for multiple ids No The lists (referenced by ID) that the contact belongs to. You obtain listIds by calling the readLists function.
Note: The lists you set in this call are incremental to lists the contact may already be on. This means contact will be remain on any list(s) not specified in this call and is also added to lists you specify in this call. If you want to incrementally remove a contact from a list, use the removeFromList function.
fields contactField[] No An array of the fields and corresponding field data associated with the contact.
SMSKeywordIDs string, array. Use an array for multiple ids No An array of the SMS keyword ids you want to subscribe the contact to.

PHP Code Example

<?php 
/** This script will add a contact if the contacts is new, or update the contact's 
 * information if they already exist. 
 * @copyright Copyright (c) 2011 Bronto Software (http://www.bronto.com) */
  

  $client = new SoapClient('https://api.bronto.com/v4?wsdl', array('trace' => 1, 
                                 'features' => SOAP_SINGLE_ELEMENT_ARRAYS));
 
try {
  // Add in a valid API token
  $token = "ADD YOUR TOKEN HERE";
 
  print "logging in\n";
  $sessionId = $client->login(array('apiToken' => $token))->return;
 
  $session_header = new SoapHeader("http://api.bronto.com/v4",
                   'sessionHeader',
                   array('sessionId' => $sessionId));
  $client->__setSoapHeaders(array($session_header));
 
    // Replace SOME CONTENT with a string. We assume here
    // the field is storing a string. The value you pass in
    // should match the type set for the field.
    // Replace SOME FIELD ID with a valid field ID. Field IDs
    // can be obtained by calling readFields. Field IDs are also
    // available in the footer when viewing an individual field in
    // the UI.
    $field1 = array('fieldId' => 'SOME FIELD ID',
                    'content' => 'SOME CONTENT');
    $field2 = array('fieldId' => 'SOME FIELD ID',
                    'content' => 'SOME CONTENT');
 
  // Note: The lists you set in this call will be incremental to the lists 
 // the contact may already be on. The contact will not be removed from any  
 // list(s). To incrementally remove a contact from a list, 
 // use the removeFromList function.
  $contacts = array('email' => 'some_contact@example.com',
            'listIds' => 'ADD IN A LIST ID',
            'fields' => array($field1, $field2)         
                         );
 
  print "Adding contact with the following attributes\n";
  $write_result = $client->addOrUpdateContacts(array($contacts)
                    )->return;
 
  if ($write_result->errors) {
    print "There was a problem adding or updating the contact:\n";
      print_r($write_result->results);
  } elseif ($write_result->results[0]->isNew == true) {
      print "The contact has been added.  Contact Id: " . $write_result->results[0]->id . "\n";
  } else {
    print "The contact's information has been updated.  Contact Id: " . $write_result->results[0]->id . "\n";
   }
 
} catch (Exception $e) {
  print "uncaught exception\n";
  print_r($e);
}

Python Code Example

import sys
import logging
from suds.client import Client
from suds import WebFault
 
 
# This example script will login in to the API, add
# a contact, add them to a list, and add some field
# data if the contact is new. If the contact already
# exists, they will be added to the list and their
# field data will be updated
 
# BE SURE TO REPLACE ALL PLACEHOLDER TEXT
 
# Tested with Python 2.6.1 and suds soap library version 0.4
 
# See suds home page:
# <a title="https://fedorahosted.org/suds/" href="https://fedorahosted.org/suds/">https://fedorahosted.org/suds/</a>
 
 
# Bronto API WSDL
BRONTO_WSDL = 'https://api.bronto.com/v4?wsdl'
 
# Start up basic logging
logging.basicConfig()
 
# Replace the placeholder text with a valid
# API token
TOKEN = "ADD API TOKEN"
 
 
# Login using the token to obtain a session ID
bApi = Client( BRONTO_WSDL )
 
try:
    session_id = bApi.service.login(TOKEN)
# Just exit if something goes wrong
except WebFault, e:
   print '\nERROR MESSAGE:'
   print e
   sys.exit()
 
# Set up the soap headers using the
# session_id obtained from login()
session_header = bApi.factory.create("sessionHeader")
session_header.sessionId = session_id
bApi.set_options(soapheaders=session_header)
 
# Set up the contactField objects
# Replace SOME CONTENT with a string. We assume here
# the field is storing a string. The value you pass in
# should match the type set for the field.
# Replace SOME FIELD ID with a valid field ID. Field IDs
# can be obtained by calling readFields. Field IDs are also
# available in the footer when viewing an individual field in
# the UI.
field1 = bApi.factory.create('contactField')
field1.fieldId = "SOME FIELD ID"
field1.content = "SOME CONTENT"
 
field2 = bApi.factory.create('contactField')
field2.fieldId = "SOME FIELD ID"
field2.content = "SOME CONTENT"
 
# Adding a contact, assigning them to a list,
# and adding some field data.
# Be sure to replace the placeholder text with a
# real email address and list ID!
 
contact = bApi.factory.create('contactObject')
contact.email = 'some_email@example.com'
contact.fields = [field1, field2]
 
# contact.listIds = 'SOME LIST ID'
 
# Note: The lists you set in this call will be incremental to 
# the lists the contact may already be on. The contact will not  
# be removed from any list(s). To incrementally remove a contact 
# from a list, use the removeFromList function.
 
 
try:
    add_contact = bApi.service.addOrUpdateContacts(contact)
    if add_contact.results[0].isError == True:
        print 'There was an error with your request:'
        print add_contact.results[0]
        sys.exit()
    elif add_contact.results[0].isNew == True:
        print 'A contact has been added with the id: ' + add_contact.results[0].id
    else:
      print 'The following contact has been updated: ' + add_contact.results[0].id
except WebFault, e:
    print '\nERROR MESSAGE:'
    print e
    sys.exit()