POSTing to ClientTether 2020POSTing to ClientTether 2020 - ClientTether Support

Search

Integrations/Tools

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:

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:
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

Key	Description	Limits
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 0 if not provided	[1, 0]
second_phone	Secondary Phone	Ten 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
address	street address	String
city	city	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
compName	Company Name	String
tag	Comma separated list of tags. New tags will be created if needed
job_title	Title for Person	String
deal_size		Whole Number
deal_closed	Indicates if the deal (of Deal Size) is closed = sold.	[1,0]
age	We 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
facebook	This is for a Facebook Profile ID. Mine would be: hall303 and we will generate the complete link:https://www.facebook.com/hall303	String
linkedin	This 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 specific	String
whiteboard		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.
external_id	Foreign Key Integration with CT	Integer

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="https://google.com">
  <input type="hidden" name="OnErrorURL" value="https://apple.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 (NOT ACCOUNT web_Key, It should be your Lead Source web_key) value from your ClientTether system to activate your lead source connection plan.

OPTIONAL OnSuccessURL and OnErrorURL
Using the OnSuccessURL and OnErrorURL are optional. If you are using asynchronous communication when POSTing to our system, remove these two lines from your form and we will respond with JSON code {“Message”: “Success”} or {“Message”: “Error”}

When entering values for the optional fields ( OnSuccessURL and OnErrorURL ) please be sure and include the http:// or https:// to have greatest control. The System will return the JSON to the correct URL that your system is expected to catch and process. { "url": "https://google.com"}

Remember: enter your own valid URLs for the OnSuccessURL and OnErrorURL. The above is just an example.

If you want our server to process the OnSuccessURL and OnErrorURL then you must add an additional hidden field:
<input type="hidden" name="form_submit_redirect" value="1">

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

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

Expansion Example

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}

https://youtu.be/B5esa9sYKME