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
To use the SendX JavaScript API, you need to install the SendX snippet on your website. Each SendX team account has a unique snippet that can be found under Settings > Site Code Snippet
The SendX JavaScript snippet loads asynchronously, so it won’t affect the page load time of your website.
All requests follow the same structure.
_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 the Google Analytics API follows..
SendX JavaScript API has two methods:
Identify
Track
The 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 the contact already exists, 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, 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 can be created or 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, will also 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 the email of an already existing contact needs to be updated then specify current email under email property and updated email under new Email 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 is used to track a contact. You can use this API to add or remove tags from a contact.
Properties:
AddTags: Array of tags to be added to a contact.
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 be executed. For e.g.:
On user registration, start the onboarding drip for the user.
When the Account Upgrade tag is added, move the user to the paid user list and start the account expansion drip.
On removal of the trial user tag, start the upsell drip for users who completed the trial.
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" }
