addOrUpdateContacts

The addOrUpdateContacts function allows you to add a new contact, or update an existing contact.

Overview

You can also add or update data associated with the contact, such as field data and list membership.

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

The lists you set in this call are absolute, not incremental, to lists the contact may already be on. This means contacts are removed from any list(s) not specified in this call and will only be added to lists you specify in this call.

However, this cannot be used to pass an empty list of ids in order to remove contacts from all lists that it belongs to. When the API recognizes that the list is completely empty the listId portion of the call is ignored

If you want to

  • Incrementally add a contact to a list without affecting their membership on other lists, use the addToList function.
  • Incrementally remove a contact from a list, use the removeFromList function.

If you want to use this call to incrementally add the contact to a new list and retain their current list membership, you’ll need to

  • Call readContacts.
  • Obtain the ids for the lists the contact is currently a member of.
  • Pass in those ids along with the new list ids when calling addOrUpdateContacts.
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) 2018 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 absolute, not 
  // incremental, to lists the contact may already be on. The contact 
  // will be removed from any list(s) not specified in this call and 
  // will only be added to lists you specify in this call. If your intent 
  // is to incrementally add a contact to a list without affecting their 
  // membership on other lists, use the addToList function. If you want to 
  // incrementally remove a contact from a list, use the removeFromList 
  // function. If you want to use this call to incrementally add the contact 
  // to a new list and retain their current list membership, you'll need to 
  // call readContacts, obtain the ids for the lists the contact is currently 
  // a member of, and pass in those ids along with the new list ids when
  // calling updateContacts.
  $contacts = array(
        'email' => 'EMAIL ADDRESS',
        'listIds' => 'LIST ID',
        'fields' => array(
            $field1,
            $field2
        ),
        'customSource' => 'source'
    );
 
  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 absolute, not 
# incremental, to lists the contact may already be on. The contact 
# will be removed from any list(s) not specified in this call and 
# will only be added to lists you specify in this call. If your intent 
# is to incrementally add a contact to a list without affecting their 
# membership on other lists, use the addToList function. If you want to 
# incrementally remove a contact from a list, use the removeFromList 
# function. If you want to use this call to incrementally add the contact 
# to a new list and retain their current list membership, you'll need to 
# call readContacts, obtain the ids for the lists the contact is currently 
# a member of, and pass in those ids along with the new list ids when
# calling updateContacts.
 
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()