Personalize Your Contacts, Storing Field Data With The API

OK, so your integration is running. You're adding contacts at a dizzying pace, and then your marketing team wants to send some personalized messages and...whoops, all you have are email addresses. You neglected to push any customer data that could be used to personalize a message; first name, last name, favorite soda, etc. Whatever data you have gathered from your contacts could potentially be useful in developing a bulk message that seems less bulky.

You know that this data can be imported using a csv file and the import tool in the Bronto web app, but how about with the API? We talked about adding contacts using version 3 in Welcome Friend! Adding New Contacts Using the API, but let's look at the contactObject to see how we might use it to add or update contacts with version 4.

Let's first look at the fields portion (in bold) of the addContacts SOAP request message below(note: updateContacts uses the same contact object and readContacts returns the same object).

You might never need to actually look at a SOAP message or a WSDL if your IDE/SOAP library takes care of that for you, but it can definitely be helpful when trying to understand how the requests and responses are passed back and forth. Most of the attributes are self descriptive and using them is hopefully straight forward. The fields attribute however takes a little more explaining.

In the WSDL you will see that it is defined as:

<xs:element maxOccurs="unbounded" minOccurs="0" name="fields" nillable="true" type="tns:contactField"/>

This tells us that the fields item is a group of zero or more contactField objects. In most programming languages, that type of structure would be represented as an array of contactField objects. These contactField objects in turn contain two items; fieldId and content. The content is the actual data that you want to store and the fieldId is a static id that is assigned to each of your fields when they are created. The fieldId can be retrieved using the readFields function. Since the fieldIds are static, it probably makes sense to go ahead and store these locally so they do not need to be read each time you want to use them. The easiest thing to do is to call readFields once with an empty filter and store the field information in a configuration file. That way, adding or removing fields will not require changes to your code.

With this information in hand, it will hopefully make more sense on how you would go about passing in contact information. So don't leave those fields empty any more.

Alex Durzy
Support Engineer at Bronto