API Quick Start Guide
Welcome to Sugar Market's, formerly known as Salesfusion's, RESTful API.
The Sugar Market API exposes the core entities of the Sugar Market automated marketing platform to allow integrators, partners, and customers the opportunity to manipulate and retrieve backend state.
Base URL
The base URL for connecting to the Sugar Market API is follows:
https://developer.salesfusion.com/api/2.0/
Authentication
The Sugar Market API utilizes HTTP Basic Authentication through TLS/SSL (i.e. HTTPS). In order to authenticate an HTTP request, the request must contain a properly formatted Authorization field in the HTTP headers. This requires that the user credentials be formatted correctly, encoded as a base64 string, and included in the Authorization field.
The sample code below demonstrates this process:
// The Basic Authentication format expected is user@domain:password
// (i.e. john@domain:password, or john@email.tld@domain:password)
private static string user_credentials = string.Format(
"{0}@{1}:{2}", api_username, api_domain, api_password);
private static string base64_user_credentials = Convert.ToBase64String(
Encoding.ASCII.GetBytes(user_credentials));
public static string AuthorizationHeader = string.Format(
"Basic {0}", base64_user_credentials);
The resulting AuthorizationHeader string looks as follows:
Basic YXBpX3VzZXJAc3VnYXI3NS5kZXY6Unp6TnM2WVlPcERlNHcxWQ==
This string should subsequently be set as the Authorization field in the HTTP headers for all requests sent to the API as shown below:
Authorization: Basic YXBpX3VzZXJAc3VnYXI3NS5kZXY6Unp6TnM2WVlPcERlNHcxWQ==
As mentioned before, for security, all requests made against the API must be made through TLS/SSL over port 443 (the default port for HTTPS).
Note: the format of the username within the authorization header should be [username]@[login domain] where the login domain is the domain you configured during the creation of your Sugar Market account.
Authorization
A unique API username and user account should be created and authorized to interact with the API. This user account should be separate from any user account associated with the marketing or sales process and requires API Access permissions in order to access the API. In order to authorize a user account for API Access, please follow these steps:
1) Log into the Sugar Market application using an admin user account.
2) Navigate to Account Configuration and select Roles under the Administrator navigation tree.
3) Create a new role named API Access and check Data Access and Navigation Access.
4) Under the Navigation Access tab, select "Customer-Wide - API Access" and add it to the Access Provided list.
5) Click Save and Return.
6) Navigate to User administration and open the target user account for editing.
7) In the user preferences view, select the Roles tab.
8) Click Add New Role and select the previously configured API Access role from the drop-down menu.
9) Click Save.
Alternatively, you can authorize a user account directly to access the API without creating an API Access user role. To do so, follow these steps:
1) Log into the Sugar Market application using an admin user account.
2) Navigate to User administration and open the target user account for editing.
3) Under the Navigation tab, select "Customer-Wide - API Access" and add it to the Access Provided list.
For help with authentication or authorization please file a case with the Sugar Support team.
Date Time Formats
All date/timestamp values passed to and received from the API will be in ISO 8601 format. Timestamp values will reflect Coordinated Universal Time (UTC).
Integrating the Sugar Market iFrame feature
The Sugar Market iframe component provides an easy way to integrate marketing automation data and features into your own application. The iframe is contact-specific and requires the following three query string parameters in order to load properly:
1) orgid = A unique ID assigned to your Sugar Market instance. This value can be retrieved using the /tenant/info endpoint. The returned crm_org_id field reflects your orgid.
2) userid = Your user id as recorded within the CRM. This value can be retrieved using the /tenant/info endpoint. The returned crm_id field reflects your userid.
3) recordid = The contact ID of interest as reflected by the crm_id field returned from the /contacts/<id> endpoint
The iframe URL is constructed as follows:
https://iframe.salesfusion360.com/?userId=<crm_id>&orgId=<crm_org_id>&recordId=<crm_id>
Of course, it will be important to populate the crm_id fields for users and contacts within your Sugar Market instance in order to utilize the iframe feature. If your CRM doesn't automatically populate these fields we recommend either GUIDs or hashes in lieu of IDs.
How to Get Help
For technical support, please file a case with the Sugar Support team.
Please include a detailed description of what you are trying to accomplish and a code snippet if possible.
Available Functionality
At current, the API supports CRUD operations for core CRM entities and a suite of core marketing automation functions.