1. Getting Started

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

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

About

This document will outline the steps necessary to get your platform integrated with the Connector platform, which will 'connect' your platform with InTouch and multiple other 3rd-party platforms with no additional effort.  This document assumes you know what the Connector is and does not include an overview of it, please see the Overview page for that.

The first step in getting integrated is to talk to us so we can discuss the various options for integration. After discussion we can agree on what features will be supported and how the integration will work.

There are two main sub-documents within this guide.  Based on the features of the integration that are agreed upon, you will require either one or both

  • Connector Partner Integration Guide - This guide is required if you plan on receiving data from the Connector.  This is the most common use case (i.e. users created in InTouch are sent to your system)
  • Connector API Guide - This guide is required only if you plan on sending data to the Connector (i.e. users created in your system are sent to InTouch)

Integration Options

 

IMPORTANT

Before any technical details can be discussed, there needs be agreement on what level of functionality will be provided in the integration between InTouch and your system via the Connector.   This is extremely important as it has large implications on what the technical requirements will be.  You should not proceed further without a detailed work plan of what is to be built

 

The main questions that require an answer

  1. Is the integration going be a two way synchronization, or one way?  i.e. will you be receiving data, sending data, or both.  The most common and simple integration is usually one-way where users created in InTouch are automatically created in your system. 
    1. If you will be receiving data, then you will need the 'Conenctor Partner Integration Guide'
    2. If you will be sending data, then you will need the 'Connector API Guide'
  2. What data is going to be included?
    1. Prospects (a.k.a. leads) 
    2. Members
    3. Ex/Former members
  3. If prospects, is any additional data to be included?
    1. Staff Owner of Lead
    2. Lead Source of Lead
    3. Trial information

Depending on your answers to steps 2 and 3, various requirements will need to be met. For example, if you wish to receive prospects with a staff owner, your web service must provide a method for the Connector to get a list of staff.  The details of these requirements are outlined in the companion documents

General Information

This section outlines some common information about the Connector.

Clubs

The Connector is built on the concept of one fitness club (i.e. one physical location) belonging to one client.  One client may have many clubs (i.e. a 10 location chain) within it.  

Synchronizing Staff

This information only applies if your integration with the Connector is going to support including a staff owner for new prospects. Please see the sub-documents within the guide for additional staff notes when sending, or receiving, prospects

When a new client is launched on the Connector, it is more than likely that they have already been using one or more of the systems for awhile.  This means that each system may already have staff in it.  This presents a problem for integrations that will support assigning a staff owner to a prospect or a member.  Namely, how do we synchronize the staff list so that the staff in system A are mapped to the staff in system B?  

Note: the Connector does not attempt to create staff in any system. It only tries to associate existing staff records with each.  The reason for this is the complexity, overhead, and restrictions surrounding staff.  For example, in most systems the process of creating staff is not simple and requires setting attributes that the Connector knows nothing about (for example, roles or permissions).

The Connector attempts to associate existing staff records as follows:

  • To support staff, your API MUST provide a call to get a list of staff. If your system does not provide this call, we cannot support staff synchronization with your system.  
  • The Connector will make a call to fetch the list of all staff, and then attempt to make a match on the email address.
    • Note: If your system provides the ability to look for a specific staff by email address then we can use that as well
  • If the Connector cannot make a match on email address, then the look up fails.  At this point, any leads created that are assigned to the failed staff will be sent to your system with no staff assigned.  Your system must be able to handle receiving leads that do not have an owner and assign them correctly as you desire
  • If the Connector can make a match on the email address, then the staff synchronization is complete, and prospect records can be sent to your system with the correct staff ID
Synchronizing Lead Sources

This information only applies if your integration with the Connector is going to support including a lead source for new prospects. Please see the sub-documents within the guide for additional lead source notes when sending, or receiving, prospects

Synchronizing lead sources is very similar to synchronizing staff except if there is the ability to create a lead source, the Connector will use it.

  • To support lead sources, your API MUST provide a call to get a list of lead sources. 
    • Note that if this is not provided, and only a create call is provided, then InTouch will need to be considered the 'master' of the lead source list and all lead sources will be defined there and sent to your system
  • The Connector will make a call to fetch the list of all lead sources, and then attempt to make a match on the lead source name. 
    • Note: The comparison will be case in-sensitive.
    • Note: If your system provides the ability to look for a specific lead source by name then we can use that as well
  • If the Connector cannot make a match on name, then the look up fails.  
    • If your API provides a method to create a lead source, the Connector will then make a call to create the lead source in your system
    • If your API does not provide a method to create a lead source, then any leads created that are assigned to that failed lead source will be sent to your system with no lead source assigned.  Your system must be able to handle receiving leads that do not have a lead source