POSTing to ClientTether 2020

February 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.

Prerequisite

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:

  1. The form will need to POST to the URL shown here: https://api.clienttether.com/v1/external-api/external-form-lead
  2. While you can use any of the field names from the Client Parameters table listed below, there are a couple of rules to follow:
    1. The field names are case sensitive
    2. Mandatory fields are:
      1. web_key and 
      2. EITHER 
        1. name OR 
        2. both firstName and lastName

Client Parameters Table

KeyDescriptionLimits
web_keyThis 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
nameFirst and Last name separated by an encoded space. This field will override firstName and lastName fields if all three fields are used.String
firstNameRequired for Create_Client String
lastNameRequired for Create_ClientString
phone10 digit North America phone numbers only. This is assumed to be a Mobile phoneTen digits only. No formatting accepted
smsok1 if okay to text, 0 if not.  defaults to 1 if not provided[1, 0]
second_phoneSecondary PhoneTen digits only. No formatting accepted
email Email address of the lead must be unique for each client. Otherwise a Duplicate Record Notification will be triggered.Well formatted email string
addressstreet addressString
citycityString
stateUS states and CA Province2 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
compNameCompany NameString
tagComma separated list of tags. New tags will be created if needed
job_titleTitle for PersonString
deal_size
Whole Number
deal_closedIndicates if the deal (of Deal Size) is closed = sold.[1,0]
ageWe do not accept Birthdays!Whole Number
education
String
gender
[M, F]
high_net_worth
Whole Number
home_owner_status
[Own, Rent]
household_income
Whole Number
length_of_residence
Whole Number
market_value
Whole Number
material_status
[Single, Married, Divorced]
occupation
String
presence_of_children
[1,0]
presence_of_pets
[1,0]
anniversary_1
YYYY:MM:DD
anniversary_2
YYYY:MM:DD
facebookThis is for a Facebook Profile ID. Mine would be: hall303 and we will generate the complete link:https://www.facebook.com/hall303String
linkedinThis field is for a LinkedIn profile.  Mine would be: itmanagementconsultingAnd we will generate the complete link: https://www.linkedin.com/in/itmanagementconsulting/String
twitter
String
client_category*Maids specificString
whiteboard
String
clients_date_lastEach Account Owner can use this field for whatever they choose. I.E. Last date of serviceYYYY:MM:DD
clients_date_nextEach Account Owner can use this field for whatever they choose. I.E. Next date of serviceYYYY:MM:DD
new_lead_notificationThis 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_typeThe 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_idThis is a User’s ID that is assigned to manage the ContactString
notesWhatever 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
OnSuccessURLIf 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.
OnErrorURLIf 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”>
  First name:<BR>
  <input type=”text” name=”firstName” value=””>  <BR>
  Last name:<BR>
  <input type=”text” name=”lastName” value=””><BR>
  Phone:<BR>
  <input type=”text” name=”phone” value=””>  <BR>
  email:<BR>
  <input type=”text” name=”email” value=””>  <BR>
  Notes:<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”>
</form> 

*** 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 
{“Message”: “Success”}


Expansion Parameters

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).

KeyDescriptionLimits
Any non-reserved parameter name.There is a current Limit of 100 characters for this string length.String

Expansion Example

<form action …

  Favorite Chocolate:<BR>
  <input type=”text” name=”Favorite Chocolate” value=””>

</form>

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.

Weebly Example

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

error_code msg

ct101 Invalid Web_Key

ct102 Name Not Received

ct103 Duplicate Client creation attempted

Ct104 TBD

Ct105 TBD

String Example

?error_Code=ct101&msg=Invalid Wed_Key

{message: Success}