...
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.pdf”Overview”)
| Info | ||
|---|---|---|
| ||
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. |
...
- 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 guessedCurrently (April 2012)
- TLS (Transport Level Security i.e. SSL/HTTPS does not exist on the Connector web service API calls. This will be added in the next release of the Connector) 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 httphttps://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
...
- Provider ID - Each 3rd party integrating with the Connector will be given a unique ID which identifies youtext 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 and , members, ex-members) - the Connector has one call to save all types of users (i.e. both prospects and members). There is a user_type field which is used to differentiate between the two.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: httphttps://<domain>/connector/api/2011-11/user
...
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 |
|
...
| Code Block | ||
|---|---|---|
| ||
httphttps://<domain>/connector/api/2011-11/user?provider=PROVIDER_ID?client_id=xxxx&club_id=xxxx&recordID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<response xmlns="httphttps://www.intouchfollowup.com/api/2011-11"> <uuid>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</uuid> </response> |
...
| Code Block | ||
|---|---|---|
| ||
httphttps://<domain>/connector/api/2011-11/staff |
...
| Code Block | ||
|---|---|---|
| ||
httphttps://<domain>/connector/api/2011-11/leadsource |
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<response xmlns="httphttps://www.intouchfollowup.com/api/2011-11"> <uuid>cf912bbd-7d10-41a5-b37e-1e11beff4e0c</uuid> </response> |
Fetch Single Lead Source
| Code Block | ||
|---|---|---|
| ||
httphttps://<domain>/connector/api/2011-11/leadsource?provider=INTOUCH&client_id=1111&club_id=11111111-1111-1111-1111-111111111111&identifier=FACEBOOK |
...
| Code Block | ||
|---|---|---|
| ||
httphttps://<domain>/connector/api/2011-11/leadsource?provider=INTOUCH&client_id=1111&club_id=11111111-1111-1111-1111-111111111111 |
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<error xmlns="httphttps://www.intouchfollowup.com/api/2011-11"> <reason>UNKNOWN</reason> <errorUUID>cecfeef8-24ef-4107-8d8b-534ce6a999b8</errorUUID> <message>additional error details</message> </error> |
...