API integration

Voyado Onsite can be connected to different platforms and databases. Engage, of course, but also other CRMs / CXPs / CDPs as well as different e-com platforms.

Read about connecting to Engage

You can also use the generic API connection provided to build your own custom connections to and from any platform lacking a pre-made Onsite integration. This will be covered in this article.

Voyado Onsite does not provide a generic API. When using the generic API solution, you will be setting up a server-side API for Voyado Onsite to use as a client based on the specifications below.

Configuration

Configuring a generic API integration is done in the Onsite manager. Follow these steps:

1. Log into the Onsite manager, then go to Configuration and Sites.
2. Pick the site you want to set up the generic API integration for and either click on its name or select “Edit” in the three-dots menu.
3. You should now be in General settings for that site. Scroll down to Integrations, locate the option Generic and click to expand it.
4. You’ll now see the configuration for the generic API integration.

There are three authentication methods to choose from:

• Header
• HMAC
• API Key

The configuration is very similar for all three methods. The values to fill in are:

• Get/Lookup Contact API Endpoint URL: The URL for your API endpoint that will be used to check if a contact already exists.

• Create/Update Contact API Endpoint URL: The URL for your API endpoint that will be used for creating new contacts and updating existing contacts with new data, consents, and so on.

• Email Key: The variable name to be used for email address in API requests.

• Phone number Key: The variable name to be used for mobile phone number in API requests.

• Name Key: The variable name to be used for customer name (full name) in API requests.

• Personal Identity Key: The variable name to be used for social security number (personal number in Sweden, for example) in requests to your API.

• Ignore HTTP response codes: Here you list the HTTP error codes to ignore, which means no error will be logged if any of the listed response codes are received. Use this feature to ensure everything still functions in the case of the API responding with error codes. If this setting is not active, and an unexpected response code is returned from the API, the user flow will be blocked and/or aborted.

The data

The same JSON structure is used for sending and receiving data (via POST and GET respectively). The fields in the JSON are determined by what the campaign is configured to collect:

Sending and receiving Onsite data

{ 
  "name": "John Doe",
  "firstname": "John",
  "lastname": "Doe", 
  "email": "[e-mail]", 
  "phone": "[phone]", 
  "custom": "customvalue",
  "customoption": ["customoptionvalue1,customoptionvalue2"], 
  "redeal": ["ExistingAmbassador", "NewFriend", "FriendConverted"] 
} 

In this example, customoption might be “pet” and customoptionvalue1 might be “Dog”. You should configure the API to ignore anything that you don’t recognize and/or can’t handle. This is fully configurable and maps directly into what is collected from the user.

There is one special field redeal to tag the type of contact, which is used for conversion tracking. You can choose to store this or just ignore it. The current tags in use are:

• NewAmbassador: A new contact who acted as an ambassador by referring friends
• NewFriend: A new contact from a friend referral
• NewSignup: A new contact without a referral
• ExistingAmbassador: An existing contact who acted as an ambassador
• ExistingFriend: An existing contact who acted as a friend
• ConvertedAmbassador: A contact acting as an ambassador who has converted
• ConvertedFriend: A contact acting as a friend who has converted

Receiving data

The API call to fetch data is:

GET {Get/Lookup Contact API Endpoint URL}?company={company}&email={email}

“Get/Lookup Contact API Endpoint URL” is the value you configured in Onsite Manager above.

Expected return codes are:

• 200 OK
• 404 Not found

The reason this GET is called is to avoid asking the user for information that is already known, and to set the correct redeal tags. You should make it optional to use the GET call.

Sending data

The API call used to send data is one of the following:

POST {Create/Update Contact API Endpoint URL}?company={company}

POST {Create/Update Contact API Endpoint URL}?company={company}&email={email}

POST {Create/Update Contact API Endpoint URL}?company={company}&phone={phone}

“Create/Update Contact API Endpoint URL” is the value you configured in Onsite Manager above.

Expected return codes here are:

• 200 OK
• 201 Created