Skip to main content

Voyado Engage

Contact XML import

The preferred way of creating and updating contacts in Voyado Engage is through the API. But sometimes file-based imports are more practical, for example when another system is the master or when it's not crucial that updates happen right away.

There are some things to keep in mind about file-based updates:

  • Only new information generated after the last import should be transferred

  • Each file can contain information for one or more contacts

  • If there is no new information, then no file should be sent

Please read about file based integration before going any further!

Preparing the files

Files sent to the FTP server should follow this naming convention:

[Timestamp]_[sequence number OR store id] _contacts.xml.

  • [Timestamp] should be formatted as: YYYYMMDDHHmmss (Y = year, M = month, D = day...)

  • The sequence number / store id is only needed if there is a risk that several applications might send XML files simultaneously

  • The number of contacts should not exceed the maximum specified on the file based integration page

FTP location

Again, see the file based integration page.

Validation

Contacts are validated individually and the contact's fields are considered one by one. If validation fails for any of the contact's fields, then that field will not be created or updated. But other fields, as long as they are valid, will still be updated.

An update to a contact will be skipped entirely if the validation error is grave, such as in the case of a missing mandatory key, or an age that is below the specified minimum age. Age can either be specified in the import or derived from either the social security number or the birth date field.

Warning

If there is a major error during the import the entire file will be skipped.

File example

Your XML should look like the example below, with variations depending on the number of fields used in your project.

A contact inside a <new> tag is interpreted by Engage as either new or modified, depending on if it already exists in the database or not.

<?xml version="1.0" encoding="utf-8"?>
<contacts xmlns="http://eClub.Schemas.ImportContact">
  <new>
    <member source="STORE">
      <externalId>1526235</externalId>
      <socialSecurityNumber>198010101010</socialSecurityNumber>
      <firstName>Example</firstName >
      <lastName>Examplesson</lastName>
      <email>example@example.se</email>
      <mobilePhone>+46739111111</mobilePhone>
      <careOf>Somebody</careOf>
      <street>Examplegatan</street>
      <zipCode>12345</zipCode>
      <city>Examplestan</city>
      <acceptsEmail>true</acceptsEmail>
      <acceptsSms>true</acceptsSms>
      <acceptsPostal>false</acceptsPostal>
      <consentMemberTerms>true</consentMemberTerms>
      <registrationDate>2013-02-10T15:02:00+01:00</registrationDate>
      <countryCode>SE</countryCode>
      <registrationStoreId>2343</registrationStoreId>
      <labels>
       <label>Label 1</label>
       <label>Label 2</label>
      </labels>
    </member>
<!--You can also define other contact types--> 
    <contact>
      <email>example@example.se</email> 
    </contact> 
  </new>
  <deleted>
    <member deletionReason="MANUALLY_REMOVED">
      <!—- Voyado Engage key, defined per integration and contact type -->
      <externalId>1526235</externalId>
    </member>
  </deleted>
</contacts>

For the standard fields used, see the page Contact field definitions.

Removing contacts

To delete a contact, an XML block corresponding to the contact type (in this case, member) must be placed in the “deleted” section in the file, along with whatever unique identifier has been decided for the project. We recommend you also add the attribute deletionReason.

Field name

Format

Description

deletionReason (ATTRIBUTE)

varchar

Reason for deletion. Accepted values: MANUALLY_REMOVED, DECEASED

Note

Deleted contacts will remain in the database for seven days at which point complete anonymization of their data will occur.

Importing without triggering an export ("silent update")

Normally, after changes are made to your contacts through an XML file import - be it updating, adding or deleting - an export is automatically triggered. If you don't want or need this to happen, you can use the attribute avoidTriggeringExport. Setting this to true will suppress both the BI and XML exports.

Here is an example:

<?xml version="1.0" encoding="utf-8"?>
<contacts xmlns="http://eClub.Schemas.ImportContact" avoidTriggeringExport="true">
    <new>
        <member>
	    <contactId/>
	    <infobaleenEmailCampaign/>
	</member>
    </new>
</contacts>

For this to work the file can only consist of a ContactType key (such as "member") and true Contact Attributes (that don't exist on the contact table).

If avoidTriggeringExport is set to true and the import file contains Contact Attributes that are not keys and also exist on the contact table (ex FirstName, Email), the import will fail and an error will be written to the integration log.

If an import is done with only keys and true Contact Attributes but avoidTriggeringExport is false or missing, exports will be triggered and entries added to changelog and lastmodified.

Note

The attribute avoidTriggeringExport is false by default, so you only need to include it in your XML import if you want it to be true.