Synchronizing contacts

The most important benefit of system integration is how much time you save! Especially for marketing professionals, who would otherwise have to spend a lot of time manually importing and exporting contact data. The automatic process that synchronizes the contacts to Spotler (near) real-time keeps the contact database up to date, and allows the marketing expert to send a newsletter at any given time.


Mapping contact fields

In order to synchronize contacts, you must first determine which contact properties should be synchronized. To find out which contact fields are available in the Spotler account, we recommend using the REST API method that retrieves these fields. The result will not only include the field names featured in the Spotler account, but also the formats in which they are saved. We recommend to keep field mapping within the connection accessible to a user and open to revision. With this you can expand the mapping with extra contact fields without consulting a developer.

Technical documentation
Retrieving contact properties


First and last purchase date

Two contact fields deserve special mention: firstPurchaseDate and lastPurchaseDate. This data can be used in Spotler for the purpose of segmentation, or for automated campaigns. The linked system (online store) should keep this data up to date. The firstPurchaseDate should be set once: the moment a customer makes their very first purchase. The lastPurchaseDate should be updated every time a customer places an order.


Some Spotler accounts use one or multiple permissions. This means that a contact can subscribe to, and conversely also unsubscribe from a specific mailing. This contact information is stored in a specific list field named “permissions.”

Insert or update contacts

When a new contact is created in the linked system or an existing contact is edited, this change can be passed directly to Spotler. It is helpful for the marketing professional if this happens as close to real-time as possible.

There are two ways to update contacts in Spotler. We recommend using the method designed to insert contacts, with update set to true. This way, the linked systems do not have to recall whether this contact has been inserted before. The other method is specifically used to update contacts.

Technical documentation
Insert contact (optionally with update=true)
Update contact


Duplicate prevention takes place in Spotler

When you insert contacts via the API, the rules that are programmed in the Spotler account pertaining to duplicate prevention will be applied. On the whole, this means that the prevention of duplicates will be based on the externalId and the contact’s email address. When a contact is inserted and this contact’s email address already exists within Spotler, the new contact data will be merged with the existing contact data stored in Spotler. This eliminates duplicate contacts and ensures that contacts do not receive duplicate newsletters in their inbox.


Is the linked system multilingual (as may be the case for online stores)? If so, the language should be synchronized to Spotler for every contact. Marketing professionals will, of course, want to send subscribers their mailings in the correct language. If the structure of the online store is determined by its multilingual setup, we recommend storing this structure in its entirety in the language field for the relevant contact, using for instance “SPACE-SPACE” between the levels. This value is exclusively meant for the marketing professional using Spotler and will not be shown in the newsletter.

Retrieving bounced contacts

When you send mailings, you will inevitably come across email addresses that generate a bounce. This means the email did not reach the intended recipient because the email address is incorrect. Sometimes a typing error in the email address is to blame, but you may also come across cases where a contact has left a company in order to work for another employer. Bounces are the way to ascertain whether this is the case. Using the API, you can retrieve bounced contacts from Spotler and make them accessible within the linked system. One advantage of retrieving bounces in this manner is that the file in the linked system remains clean. Access to bounced contacts also creates new opportunities! For example, you can seek out the person who was hired to replace the former contact in order to keep this client. At the same time, you can also try to get in touch via other means with the contact who left the company. After all, his or her new employer could be a potential new customer. This way, you can turn bounces into new leads.

Bounced contacts should be retrieved periodically. Once every hour, for instance, or once every day. Is the linked system a CRM system? If so, we recommend creating an automated task for the relevant account manager to follow up the bounce. Resolving bounces will no longer end up on the back burner and will be made measurable.

Technical documentation
Retrieving bounced contacts

Retrieving updated contacts

The linked system is not always the guiding system for all contact details. The recipients of a mailing can edit their profile information via a Spotler webpage. This information will be edited in Spotler directly. You can periodically retrieve these edits to keep the linked system up to date. For example once every hour, or once a day.

Sometimes the synchronized email address is also used as the username when logging in to the linked system. This is often the case with online stores. If applicable, we recommend not including this field on the edit profile page of Spotler. This means that contacts will only be able to edit their email address (username) via the linked system.

Technical documentation
Retrieving updated contacts

Retrieving unsubscribes

Every email sent via Spotler contains a link to a Spotler webpage allowing recipients to unsubscribe from future mailings of the same type. An unsubscribe can be compared with a contact edit, because an unsubscribe comes down to an edit to one or more permissions pertaining to that contact. When you retrieve updated contacts you will simultaneously retrieve the unsubscribes.

Using specific segmentations in Spotler

In general, the linked system is the source system and will often contain much more data than the direct contact information alone. It is likely that you are not synchronizing all of this data to Spotler (on purpose). However, in some cases marketing professionals want to use this data for segmented email marketing activities. For instance, in order to send an event invitation to a select list of guests.

Using the API, you can pass specific selections of contacts to Spotler. These selections are referred to in Spotler as Static lists. A static list is, in fact, no more than a collection of contactIds with a sensible title, so when using Spotler the marketing expert can see what the list is meant for. Once the list is passed to Spotler, it becomes a static list.

A maximum number of 30 temporary lists can simultaneously be stored in Spotler. It is therefore convenient to enable removing temporary lists via the linked system as well. Via the API, you can only remove temporary lists that were passed from that same system.

Technical documenation
Insert a temporary list
Add contacts to a temporary list
Get all temporary lists
Delete a temporary list

Insert subscribers

There is a separate method to pass to Spotler contacts who have subscribed to a newsletter. The submitted email address and the correct permission must always be included in the call. This method is purely meant to register new subscribers in Spotler, via a custom subscriber form on a website, for instance. This method is not intended to keep two systems synchronized. Therefore, it is not necessary to include a contactId in the call.

Technical documentation
Insert subscribers

Searching contacts based on a property

Using the API, you can search for contacts in Spotler on the basis of a certain property or a combination of multiple properties. An example of the possible applications of this method is a web form that allows a visitor to enter only a discount code. This way you can search Spotler for the contact matching that discount code. When the contact is found, a personalized webpage can be shown – a prefilled form, for instance. When the contact cannot be found, a webpage may display a message explaining that the entered code is not valid.

Technical documentation
Search contacts based on a property