SugarMarket RESTFUL API

Number of APIs: 82

Sugar Market provides a self-served RESTFUL API. The SugarMarket API exposes the core entities of the SugarMarket 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 SugarMarket API is follows:

https://developer.salesfusion.com/api/2.0/

Authentication

The SugarMarket API utilizes two authentication methods:

HTTP Basic Authentication through TLS/SSL
Token-based Authentication

HTTP Basic Authentication

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 SugarMarket account.

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) Contact your Sugar Market consultant or CSM so they can add the 'Customer-Wide' and 'Customer-Wide - API Access' features.

2) Log into the SugarMarket application using an admin user account.

3) Navigate to Account Configuration and select Roles under the Administrator navigation tree.

4) Create a new role named API Access and check Data Access and Navigation Access.

5) Under the Navigation Access tab, select Customer-Wide and Customer-Wide - API Access and add it to the Access Provided list.

6) Click Save and Return.

7) Navigate to User administration and open the target user account for editing.

8) In the user preferences view, select the Roles tab.

9) Click Add New Role and select the previously configured API Access role from the drop-down menu.

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

Token-Based Authentication

To obtain a token, make a request against the following endpoint providing your username, domain, and password as a JSON blob:
POST https://developer.salesfusion.com/api/2.0/users/request-token/

Here’s a CURL:

curl --location --request POST 'https://developer.salesfusion.com/api/2.0/users/request-token/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "robparker@axiomfire.com",
    "password": "XXXXXXXXXXXXXXX"
}'

Response will look as follows:

200
{
   "token": "8ffa19e5b03874a543dda1f97d5acb813a236675"
}

You can then make requests to the API by providing the following HTTP Authorization header:

Token 8ffa19e5b03874a543dda1f97d5acb813a236675

Here’s a CURL:

curl --location --request GET 'https://developer.salesfusion.com/api/2.0/contacts' \
--header 'Authorization: Token 8ffa19e5b03874a543dda1f97d5acb813a236675

Tokens will expire after 8 hours. When a token is expired, a request to the API will return the following:

401
{
   "detail": "Expired token"
}

Subsequent requests to the API will return the following:

401
{
   "Msg": "[Invalid token.]"
}

At this point, a new token must be requested.

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 SugarMarket iFrame feature

The SugarMarket 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 SugarMarket instance. This value can be retrieved using the /tenant/info endpoint. The returned crmorgid 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/ endpoint

The iframe URL is constructed as follows:

https://iframe.salesfusion.com/?userId=&orgId=&recordId=

Of course, it will be important to populate the crm_id fields for users and contacts within your SugarMarket 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.

Using Qodex and Making Test Calls

1) Download and install Qodex from here: https://www.getQodex.com/downloads

2) Ensure you have completed the steps above to setup your User and API access role to authenticate to the API.

Open Qodex on your machine and get familiar with the layout. For this example we will be querying the contacts table within Sugar Market, formerly known as Salesfusion.

1) Within the Qodex app, first we will focus on the bar that says Enter Request URL. In this space we need to put the URL of the RESTFUL API endpoint we would like to call. In this example the URL is:

https://developer.salesfusion.com/api/2.0/contacts/

2) We now need to setup Authentication. Click into the Authorization menu (this menu is opened by default in most cases). In the dropdown menu that states Inherit auth from parent select the Basic Auth option. You should now see a Username and Password field on the right side of the screen.

Enter your username and password into the corresponding fields. Your API username is actually the username of the user you created plus the domain name:

USERNAME@DOMAIN.COM

NOTE: Some users may default to having an emailaddress as the username in which case you will need to use the following. It might look a little funny but should work just fine.

USERNAME@EMAILADDRESS.COM@DOMAIN.COM

3) Now that we have authentication setup we can simply make our API call. Just hit the send button! If everything has been done correctly, you should receive a JSON object of your top 100 contacts back! If anything is done incorrectly, you may receive an error. If you are unsure of what this error means please file a case with the Sugar Support team with a screenshot of the error and help will be on the way!

Using the Search feature

Searching via the Sugar Marke RESTFUL API is as simple as including a URL parameter in your API call. It does require a specific table be specified(Such as contacts) and cannot be called on the base route. The query is appended to the end of the route. You can perform searches on the all tables presented by the RESTUL API to find relevant information. It is also not limited to a singular field and will search all fields for relevant values (firstname, email, lastname, etc.)

Example below

Base Route:

https://developer.salesfusion.com/api/2.0/contacts/

Query:

?search=tj.southern

Combined:

https://developer.salesfusion.com/api/2.0/contacts/ ?search=tj.southern

Fetching Records by Date Range

For some scenarios when getting data from the Sugar Market RESTUL API you may want to query a certain entity to only fetch records that fall within a certain date range.

An example of this would be wanting to fetch all contacts that have been updated in the month of October.

To do this we can append UTM paramters to our base route like the example below:

Base Route: https://developer.salesfusion.com/api/2.0/contacts

UTM Parameters: ?datefield=updateddate&startdate=2018-20-01&enddate=2018-10-31

Combined: https://developer.salesfusion.com/api/2.0/contacts?datefield=updateddate&startdate=2018-09-01T00:01&enddate=2018-09-30T23:59

Within the appended UTM Parameters the date_field section can be any date field presented on the given route such as Created_date.

Sorting data with the RESTFUL API

Sorting data with the Sugar Market RESTFUL API is as simple as adding an additional parameter to your base route. The sorting function can be called on all tables but can ONLY be used on standard fields as custom fields are not preset in paginated views at this time.

Example:
Base URL:

https://developer.salesfusion.com/api/2.0/contacts/

Query:
?ordering=contact_id

Combined:
https://developer.salesfusion.com/api/2.0/contacts/?ordering=-contact_id

Operator = Sorts Ascending
Operator =- Sorts Descending

API Throttle Rates

The REST API throttle rates are 90 calls per minute or 2000 calls per day, whichever happens first.

Available Functionality

At current, the API supports CRUD operations for core CRM entities and a suite of core marketing automation functions.

How to Get Help

For technical support, please contact us at the following: support@sugarcrm.com

Please include a detailed description of what you are trying to accomplish and a code snippet or request and response objects if possible.