This guide details various functions associated with our Javascript API
SendX Javascript API enables you to add contacts, associate tags with them and update custom fields. This guide details various functions associated with our Javascript API.
-
Installing Javascript Snippet
-
Sending API Requests
-
API Methods
Installing Javascript Snippet
To use SendX Javascript API you need to have SendX snippet installed on your website. Each SendX team account has a unique snippet that can be found under Settings > Site Code Snippet
SendX Javascript snippet gets loaded asynchronously and hence it won't affect page load time of your website.
Sending API Requests
All requests follow the same pattern.
_scq.push(["methodName", { key: "value", ... }]);
API requests are executed asynchronously so you can safely place them anywhere on the page. The conventions are similar to what google analytics API follows.
API Methods
SendX Javascript API has two methods:
-
Identify
-
Track
Identify API Method
Identify API Method is used to attach data to a visitor. If a contact is not yet created then we will create the contact. In case contact already exists then we update it.
Example Request:
_scq.push(["identify", { email: "john.doe@gmail.com ",
firstName: "John", lastName: "Doe", birthday: "1989-03-03", customFields: { "Designation": "Software Engineer", "Age": "27", "Experience": "5"},
tags: ["Developer", "API Team"],
}]);
Note that tags are an array of strings. In case they don't exist previously then API will create them and associate them with the contact.
Similarly if a custom field doesn't exist then it is first created and then associated with the contact along-with the corresponding value. In case custom field exists already then we simply update the value of it for the aforementioned contact.
Custom Fields are associated with data types and which be created and edited inside the app. If a custom field is not present inside the app and an API call is made containing it, a custom field with type 'string' is created and the value set. For custom fields with data type 'number', values can be added to or subtracted from existing values. This can be done by using "++" or "--" operator before the number(e.g. "customField_name": "++34" would increase the value of existing "customField_name" in SendX for the contact. If it doesn't already exist, the value '- 34' would be inserted for it).
We don't delete any of the properties based on identify call. What this means is that if for the same contact you did two API calls like:
API Call A
_scq.push(["identify", { email: "john.doe@gmail.com ", firstName: "John", birthday: "1989-03-03", customFields: { "Designation": "Software Engineer"},
tags: ["Developer"],
success: function(){console.log("identify call successful");},
failure: function(){console.log("identify failed");},
}]);
API Call B
_scq.push(["identify", {
email: "john.doe@gmail.com ",
customFields: { "Age": "29"},
tags: ["API Team"],
success: function(){console.log("identify call successful");},
failure: function(){console.log("identify failed");},
}]);
The the final contact will have firstName as John, birthday as 1989-03-03 present. Also both tags Developer and API Team shall be present along with custom fields Designation and Age.
Properties:
-
firstName: type string
-
lastName: type string
-
email: type string
-
newEmail: type string
-
company: type string
-
birthday: type string with format YYYY-MM-DD eg: 2016-11-21
-
customFields: type map[string]string
-
tags: type array of string
-
success: Optional. Callback function which is executed on successful completion of request.
-
failure: Optional. Callback function which is executed when request fails or timeouts.
In case email of an already existing contact needs to be updated then specify current email under email property and updated email under newEmail property.
Response:
{ "status": "200", "message": "OK", "data": { "encryptedTeamId": "CLdh9Ig5GLIN1u8gTRvoja", "encryptedId": "c9QF63nrBenCaAXe660byz", "tags": [ "API Team", "Tech" ], "firstName": "John", "lastName": "Doe", "email": "john.doe@gmail.com ", "company": "", "birthday": "1989-03-03", "customFields": { "Age": "29", "Designation": "Software Engineer" } } }
Track API Method
Track API Method is used to track a contact. You can add or remove tags from a contact using this API.
Properties:
-
addTags: Array of tags to be added to a contacts
-
removeTags: Array of tags to be removed from a contact
-
success: Optional. Callback function which is executed on successful completion of request.
-
failure: Optional. Callback function which is executed when request fails or timeouts.
You can have automation rules based on tag addition as well as tag removal and they will get executed. For eg:
-
On user registration tag start on-boarding drip for him / her.
-
Account Upgrade tag start add user to paid user list and start account expansion drip.
-
On removal of trial user tag start up-sell trial completed users drip.
Example Request:
> _scq.push(["track", {
"addTags": ["blogger", "female"],
success: function(){console.log("track call successful");},
failure: function(){console.log("track call failed");},
}]);
> _scq.push(["track", {
"addTags": ["paid user"], "removeTags": ["trial user"],
success: function(){console.log("track call successful");},
failure: function(){console.log("track call failed");},
}]);
Response:
> { "status": "200", "message": "OK", "data": "success" }
Did this answer your question?