...
- Users (prospects and 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.
- Staff
- Lead sources
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>
...
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: http://<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 |
| <state> | |
State or Province<address2> | Second address field (not supported in InTouch) | <mobile> | Mobile number
| |
<country> | Country (2 digit ISO code) | |||
| ||||
<city> | City |
| <email> | |
Email address<zipcode> | Zip Code or Postal Code |
| ||
<homePhone> | Home phone number<state> | State or Province |
| <workPhone> |
Work phone <country> | Country (2 digit ISO code) | |||
<mobile> | Mobile number |
| ||
<company><email> | CompanyEmail address |
|
Fetching User Records
...
<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:
...
| Code Block |
|---|
<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.
| Code Block | ||
|---|---|---|
| ||
http://<domain>/connector/api/2011-11/staff |
Synchronizing Staff
When a new client is launched on the Connector, it is more than likely that they have been using one or more of the systems being integrated for awhile. This means that each system may already have staff in it. This presents a problem for systems that support assigning a staff owner to a prospect or a member. The question is, how do we synchronize the staff list so that the staff in system A are mapped to the staff in system B. Note that the Connector does not attempt to create staff in any remote 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 system 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:
- 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
Lead Sources
The Connector supports lead sources as well.
| Code Block | ||
|---|---|---|
| ||
http://<domain>/connector/api/2011-11/leadsource |
Synchronizing Lead Sources
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.
...
- 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
...
- Note: The comparison will be case in-sensitive.
...
- 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.
| Code Block | ||
|---|---|---|
| ||
http://<domain>/connector/api/2011-11/staff |
Lead Sources
The Connector supports lead sources as well.
| Code Block | ||
|---|---|---|
| ||
http://<domain>/connector/api/2011-11/leadsource |
Save Lead Source
| Code Block | ||||
|---|---|---|---|---|
| ||||
<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> |
...