POSTing to ClientTether 2020February 10, 2020
Send New Leads to ClientTether via Form Post 2020
We are very excited to announce this enhancement of the original method for Posting Leads to ClientTether. This 2020 version is meant to bridge the gap between a simple form POST and our complex API 2.0.
This is a simple yet powerful process that is only used for inserting New Leads into ClientTether. If you need a more in depth API option, please review: ClientTether API Doc v2.
ClientTether is all about automation. Inside of ClientTether, you can connect a Lead Source to an Action Plan. Hence, if you use this POST process and send a new lead with a specific Lead Source, ClientTether will initiate the Connection Action Plan. At the bottom of this page is a video explaining a few tips for Posting new leads into ClientTether.
Identify which Lead Source you plan to use. Below is an image of the Lead Source page under Settings for my sample account. The Web_Key at the top-right of the Image is the Web_Key for the account itself. If you POST a New Lead with that Web_Key, the Default Action Plan will be initiated. The other Web_Keys are unique identifiers for your account and a specific Lead Source. If you POST a New Lead with a Web_Key associated to a Lead Source then the associated Connection Action Plan will be initiated.
You must submit a Web_Key with every Form Post.
Prepare your web form
To use your own custom forms and have them work properly with ClientTether:
- The form will need to POST to the URL shown here: https://api.clienttether.com/v1/external-api/external-form-lead
- While you can use any of the field names from the Client Parameters table listed below, there are a couple of rules to follow:
- The field names are case sensitive
- Mandatory fields are:
- web_key and
- name OR
- both firstName and lastName
Client Parameters Table
|web_key||This is a mandatory field. Its value is dependent on the Prerequisite steps described above. If the Lead Source is tied to an Action Plan, it will be initiated on insert of Client.||String|
|name||First and Last name separated by an encoded space. This field will override firstName and lastName fields if all three fields are used.||String|
|firstName||Required for Create_Client||String|
|lastName||Required for Create_Client||String|
|phone||10 digit North America phone numbers only. This is assumed to be a Mobile phone||Ten digits only. No formatting accepted|
|smsok||1 if okay to text, 0 if not. defaults to 1 if not provided||[1, 0]|
|second_phone||Secondary Phone||Ten digits only. No formatting accepted|
|Email address of the lead must be unique for each client. Otherwise a Duplicate Record Notification will be triggered.||Well formatted email string|
|state||US states and CA Province||2 letter abbreviation only|
|zip||Postal code:US and CA acceptable5 Digit Zip5-4 Digit Zip5-4-2 Digit Zip A1A 1A1, where A is a letter and 1 is a digit, with a space separating the third and fourth characters|
|tag||Comma separated list of tags. New tags will be created if needed|
|job_title||Title for Person||String|
|deal_closed||Indicates if the deal (of Deal Size) is closed = sold.||[1,0]|
|age||We do not accept Birthdays!||Whole Number|
|material_status||[Single, Married, Divorced]|
|This is for a Facebook Profile ID. Mine would be: hall303 and we will generate the complete link:https://www.facebook.com/hall303||String|
|This field is for a LinkedIn profile. Mine would be: itmanagementconsultingAnd we will generate the complete link: https://www.linkedin.com/in/itmanagementconsulting/||String|
|clients_date_last||Each Account Owner can use this field for whatever they choose. I.E. Last date of service||YYYY:MM:DD|
|clients_date_next||Each Account Owner can use this field for whatever they choose. I.E. Next date of service||YYYY:MM:DD|
|new_lead_notification||This determines if the Account Owner will receive notice that they have a “New Lead”. The standard notices will be sent: Email, Text and Software Notification.0= No Notifications (default)1= Software Notification Only2= All Three Notifications: Email, Text and Software||[0,1,2] String|
|contact_type||The system handles 5 types of Contacts. UI text values: [Client, Employee, Partner, Vendor, Other]DB values [1, 2, 3, 4, 5]If nothing is supplied in this value for any CRUD, the system will default to 1.||[1, 2, 3, 4, 5] String|
|assigned_user_id||This is a User’s ID that is assigned to manage the Contact||String|
|notes||Whatever Text you enter in this field will be inserted as a History Note when the Contact is created. This is designed to match the process of Posting 2019.||String|
|OnSuccessURL||If you do not use asynchronous communication, then you can send a URL where we will push your clients on a successful insert. Include the http:// or https:// to have greatest control.|
|OnErrorURL||If you do not use asynchronous communication, then you can send a URL where we will push your clients if the post fails for any reason. We will send an error code with more details. See Appendix Error Codes. Include the http:// or https:// to have greatest control.|
Simple web form example:
<form action=”https://api.clienttether.com/v1/external-api/external-form-lead” method=”post”>
<input type=”text” name=”firstName” value=””> <BR>
<input type=”text” name=”lastName” value=””><BR>
<input type=”text” name=”phone” value=””> <BR>
<input type=”text” name=”email” value=””> <BR>
<textarea rows=”4” cols=”50” name=”notes” value=””></textarea> <BR><BR>
<input type=”hidden” name=”web_key” value=”CT_XXXXXX”>
<input type=”hidden” name=”OnSuccessURL” value=”http://SSSSS.com“>
<input type=”hidden” name=”OnErrorURL” value=”http://EEEEEE.com“>
<input type=”submit” value=”Submit”>
*** If you are new to Form POSTing visit W3Schools
In the sample code above, replace CT_XXXXXX with the right web_key value from your ClientTether system to activate your lead source connection plan.
When entering values for the optional URL fields please be sure and include the http:// or https:// to have greatest control. Remember: enter your own valid URLs for the OnSuccessURL and OnErrorURL. The above is just an example. However, If you are using asynchronous communication, remove these two lines from your form and we will respond with a JSON code
We have expanded the acceptable parameters for 2020 Client Info. We will consider all parameters mentioned in the Client Parameter Table above as “Reserved” parameter names. We will also accept any non-reserved parameter name and its value as a simple String (striping all HTML).
|Any non-reserved parameter name.||There is a current Limit of 100 characters for this string length.||String|
<form action …
<input type=”text” name=”Favorite Chocolate” value=””>
Since Favorite Chocolate is not a reserved parameter, we would create a custom field name Favorite Chocolate and put the entered value in the Custom Field.
Use “Embed Code” (NOT Weebly’s form tool) to Paste in the form as shown in the video. This is the only way to POST to a custom website from Weebly that we found at the time of this publication. If using a Form POST is too complicated, try using ClientTether’s Parsers
Appendix – Return Codes
ct101 Invalid Web_Key
ct102 Name Not Received
ct103 Duplicate Client creation attempted