...
| Code Block |
|---|
| language | html/xml |
|---|
| title | Request |
|---|
|
<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.
...
The solution of how the Connector attempts to overcome these issues is as follows:
Lead Sources
The Connector supports lead sources as well.
...
- At minimum you must provide a call to get a list of staff
- The Connector will make a call to fetch the list of all staff, and then attempt to make a match on the email address.
- If there is no match, and there is a web service call to create staff, then the staff will be created
- Why this way? This method has the lowest possibilities for errors.
Lead Sources
The Connector supports lead sources as well.
| Code Block |
|---|
| title | Lead Web Service URL |
|---|
|
http://<domain>/connector/api/2011-11/leadsource |
Save Lead Source
| Code Block |
|---|
| language | html/xml |
|---|
| title | Request |
|---|
|
<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> |
| Code Block |
|---|
| language | html/xml |
|---|
| title | Response |
|---|
|
<response xmlns="http://www.intouchfollowup.com/api/2011-11">
<uuid>cf912bbd-7d10-41a5-b37e-1e11beff4e0c</uuid>
</response> |
Fetch Single Lead Source
| Code Block |
|---|
|
http://<domain>/connector/api/2011-11/leadsource?provider=INTOUCH&client_id=1111&club_id=11111111-1111-1111-1111-111111111111&identifier=FACEBOOK |
| Code Block |
|---|
| language | html/xml |
|---|
| title | Response |
|---|
|
<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
| Code Block |
|---|
|
http://<domain>/connector/api/2011-11/leadsource |
...
?provider=INTOUCH&client_id=1111&club_id=11111111-1111-1111-1111-111111111111 |
| Code Block |
|---|
| language | html/xml |
|---|
| title | RequestResponse |
|---|
|
<leadSource> <leadSources>
<providerInfo><leadSource>
<identifier>PROVIDER_ID<<createdBy>INTOUCH</identifier>createdBy>
<clientID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</clientID>
<clubID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</clubID>
<recordID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</recordID><createdDate>2012-04-17T21:58:47.758Z</createdDate>
</providerInfo> <modifiedBy>INTOUCH</modifiedBy>
<leadInfo> <name>Facebook</name><modifiedDate>2012-04-17T21:59:29.673Z</modifiedDate>
<active>true<<name>Facebook</active>name>
</leadInfo> </leadSource> |
| Code Block |
|---|
| language | html/xml |
|---|
| title | Response |
|---|
|
<response xmlns="http://www.intouchfollowup.com/api/2011-11"> <active>true</active>
</leadSource>
<leadSource>
<createdBy>INTOUCH</createdBy>
<uuid>cf912bbd<createdDate>2012-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
| Code Block |
|---|
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
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).
...