3. API Guide
Table Of Contents
Introduction
This document describes the Connector web service API. 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 Connector API which is used for INCOMING data. That is data that is coming from your platform and going to other platforms, via the Connector. If the integration agreement that you have decided upon with InTouch is only for outgoing data (that is, your system only receives data) then this document does not apply. Please see the companion document "Connector Partner Integration Guide" for details on receiving data.
Notes
- Currently (April 2012) there is no security (i.e. username/password or API token) on the Connector web service API 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
- TLS (Transport Level Security i.e. SSL/HTTPS) is available but not yet enforced. Take care to ensure that any API calls that you make to the Connector are done with TLS. You should never make calls to the Connector without TLS (i.e. unecrypted)
- A Java library is available to communicate with Connector to ease your development should you be a Java shop
- Our QA environment which you can use to develop against is https://qa.intouchfollowup.com/connector/api/2011-11/user. Note that before actual web service calls can be made, work must be done by InTouch in order to make it aware of your platform
General Info
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). All of the entities that the Connector works with (prospects, members, staff, lead sources) must belong to one client, and one club within that client. It is important to note that all communication with the Connector is done using the IDs from YOUR SYSTEM. While you can track the GUIDs that the Connector returns to you, you should not communicate with the Connector using these GUIDs. Think of this way, when you make a call to the Connector you are saying: I am 'PARTNER X', here is a prospect record that has the ID 123456 in my system, and it belongs to club 123 within the client 456.
All calls made to the Connector must include
- Provider ID - Each 3rd party integrating with the Connector will be given a unique text identifier
- Client ID - As this is a multi-tenant system all requests must include the client ID.
- Club ID - Each entity must belong to a club and as such the club ID is required
- Record ID - The ID within your system that you are working with
Web Service API Calls Available
- Users (prospects, members, ex-members) - the Connector has one call to save all types of users. There is a user_type field which is used to differentiate between them
- Staff
- Lead sources
Validation
The Connector is very forgiving with validation as it cannot be the lowest common denominator of all the systems being integrated. Imagine that the Connector was restrictive with validation and only allowed a maximum first name length of 20 characters. This would mean that every system receiving data from the Connector would only have a 20 character first name, even if all the integrated systems actually supported 40 characters! So the Connector only classifies 4 fields as mandatory (first name, last name, user type, user status), and is very open as to the lengths of these fields. Generally, it is assumed that data is validated before it gets sent to the Connector (for example, InTouch validates all data before sending anything to the Connector).
Working With User Records
URL: https://<domain>/connector/api/2011-11/user
Fields:
Name | Description | Details |
<firstname> | First name |
|
<lastname> | Last name |
|
<userStatus> | The status of the user |
|
<userType> | The type of the user |
|
<birthdate> | Date of birth |
|
<gender> | Gender |
|
<address1> | First address field |
|
<address2> | Second address field (not supported in InTouch) |
|
<city> | City |
|
<zipcode> | Zip Code or Postal Code |
|
<state> | State or Province |
|
<country> | Country (2 digit ISO code) | |
<mobile> | Mobile number |
|
<email> | Email address |
|
<homePhone> | Home phone number |
|
<workPhone> | Work phone number |
|
<company> | Company |
|
Fetching User Records
Fetching a user record simply requires two attributes included in a GET call to the user web service. Example:
https://<domain>/connector/api/2011-11/user?provider=PROVIDER_ID&clientID=xxxx&clubID=xxxx&recordID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
<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
<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.
- Reminder: 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
<response xmlns="https://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. Note: Though you may save this ID in your system it is not necessary as all communication with the Connector is done using your own identifiers
Saving Lead Data
For prospects, the Connector allows you to pass in a lead (aka opportunity) owner, as well as a lead source. The request looks like
<user> <providerInfo ... snipped for brevity /> <userInfo ... snipped for brevity /> <leadInfo> <leadSource>FACEBOOK</leadSource> <ownerID>6b85b27e-5028-4b23-a1e2-f3aa5bf3909b</ownerID> </leadInfo> </user>
- Note that the <leadInfo> section is optional, and that the <leadSource> and <ownerID> fields can either both be set, or just one of them can be set. If your system does not support staff, or lead sources, then these can be ignored
- The ID values for the staff owner and lead source are again, the ID values from your system.
Staff Are Users Too
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 <userType> element must be STAFF.
https://<domain>/connector/api/2011-11/staff
Lead Sources
The Connector supports lead sources as well.
https://<domain>/connector/api/2011-11/leadsource
Save Lead Source
<leadSource> <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> <leadInfo> <name>Facebook</name> <active>true</active> </leadInfo> </leadSource>
<response xmlns="https://www.intouchfollowup.com/api/2011-11"> <uuid>cf912bbd-7d10-41a5-b37e-1e11beff4e0c</uuid> </response>
Fetch Single Lead Source
https://<domain>/connector/api/2011-11/leadsource?provider=INTOUCH&clientID=1111&clubID=11111111-1111-1111-1111-111111111111&identifier=FACEBOOK
<leadSource> <providerInfo> <identifier>INTOUCH</identifier> <clientID>1111</clientID> <clubID>11111111-1111-1111-1111-111111111111</clubID> <recordID>FACEBOOK</recordID> </providerInfo> <leadInfo> <createdBy>INTOUCH</createdBy> <createdDate>2012-04-17T21:58:47.758Z</createdDate> <modifiedBy>INTOUCH</modifiedBy> <modifiedDate>2012-04-17T21:59:29.673Z</modifiedDate> <name>Facebook</name> <active>true</active> </leadInfo> </leadSource>
Fetch Lead Sources
https://<domain>/connector/api/2011-11/leadsource?provider=INTOUCH&clientID=1111&clubID=11111111-1111-1111-1111-111111111111
<leadSources> <leadSource> <createdBy>INTOUCH</createdBy> <createdDate>2012-04-17T21:58:47.758Z</createdDate> <modifiedBy>INTOUCH</modifiedBy> <modifiedDate>2012-04-17T21:59:29.673Z</modifiedDate> <name>Facebook</name> <active>true</active> </leadSource> <leadSource> <createdBy>INTOUCH</createdBy> <createdDate>2012-04-17T21:58:47.758Z</createdDate> <modifiedBy>INTOUCH</modifiedBy> <modifiedDate>2012-04-17T21:59:29.673Z</modifiedDate> <name>Corporate</name> <active>true</active> </leadSource> </leadSources>
Errors
The Connector is build using ReSTful style web services, which is simply regular old HTTP. This means that 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 'Not Found'. Similarly, if any type of error occurrs 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
<error xmlns="https://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
Appendix
Always returning the InTouch UUID in a GET call
In order to send referral leads through the web lead form service, the InTouch user UUID of the person who referred the new lead is required. This page outlines the web service call to GET an InTouch member UUID for an existing record.
Note: InTouch must enable this feature before you will get the extra UUID
Once the feature is enabled, the GET call to the web service will return the InTouch UUID in the extraProviderIDs section.
<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> <extraProviderIDs> <inTouchID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</inTouchID> </extraProviderIDs> <userInfo> <firstname>Foo</firstname> <lastname>Bar</lastname> ... </userInfo> </user>