Date: June 8, 2011

Last Updated: April 9, 2012

Contributors:

Objective/Purpose

This document will outline the steps necessary to get your platform integrated with the Connector platform, which will allow instant an easy integration with multiple other 3rd-party platforms with no additional effort.
This document assumes the user knows what Connector is does not include an overview of it (please see or request “Connector – Overview.docx”)

Notes/Questions

The Connector is currently (as of April 2012) considered to be in stage 1 complete. This means that the system should be stable, but there will be missing features that are scheduled to be implemented in future stages. Email me (Collin) if you encounter any issues. Thanks.
Currently (April 2012) there is no security (i.e. username/password) on the web service calls. This will obviously change soon but for now it is simply ‘security through obscurity’ in the sense that the GUIDs provide a level of security because they effectively cannot be guessed

Introduction

In order to get your platform integrated with the Connector the following steps will occur

Agreement between parties on what functionality will be provided. Support for the following options is available
- Prospects
  - Creation of a prospect in your system when a prospect is added to the Connector from another system
  - Update of a prospect in your system when a prospect is updated in the Connector by another system
- Staff
- Lead Sources

Connector is built using ReST web services and currently supports XML payloads. JSON might be supported in the future if requested.
A Java library is available to communicate with Connector to ease your development should you be a Java shop
Currently, the available web services are
- User services - GET operation to fetch a user, POST operation to save (create/update) a user. URL: http://<domain>/connector/api/2011-11/user
- Staff services - GET operation to fetch a list of staff. URL: http://<domain>/connector/api/2011-11/staff
- Lead source services - GET operation to fetch a lead source, POST operation to save (create/update) a lead source. URL: http://<domain>/connector/api/2011-11/leadsource
Our QA environment which you can use to develop against is http://qa.intouchfollowup.com/connector/api/2011-11/user
Email cpeters@intouchfollowup.com to get set up. The process is that you will need to give us the club/location IDs on your side and we will match them to a test club/location in the InTouch system. Once that information has been entered into InTouch you can start making web service calls

Getting Started

In order to get your system integrated with the Connector the following steps must occur

Prospects - Your API must implement the following methods in order to allow the Connector to create prospects
1. Create prospect
2. Update prospect
3. Note: A single 'Save prospect' method is also acceptable
Members - Your API must implement the following methods in order to allow the Connector to create members
1. Create member
2. Update member
3. Note: A single 'Save member' method is also acceptable
4. Note: The process of converting a prospect to a member is unique per system.
Staff - Your API must implement the following methods in order for the Connector to sync staff
1. Fetch list of staff - The email address must be accessible in order for the Connector to associate certain records together
2. Create staff
3. Update staff
Lead Sources - Your API must implement the following methods in order for the Connector to sync lead sources
1. Fetch list of lead sources
2. Create lead source
3. Update lead source

Technical Discussion

Working With User Records

URL: http://<domain>/connector/api/2011-11/user

Fields:

Name	Description	Details
<firstname>	First name	Mandatory TBD - Restrictions (max length, etc..)
<lastname>	Last name	Mandatory TBD - Restrictions (max length, etc..)
<userStatus>	The status of the user	Mandatory Must be ‘ACTIVE’ or ‘INACTIVE’
<userType>	The type of the user	Mandatory Must be ‘PROSPECT’ or ‘MEMBER’
<birthdate>	Date of birth	Must be yyyy-mm-dd format
<gender>	Gender	Must be ‘M’ or ‘F’
<address1>	First address field	TBD - Restrictions (max length, etc..)
<address2>	Second address field (not supported in InTouch)	TBD - Restrictions (max length, etc..) Note: Currently InTouch only has one address field
<city>	City	TBD - Restrictions (max length, etc..)
<zipcode>	Zip Code or Postal Code	TBD - Restrictions (max length, etc..)
<state>	State or Province	TBD - Restrictions (max length, etc..)
<country>	Country (2 digit ISO code)	As per http://en.wikipedia.org/wiki/ISO_country_codes
<mobile>	Mobile number	TBD - Restrictions (max length, etc..)
<email>	Email address	TBD - Restrictions (max length, etc..)
<homePhone>	Home phone number	TBD - Restrictions (max length, etc..)
<workPhone>	Work phone number	TBD - Restrictions (max length, etc..)
<company>	Company	TBD - Restrictions (max length, etc..)

Fetching User Records

Fetching a user record simply requires two attributes included in a GET call to the user web service. Example:

Sample fetch URL using GET

http://<domain>/connector/api/2011-11/user?uuid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&provider=PROVIDER_ID

TODO - Example needs updating to include client_id/club_id

Sample return XML

<user>
   <providerInfo>
      <identifier>PROVIDER_ID</identifier>
      <clientID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</clientID>
      <clubID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</clubID>
      <recordID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</recordID>
   </providerInfo>
   <userInfo>
      <firstname>Foo</firstname>
      <lastname>Bar</lastname>
      <birthdate>1972-03-12</birthdate>
      <gender>M</gender>
      <userStatus>ACTIVE</userStatus>
      <userType>PROSPECT</userType>
      <address1>1234 Fake St</address1>
      <address2>Apartment 1a</address2>
      <city>Spuzzum</city>
      <zipcode>12345</zipcode>
      <state>WA</state>
      <country>US</country>
      <mobile>555-555-5555</mobile>
      <email>foo@bar.com</email>
      <homePhone>555-666-6666</homePhone>
      <workPhone>555-777-7777</workPhone>
      <company>Acme Widgets</company>
      <createdBy>INTOUCH</createdBy>
      <createdDate>2012-04-10T04:11:07.023Z</createdDate>
      <modifiedBy>INTOUCH</modifiedBy>
      <modifiedDate>2012-04-10T04:11:07.023Z</modifiedDate>
   </userInfo>
</user>

Saving User Records

Here is a sample piece of XML which should be POST’ed to the user web service (note: subject to change before launch)

Sample save XML

<user>
   <providerInfo>
      <identifier>PROVIDER_ID</identifier>
      <clientID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</clientID>
      <clubID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</clubID>
      <recordID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</recordID>
   </ providerInfo >
   <userInfo>
      <firstname>Foo</firstname>
      <lastname>Bar</lastname>
      <userStatus>ACTIVE</userStatus>
      <userType>PROSPECT</userType>
   </userInfo>
</user>

Details

The <user> tag needs to wrap the entire record
Note: Though shown as GUID/UUIDs, the values for the IDs (identifiers) can effectively be anything; it does not have to be a real GUID/UUID.
- The value of the <recordID> tag is YOUR identifier. ALL communication with the Connector is done using your identifier.
The <providerInfo>tag provides all the information necessary for Connector to process the record. This includes
- <clientID>: The ID number of the client for this user record in the source provider (i.e. your system)
- <clubID>: The ID number of the location for this user record in the source provider.
- <recordID>: The ID number of the user in the source provider
- <identifier>: This is a set identifier which will be used to know who sent the record (i.e. the provider). This value will be given to you and must be sent for every web service call
The <userInfo> tag provides all the details for the actual user. Please see the user fields table for full details.

Result

The following XML is returned from a save call

Sample return XML

<response xmlns="http://www.intouchfollowup.com/api/2011-11">
   <uuid>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</uuid>
</response>

The return value contains a <response> element which contains the UUID of the record within the Connector.

Staff

The Connector supports the saving of staff as well. The staff web service has a different URL but is syntactically identical to the user web service with the exception that the <user_type> element must be STAFF.

Staff Web Service URL

http://<domain>/connector/api/2011-11/staff

Lead Sources

The Connector supports lead sources as well.

Lead Web Service URL

http://<domain>/connector/api/2011-11/leadsource

Save Lead Source

Request

<leadSource>
   <providerInfo>
      <identifier>INTOUCH</identifier>
      <clientID>1111</clientID>
      <clubID>11111111-1111-1111-1111-111111111111</clubID>
      <recordID>FACEBOOK</recordID>
   </providerInfo>
   <leadInfo>
      <name>Facebook</name>
      <active>true</active>
   </leadInfo>
</leadSource>

Response

<response xmlns="http://www.intouchfollowup.com/api/2011-11">
   <uuid>cf912bbd-7d10-41a5-b37e-1e11beff4e0c</uuid>
</response>

Fetch Lead Source

TODO

URL: http://<domain>/connector/api/2011-11/leadsource?provider=PROVIDER_ID&identifier=FACEBOOK

Fetch Lead Sources

TODO

URL: http://<domain>/connector/api/2011-11/leadsource?provider=PROVIDER_ID&client_id=xxx&club_id=xxx

Errors

For those unfamiliar with ReSTful style web services, it is actually built on top of regular old HTTP. This means that (technically speaking) if you make a request to fetch a user and that user isn’t found you will actually get an HTTP response status of 404. I say technically speaking because the implementer of a web service doesn’t have to adhere to that. It is perfectly acceptable to give a normal HTTP response status of 200 and just have a different payload. All implementers need to be aware of how each web service works of course. Connector will be implemented in that if any type of real error occurred in the backend, an HTTP response code in the 400-599 range will be returned (these are the error codes).

In regards to real errors: from a high level this type of error should be returned depending on what has happened

Sample error XML

<error xmlns="http://www.intouchfollowup.com/api/2011-11">
   <reason>UNKNOWN</reason>
   <errorUUID>cecfeef8-24ef-4107-8d8b-534ce6a999b8</errorUUID>
   <message>additional error details</message>
</error>

Details

<reason>: will be an identifier that will try to narrow down the type of error. Will show ‘UNKNOWN’ if the error type isn’t known. Current examples are: ‘VALIDATION’, ‘DATABASE’
<errorUUID>: This is a regular old UUID which you can pass on to InTouch support which will simply let us have an easy way to find the error in the Connector logs
<message>: the actual details of the error. Note that currently this is just the stack trace from the real error in the backend so some errors might be cryptic

Developer Guide

Objective/Purpose

Notes/Questions

Introduction

Getting Started

Technical Discussion

Working With User Records

Fetching User Records

Saving User Records

Details

Staff

Lead Sources

Save Lead Source

Fetch Lead Source

Fetch Lead Sources

Errors

Details