Contact List: Linking to Revinate's API

Revinate Marketing Contact List API feature helps hoteliers build databases, and automate contact signups from online web forms. Some additional benefits include automating campaign activation for external lists, synch email activity/subscription status of these guests and track campaign stats of hotel web signups.

Revinate Marketing has an API that allows you to add profiles from external contact lists to the Revinate guest database. This option is useful for hotels to unify the guest list across their different channels and have them merge with their guests with stays and to market to their external lists. The API is an alternative method to add contacts to other existing methods like uploading a CSV file or entering a contact via a User Interface within the Revinate Marketing app.

Detailed setup information on our Contact List API can be downloaded here

This article covers:

• Basic Setup 
• HTML Customization
• and Advanced Setup
• Contact List via API: Online Forms
• PDF of Contact List via API 

The Contact List API is an endpoint that uses JSON. Within Revinate Marketing™, a token can be provided for contact lists that are used by the API. In addition, within the application, we provide a sample code snippet with very basic HTML and JavaScript that utilizes this API. This sample HTML and JavaScript is intended only to help start people off as an example for Contact List Signups. The sample is not intended to be used as-is. It will likely need to be styled and customized before use.

Examples of using an API:

• Subscription forms from a hotel website for newsletters or specials
• Capturing contact info from a website when a user abandons a flow, so they can later be sent a one-time promotion (i.e. a “lite” manual-oriented cart abandonment solution)

Basic Setup  

For a basic setup focused on users who may be less technical, we provide a sample HTML, which also uses an existing, pre-built JavaScript file. Through the sample HTML and JS, it constructs the JSON to make the API call for the user in a simple form.

Note: This sample is not intended to be used as-is.  

• Sample will likely need to be styled and customized before being used. 
• Current sample submits one contact at a time to a single contact list. It provides some basic validation (e.g. email address requires an @ sign). Submission is automatically setting the contact to "Subscribed" status currently.

1) Find a Contact List for the API to interact with:

• Users must navigate to the "Contact Lists" screen in the account, which is accessed by the menu path: Marketing > Guests & Segments > Contact Lists.

2) Click on the Contact List you want the API to interact with ("Tst grp upload" in the example below).

• If you do not have an existing Contact List, you will have to create / import

3) Click "UPLOAD VIA API" to open a modal (per the screenshot below):

• Note the "Token," which is specific to the Account and the Contact List. This is the key that the API itself uses.
• There are additional sample instructions/steps in the modal and a button to copy the Sample HTML from the modal's window (It can also be highlighted and copied manually).

4) Paste HTML

If you were to paste the sample HTML "as-is", it would result in the following generic sign-up form:

Customize HTML

To customize the above, users can take the sample HTML and then proceed to modify it to their needs, as suggested in the sample sign-up form instructions.

For example, they may want to:

• Remove unnecessary fields and scale down to the first name, last name and email address (or just the email address).
• Rename the form's title from "Revinate Contact Sign-up Form Sample" to something more applicable.
• Change any labels or add any additional text desired.
• Modify the fonts, styles and coloring for branding purposes.
• Add new profile fields as in the image below

**New profile fields can be text or numbers and can be used in a merge tag

API Customization

Some areas to customize are visually highlighted below:

 or add a new profile field, (User Defined Field)

 5) Place the snippet into your website 

• We encourage submitting a few test contacts on the first deployment and on any changes to your form, just to ensure things are working as expected.
• The form should now be ready for use.

Advanced Setup

There are several more advanced functions that you may wish to implement, which are more complex.

Detailed setup information on our Contact List API can be downloaded here

For example:  

• In order to re-direct to a landing page, a web developer would need to modify the form action to include this re-direct. In addition, developers could build an entirely different submission flow of their own using the API directly, which is covered in the "Advanced Setup" section.
• In order to insert multiple contacts into a list and/or to input into multiple lists in a single call, a developer must also utilize the API directly.
• In order to perform additional validation on more form fields, a developer would need to add more JavaScript to check the given form fields.

For more advanced users, who may have web development resources, they can directly interface with the API and build to their own requirements. A developer would need to build the JSON elements and POST it to the endpoint provided. One way to familiarize with this is also to review how we did this in the sample via the HTML source and the JavaScript used within the sample described earlier.

End-point and Method

• End-point: https://contact-api.inguest.com/api/add-contacts-to-lists
• Method: POST

Example: Here's an example of the raw JSON used to make the call:

Here's an example of the raw JSON passed back as a response:

Sample command using curl

curl -XPOST "https://contact-api.inguest.com/api/add-contacts-to-lists" -H "Content-Type:text/plain" -d '{"tokens":["GUID to be replaced"],"contacts":[{"first_name":"John","last_name":"Smith","address_1":"1 Letterman Dr","address_2":"","city":"San Francisco","state":"CSM","country":"USA","zip":"94129","phone":"4155551212","email":"[e-mail]"}]}'

Breaking down the above, you can see that the end-point is being called. The JSON elements include the following:

• An array of (one or more) tokens: tokens correspond to an encrypted identifier for a given account's contact list(s) (REQUIRED)
• An array of (one or more) contacts:
• first_name
• last_name
• address_1
• address_2 § city
• state
• country
• zip
• phone
• email (REQUIRED)

Scalability

The API is limited to the following:

• e.g. 20 tokens x 20 contacts, or 5 tokens x 80 contacts

• A combination of up to 400 contacts x contact lists (which correspond to a token) per a call
• Bulk uploads of contacts should still be performed through the CSV upload within the UI.

To capture the sign up date as a UDF in your website API form code automatically (without having the guest enter this information) here are the instructions: 

 

Create a unique UDF for each form (main hotel from, banqueting form, etc) so you can have a unique date for each one. To add the UDFs to the accounts follow the instructions shared below: 

 

Inside any contact list, click the 'UPLOAD VIA API' button. Then click 'ADD NEW PROFILE FIELD' and add a unique name for each form's sign-up date. You will also need to tick the checkbox 'This is a date field'. 

 

In the form code the input tag shared below is inserted within the form tag.

 

<input type="hidden" name="#" id="signup_date" value="">

 

The '#' value will be replaced with the name value generated for the specific UDF created in Revinate. For example if I name the UDF 'Website Signup Date', the name value in Revinate becomes 'WEBSITESIGNUPDATE' and the entire input tag would look like the below.

 

<input type="hidden" name="WEBSITESIGNUPDATE" id="signup_date" value="">

 

Lastly, the script section shared below is inserted at the end of the body section.

 

<script>

 

var dateField = document.getElementById("signup_date");

var currentDate = new Date().toISOString().slice(0, 10);

dateField.value = currentDate;

</script>

CONTACTS LIST VIA API : Online Forms

When using an API connection to upload contact list note that the API code is defining fields as an open text. For example: If you have a newsletter signup where guests tick checkboxes for subjects they are interested in learning more about the system will initially not recognize the 'tick box' field as it will want to search for an open text field. In this case, it is recommended that someone with coding knowledge update the types of fields in your form.

Example of open text fields in an online form: Let us know which newsletter you're interested in by typing Y in the boxes below.

Restaurant

[______]

Spa

[______]

Hotel

[______]

Vacation

[______]

Segmenting by User Defined Fields

Note that asterisks when selecting segmentation options will denote what fields are user-defined fields and can be part of the segment builder. This way when making segments it will be simple to understand what you can segment on.

For more information on setting up a contact list see our related article: Setting up a Contact List

Detailed setup information on our Contact List API can be downloaded here