2. Partner Integration Guide

Owned by Collin Peters (Unlicensed)
Last updated: Jun 08, 2017 by Caitlin Tupper

HOME > SET UP > INTEGRATIONS & PARTNER PAGES > DEVELOPER GUIDE

 

 

 

Table Of Contents

Introduction

This document describes the steps necessary to receive data from the Connector.  This document assumes you know what the Connector is and does not include an overview of it (please see “Connector – Overview”)

 

Important

This document describes the options available for the Connector to make web service calls to your platform (i.e. you are the RECEIVER of data). That is, data which is coming from other platforms such as InTouch, and going into your platform. If the integration agreement that you have decided upon with InTouch is only for sending data (that is, your system only sends data) then this document does not apply. Please see the companion document "Connector API Guide" for details on sending data to the Connector.

First off, your system MUST provide some type of web services via an API that the Connector can call. This is how the Connector will send the data to your system.  If you do not yet have an API built, this document will outline the basic requirements that it should have.

The required calls in order to support the various integration features are listed below.  Once baseline features are agreed upon, work will need to be completed by InTouch in order to add support to the Connector to make the API calls to your system.  When calling your web services the Connector will obviously use whatever technology is required (e.g. soap, rest, etc...).  Note that the Connector is a Java application, if you have a Java library already prepared that you can provide to InTouch it will greatly simplify the work required on our part to make calls to your web service

Requirements - Summary

  • Web service calls
    • To support receiving prospects a 'save prospect' API call is required (or insert/update prospect). The call MUST return the ID of the user in your system
      • To support including a lead/prospect owner a 'get staff list' API call is required which returns a list of staff with the staff ID and email address at a minimum
      • To support including a lead/prospect lead source a 'get lead source list' API call is required which returns a list of lead sources with their names
    • To support receiving members a 'save member' API call is required (or insert/update member). The call MUST return the ID of the user in your system
    • To support receiving ex-members a 'save ex-member' API call is required (or insert/update ex-member). The call MUST return the ID of the user in your system
  • General attributes of a good API
    • Connection information
      • URL - the web URL to access the API. e.g. https://yourdomain.com/api
      • Username/password - Ideally your API should be secured by a username/password or a security token. This would be added to the Connector so it can authenticate securely to your API
      • Scheme (https or http) - It is highly recommend that your API be secured by TLS (Transport Layer Security) i.e. https & ssl. An unsecured API is very risky
    • A test site. Ideally there will be a permanent URL that InTouch can A) create the integration against and B) continue to test in the future and add new features. Generally running a single production site adds to the complexity because it makes it more difficult to add enhancements to the integration

Requirements - Details

These are the web service calls required by your API in order for the Connector to send data to your system

  1. Prospects - In order to have prospects sent to your system, the following API calls are required
    1. Save prospect
      1. An API call where we can send all of the prospect information. Usually this will be an HTTP POST call (REST or SOAP) with the details of the prospect in the body of the call
      2. This must return the ID of the user in your system so subsequent update calls can be made
      3. This save call should support both inserts and updates. However, it is also satisfactory to have two calls (one to create a prospect and one to update a prospect) but a single save call is preferred as it should be the responsibility of your system to know if it is doing an insert or update
    2. Staff Owner - In order to have a staff owner sent for prospects, the following API calls are required
      1. Fetch a list of staff
        1. The email address must be accessible in order for the Connector to associate certain records together.  See the 'Getting Started' part of the developer guide
        2. Note that an API call that fetches a single staff by email address is sufficient as well
      2. Notes
        1. Staff owner for a prospect is optional. If staff owner for prospects is not supported then it is up to your system to handle prospects being sent with no staff owner 
        2. See section below for more details on staff synchronization.  
        3. The Connector does NOT attempt to create or update staff in any system due to the high level of complexity and overhead of creating staff (i.e. permissions, existing staff, etc...)
    3. Lead Sources - In order to have a lead source sent for prospects, the following API calls are required
      1. Fetch list of lead sources OR
      2. Save a lead source (or separate methods for inserting & updating a lead source, similar to prospects as noted above). This must return the ID of the lead source in your system
      3. Note: Both are not required but it is ideal.  See below for details on lead source synchronization. 
  2. Members - In order to have members sent to your system, the following API calls are required
    1. Save a member  (or separate methods for inserting & updating a member, similar to prospects as noted above). This must return the ID of the user in your system so subsequent update calls can be made
    2. Note: The process of converting a prospect to a member is unique per system. 
  3. Ex-Members - Same as members except the user type will be ex-member.

 

General Information

Fields

The Connector contains the following user information fields

  • First name
  • Last name
  • User status (active or inactive)
  • User type (prospect, member, ex-member, or staff if that is part of your integration)
  • Birthdate
  • Gender
  • Address 1
  • Address 2 (note: currently InTouch does not have this field)
  • City
  • Zipcode
  • State
  • Country
  • Email
  • Mobile
  • Home phone
  • Work phone
  • Company
  • Created date
  • Created by (simple text indicating who created the user. e.g. INTOUCH)
  • Modified date
  • Modified by (simple text indicating who last modified the user. e.g. INTOUCH)

For prospect/lead records there are these additional fields

  • Lead Owner (applicable to prospects only). Optional. Requires staff synchronization as listed below.  We will send you your staff ID
  • Lead Source (applicable to prospects only). Optional. Requires lead source synchronization as listed below.  We will send you your lead source ID
  • Trial start date (applicable to prospects who are on a trial only). Optional.
  • Trial end date (applicable to prospects who are on a trial only). Optional.
Staff Synchronization

If your integration is to support having a staff owner for received prospects, then the rules listed in the developer guide will apply. This means that your API must contain a web service call to retrieve a list of staff.  When a staff is saved (usually through InTouch), a call will be made to your staff web service and a match will be attempted on email address.  Once a staff is synchronized, then prospects assigned to that staff will be sent to your web service using that staff.

Example:

  • New staff 'John Staff' is added to InTouch with an email of jstaff@club.com.  The InTouch ID for John is 1111
  • John is sent to the Connector
  • The Connector realizes that this record does not have a link to your system for this staff
  • A web service call is made to your API to get a list of staff
  • If the results contain a staff with an email of jstaff@club.com, then an association is made. Let's assume John Staff exists in your system with ID 9999
  • If the results do not contain a staff with an email of jstaff@club.com, then no association can be made
  • Now a new prospect is added to InTouch, Pete Prospect, and Pete is assigned to John Staff
  • The prospect is sent to the Connector
  • The Connector can see that Pete Prospect is assigned to staff with InTouch ID 1111
  • If the staff association above was successful, then the Connector will send Pete Prospect to your system with a staff owner ID of 9999 (the staff ID in your system)
  • If the staff association above was unsuccessful, then the Connector will send Pete Prospect to your system with no staff owner
Lead Source Synchronization

Lead Source synchronization works very similar to staff synchronization (as above) except that if a lead source lookup fails, and your API provides a method to create a lead source, then an attempt will be made to create the lead source in your system.

Example:

  • A new lead source named 'Newspaper' is added to InTouch. The internal InTouch ID is 'NEWSPAPER'
  • The lead source is sent to the Connector
  • The Connector realizes that this record does not have a link to your system for this lead source
  • Depending on what support your API has, there are three possibilities
    1. Your system has 2 API calls, one to get a list of lead sources, another to create a lead source.  In this case API call #2 (as below) to get a list of lead sources will be attempted. If the match succeeds then we're all done. If the match does not succeed, then an attempt will be made to create the lead source as per API call #3 (as below).
    2. Your system only has an API call to get a list of lead sources.  All lead sources will be loaded, and the Connector will try a case insensitive match. If the match succeeds then we're all done. If the match does not succeed, then the synchronization fails.
    3. Your system only has an API call to create lead source. An attempt is made to save the lead source.  
      1. Note: It is also assumed that your system will have an update lead source API call as well.  If this API call does not exist, then no attempts at updates will be made. In this case, lead source names should never be changed in your system.

Turnup

This section details what is necessary to get a new client turned-up on the Connector.  The turn-up process for your system may vary slightly from other systems if there are any custom configuration options.

General Information required

  • The client ID number in your system
  • The club ID numbers in your system (One for every club)
  • Connection information (not required for integrations with full SaaS platforms)
    • IP
    • Username/Password
    • Scheme (http/s)
  • Any custom configuration options built into the Connector for your platform