Contact XML import

The preferred way of creating and updating contacts in Voyado Customer Engagement 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!

Contact XML imports are not processed continuously and updates done in this way can take up to 24 hours to be completed. The XML import interface therefore does not reflect real-time changes in contact data. If you need that, use the contacts bulk API. See here and here.

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. (Note that age can either be specified in the import or derived from either the social security number / personal identity number or the birth date field.)

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

Using Contact Id as key

It is possible to use contact id as identifier for a contact: <contactId>65D152A2-1C12-4E6B-93DC-1D2122554D30</contactId> When <contactId> is included for at least one contact in the XML:

It will be used as key (ignoring other keys)
It will require all contacts in the XML to have <contactId> specified (otherwise XSD validation will fail)
Only updates and deletes are allowed
Neither key fields nor mandatory fields are required

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 Customer Engagement 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>
        <contact>
            <email>example@example.se</email>
        </contact> 
    </new>
    <deleted>
        <member deletionReason="MANUALLY_REMOVED">
            <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 its contact type (in this case, “member”) must be placed in the “deleted” section of 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

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

Importing without triggering export

This is also known as a “silent export”.

After changes are made to your contacts through an XML file import (through updating, adding or deleting) normally BI and XML exports are automatically triggered. However, if you don’t want or need this to happen, you can add the attribute avoidTriggeringExport in your XML. Setting this to “true” will suppress both of those exports.

Importing historical data

Data import by file

Data export by file

Preparing the files

FTP location

Validation

Using Contact Id as key

File example

Removing contacts

Importing without triggering export

Read more about avoidTriggeringExport

​Preparing the files

​FTP location

​Validation

​Using Contact Id as key

​File example

​Removing contacts

​Importing without triggering export

Read more about avoidTriggeringExport

Preparing the files

FTP location

Validation

Using Contact Id as key

File example

Removing contacts

Importing without triggering export