We have discussed how to use these fields in Getting Personal With Your Contacts, but this post will concentrate on how to create the fields using the API.  The SOAP message you will generate to create a field of type text will look like this.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.bronto.com/v4">
  <SOAP-ENV:Header>
  <ns1:sessionHeader>
    <sessionId>ceeac55f-cf56-458d-a3b3-0a2058e0f3d7</sessionId>
  </ns1:sessionHeader>
  </SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns1:addFields>
  <fields>
    <name>Favorite Color Field</name>
    <label>What is you favorite color</label>
    <type>text</type>
    <visibility>public</visibility>
  </fields>
</ns1:addFields></SOAP-ENV:Body>

The attributes in this SOAP message should be familiar to anyone who has created a contact field in the Bronto application, but they are documented here.

Here is a sample of the PHP code that would generate this SOAP message.

$client = new SoapClient('https://api.bronto.com/v4?wsdl', array('trace' => 1,
'features' => SOAP_SINGLE_ELEMENT_ARRAYS));
setlocale(LC_ALL, 'en_US');
try {
  $token = "YOUR TOKEN HERE";
  $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));
  $field = array('name' => 'Favorite Color Field',
                 'label' => 'What is you favorite color',
                 'type' => 'Text',
                 'visibility' => 'public');
  $res = $client->addFields(array($field))->return;

  if ($res->errors) {
    echo "There was a problem creating your field:<br>";
    echo $res->results[$res->errors[0]]->errorString . "<br>";
  } else {
    echo "Field has been created.  Id: " . $res->results[0]->id . "<br>";
  }
} catch (Exception $e) {
  print "uncaught exception\n";
  print_r($e);
}

After creating these fields, you can add personalized customer data using the API, as discussed in the post Storing Field Data With The API. Contact fields give you the flexibility to associate data with contacts at a very granular level. You can use this data to add a personal note, add data to URLs in your message, or just include data about the contact. If you have any questions, feel free to leave them in the comments section below.

Andrew Kanes
Support Engineer at Bronto

Related posts:

1. Clear that List using the API v4 Last fall, Alex explained how to Clear Contacts From...
2. Create a Header Without Logging into Bronto Did you know you can now create headers and footers...
3. The Pluses And Minuses Of List Management What happened to all my lists?!?!? You might be asking...

Last fall, Alex explained how to Clear Contacts From Lists in v3 of the API. You now have the same ability in v4 API using the clearLists function. All you need to do is specify the list id returned from the addLists or readLists function. After you call clearLists, all your contacts will be removed from the list, however, they will remain in Bronto.

Here is a sample SOAP message that would clear two lists.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v4="http://api.bronto.com/v4">
   <soapenv:Header>
      <v4:sessionHeader>
         <sessionId>b058d5e0-7cb4-4578-b16f-a4c049079207</sessionId>
      </v4:sessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <v4:clearLists>
         <list>
            <id>0bbb03ec0000000000000000000000038e93</id>
         </list>
         <list>
            <id>0bbb03ec00000000000000000000000390d0</id>
        </list>
      </v4:clearLists>
   </soapenv:Body>
</soapenv:Envelope>

This PHP script would create a SOAP message like this.

<?php
/**
 * This example will clear two lists of all contacts on those lists.
 * You must edit the code to refer to the list id you wish to clear.
 */

$client = new SoapClient('https://api.bronto.com/v4?wsdl', array('trace' => 1, 'features' => SOAP_SINGLE_ELEMENT_ARRAYS));
setlocale(LC_ALL, 'en_US');

try {
        $token = "#####API TOKEN###########";

        print "logging in<br>";
        $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));

        $ids = array(array('id' => '0bbb03ec0000000000000000000000038e93'),
                   array('id' => '0bbb03ec00000000000000000000000390d0'));

        $res = $client->clearLists($ids)->return;

        if ($res->errors) {
                print "There was a problem clearing your lists:<br>";
                print $res->results[$res->errors[0]]->errorString . "<br>";
        } else {
                print "Lists have been cleared<br>";
        }
} catch (Exception $e) {
        print "uncaught exception\n";
        print_r($e);
}
?>

Now you are able to quickly and easily clear your lists without having to find everyone on the list. We do suggest you exercise caution when using this function, as there is no rewind button. I hope you find this new functionality useful. Let us know if you have any questions.

Andrew Kanes
Support Engineer at Bronto

Related posts:

1. Spring Cleaning: Clearing Contacts From Lists This post only applies to Legacy Version 3 of the...
2. The Pluses And Minuses Of List Management What happened to all my lists?!?!? You might be asking...
3. Create a Header Without Logging into Bronto Did you know you can now create headers and footers...

As with our other API functions, there is not only the ability to add, but also to read, update and delete API Tokens. These functions give API users the ability to manipulate their API Tokens just as a user logged into the web application is able to.

Let’s Jump In

First let’s take a look at an example of a SOAP message to create a token:

The response message that is returned by the API will contain the Id of the newly created token and will look like this:

You can then use the Id to reference that token, for instance when using the readApiTokens.

You can also use the filters available for readApiTokens to search for tokens based on their name, or return all the tokens available to a sub-account or an entire agency. Of course, after you create the API Token, you are now able to use it to log into the API. We hope you find this new functionality useful and please let us know if you have any questions.

Andrew Kanes
Support Engineer at Bronto

Related posts:

1. May I Have Another User As part of version 4 of the Bronto API, we...
2. Clear that List using the API v4 Last fall, Alex explained how to Clear Contacts From...
3. Agencies Can Create New Accounts Using The API Last month we discussed how to create headers and footers...

The new function and its related functions deleteAccounts, readAccounts and updateAccounts allows you to maintain your client accounts from outside the Bronto application. The arguments for this function fall into generalSettings, contactInformation, formatSettings, brandingSettings, repliesSettings and allocations. You can use these new functions to integrate Bronto into an external application where you preform other work, there by cutting down on the time you spend switching between applications. To do this you would need to generate a SOAP message like this:

Of course, after you create your client accounts, you can do a readAccounts to display information about those clients accounts in another application. Then using updateAccounts, you can update a client account and maintain it without having to switch over to Bronto. You could also set up an automatic system to examine your client accounts on a regular basis and alert you if any are approaching a limit, such as maximum number of contacts allowed in the current allocation period.

If you have any questions, feel free to leave them in the comments section below.

Andrew Kanes
Support Engineer at Bronto

Related posts:

1. Token, Token, Who Wants a Token? Another new feature of version 4 of the Bronto API...
2. May I Have Another User As part of version 4 of the Bronto API, we...
3. Create a Header Without Logging into Bronto Did you know you can now create headers and footers...

This new function, and its associated functions deleteHeaderFooters, readHeaderFooters and updateHeaderFooters, allows you to manipulate the name and contents of your headers and footers from outside the Bronto application. The arguments are name, html, text and isHeader. These allow you to specify the name of the header or footer, the html and plain text content of the header or footer, and how it should be used.

Do you design your headers and footers in an external application and then log into Bronto to create your header and paste in your content? Using these four functions, you can create, modify, read, and delete headers and footers from an external, customized application. Now you can avoid the process of cutting and pasting your content into Bronto by sending a SOAP message like this

Here is some sample PHP code to generate this SOAP message:

If you have any questions, feel free to leave them in the comments section below.

Andrew Kanes
Support Engineer at Bronto

Related posts:

1. Agencies Can Create New Accounts Using The API Last month we discussed how to create headers and footers...
2. Clear that List using the API v4 Last fall, Alex explained how to Clear Contacts From...
3. Adding Contact Fields using the API Recently, we wrote about creating headers and footers and adding...

Using the contactFilter

Lets say you were interested in all active contacts created after June 1, 2009 at 6am ET. You would create a SOAP message like:

Using the readContacts function, you can also filter on criteria such as email address, modified date, which lists or segments the contacts are on, message format preference, source and customSource. You can also specify if the contacts should match all or any of the filter criteria by defining the filter type as an AND or an OR.

Aggregate Information Returned by the readContact Function

The updated readContact function also returns aggregate information for each contact. The results now include numSends, numBounces, numOpens, numClicks, numConversions and conversionAmount. These metrics tell you the total number of deliveries sent to a contact, the number of times deliveries sent to a contact that have bounced, the number of opens recorded for the contact, the number of clicks recorded for the contact, the total number of times a contact has converted, and the total amount of any conversions. This is in addition to all the other information about a contact that is returned.

Let us know if you have any suggestions or questions in the comments section below!

Andrew Kanes
Support Engineer at Bronto

Related posts:

1. Filtering Result Sets Did you know that all of the read functions available...
2. Token, Token, Who Wants a Token? Another new feature of version 4 of the Bronto API...
3. Create a Header Without Logging into Bronto Did you know you can now create headers and footers...

Creating a token

Related posts:

1. The Pluses And Minuses Of List Management What happened to all my lists?!?!? You might be asking...
2. Create a Header Without Logging into Bronto Did you know you can now create headers and footers...
3. Clear that List using the API v4 Last fall, Alex explained how to Clear Contacts From...

This post only applies to Legacy Version 3 of the API

You may be using the Bronto API to find out who is reading your deliveries or to send a message, but how about using it to add new contacts to your Bronto list? Using the API, you can add new contacts that you have in a system outside of Bronto. The Bronto API allows you to create up to 1000 contacts in a single request. After the request has been successfully processed, these contacts will be available in the Bronto application and the API.

Adding New Contacts

You create these new contacts using the writeContacts function. This function allows you to give as much or as little information about the new contacts as you have. The only information required to create new contacts using writeContacts is their email address, their status (active, unsubscribed, bounced, unconfirmed), and whether each contact should receive html or plain text messages. Naturally, you can also include other information such as source, any lists the new contacts should be on, and any member field data you have about the new contacts. Since the email address is a unique identifier in the Bronto system, you will not create a duplicate contact should you try to create an email address that already exists. You can, however, update current contacts based on the email address if you choose.

Advanced Features

What if you don’t know if the contacts you are trying to add are all new? What if you don’t want to overwrite contact information already in Bronto? As part of your request, you can specify the mode that writeContacts should use. This tells the API how to handle this request. You can use insert, update or insertUpdate. If you specify insert, the contacts will only be created. If they already exist in Bronto, their information will not be updated or overwritten. The update mode will update information of current contacts. The last mode, insertUpdate will allow you to create new contacts or update contacts if they already exist.

The listsMode attribute of the writeContacts function gives you the ability  to add or remove the contacts from lists. The options for listsMode are replace, insertUpdate and remove. The replace mode removes the contacts from the lists they are currently on and adds them to the lists specified in the request. The insertUpdate mode keeps the contacts on any lists they may currently be on and adds them to the specified lists. The remove mode removes the contact from the lists in the request. You should always have a contact assigned to at least one list since you can only send to contacts on a list.

The fieldsMode allows you to specify how any member field data you send is treated. There are only two modes, replace and insertUpdate. The replace mode will delete any current field data the contact has, and add the field data sent in the request. The insertUpdate mode will only add data to a field if new field data is included in the request. It will leave any fields not specified in the request as they are.

Last but not least is the ignoreStatusChangeIfUpdate attribute. This parameter is really a safety net that keeps you from unintentionally changing the status of a contact. For instance, if a contact already exists in Bronto, but is bounced, this will keep you from accidentally updating them to subscribed and then attempting to send them a message. If you include this parameter with a value of 1 in your request, then a contact who is currently on your list will not have their status changed, regardless of what value you specify in the request.

Some Example Code (PHP)

Below is some example code you can use to get an idea of how the writeContacts function can be used.

Add Away

Now that you have read about the power of writeContacts, we hope you will continue to leverage the power of the Bronto API and discovery new ways to use it.

Andrew Kanes
Support Engineer at Bronto

Related posts:

1. Importing Contacts: Updating Existing Contacts And Adding New Contacts Often times, when managing your Bronto contacts, you’ll want to...
2. Spring Cleaning: Clearing Contacts From Lists This post only applies to Legacy Version 3 of the...
3. Personalize Your Contacts, Storing Field Data With The API OK, so your integration is running. You’re adding contacts at...