SugarCRM Cookbook – The School of REST – Part 1

sugarmajed —  February 28, 2014 — 23 Comments

Welcome to the School of REST – our first installment in the Sugar 7 Cookbook Series! We’ve always believed that DATA belongs to you and it should always be accessible to you! With Sugar 7 we’ve added a completely revamped REST API. Today we are going to cover all the basics of pushing data into and getting data out of your SugarCRM instance. For each of the API calls we’ll show how to do it in curl, a generic HTTP Request, as well as showing you the response. Also, before we get started you can always hit /rest/v10/help for detailed documentation on all the APIs.

In this Guide we will be creating an Account “Burger Palace” and relating it to a Contact “Bob Burger”. We will then show you the ins and outs of Creating and Updating Records, Filtering Lists, Creating Relationships, Filtering on Relationships, Marking Records as Favorites, and Deleting Records.

This guide is broken into 3 sections.

Part 1 – Connecting, Creating Records, and Filtering Lists

Part 2 – Retrieving, Updating, and Relating Records 

Part 3  – Filtering on Relationships, Favorites, and Deleting Records 

You may want to download PostMan for Chrome to follow along interactively from

You can download Our Cookbook1 PostMan collection from

Step 1. Connecting/Authenticating

Sugar 7 uses two-legged OAuth2 for authentication. You simply need to do a POST to /rest/v10/oauth2/token with the following params:

grant_type String Type of request. Available grant types are “password” and “refresh_token”.
client_id String The client_id of “sugar” will automatically create an OAuth Key in the system and can be used for “password” authentication. The client_id of “support_portal” will create an OAuth Key if the portal system is enabled and will allow for portal authentication. Other client_id’s can be created by the administrator in the OAuthKeys section in the Administration section and can be used in the future for additional grant types, if the client secret is filled in, it will be checked to validate use of the client id.
client_secret String The clients secret key.
username String The username of the user authenticating to the system.
password String The plaintext password the user authenticating to the system.
platform String Defaults to “base” allows you to have custom meta-data per platform

So, first we are going to login using a grant_type of “password”.

Once you get the response you’ll need to hold onto the access_token and the refresh_token. Anytime the access_token is invalidated, you’ll want to make another request to the token endpoint with a grant_type of “refresh_token”. Store just the refresh_token in long term storage – not the username and password.

For all the following requests we are going to pass in a header of OAuth-Token: {{your access token here}}

2. Create an Account – Burger Palace

Now that we have the access_token we can start having some fun! Let’s create a new customer – “Burger Palace” as an Account.

Being that everything is RESTful creating a new record is just a POST away. In this case we just do a POST to /rest/v10/Accounts.

For this example we will be posting an id as part of the record. You do not need to do this as SugarCRM will automatically generate an id for your record.

And of course you can add any additional fields that you would like to set.

3. Retrieve a list of Accounts 

Great, now that we have records in our system let’s fetch them back.  Being RESTful you just need to do a GET request to /rest/v10/Accounts. Don’t forget to pass in the OAuth-Token header.  To speed things up be specific about the fields that you want. Let’s just fetch the name, account type, and description by passing in fields=name,account_type,description. We’ll pass in max_num to specify that we only want 3 records at a time. By default if max_num isn’t set it will return 20 records. In this case the request will look like /rest/v10/Accounts?fields=name,account_type,description&max_num=3

Excellent! If we wanted to paginate we could just add the offset parameter to the request. That is the number of records you want to skip in the list before returning anything. So passing an offset of 3 would get us to the next page of records.

4. Filter a list of Accounts by Name 

Now, let’s filter our list for records that have the name “Burger Palace”. To do this we just need to do a GET request to /rest/v10/Accounts and to pass in the filter parameter. In this case the request would look like /rest/v10/Accounts?filter[0][name]=Burger Palace&fields=name,account_type,description

You’ll notice in the response that the next_offset in the response is set to -1 which means that there are no more records in the collection.

5. Filter a list of Accounts by Names starting with “B” and a specific email address

Now, let’s pass in multiple filter conditions and let’s use some of the filter operations.

Sugar 7 supports the following filter operations

$equals Performs an exact match on that field.
$not_equals Matches on non-matching values.
$starts Matches on anything that starts with the value.
$in Finds anything where field matches one of the values as specified as an array.
$not_in Finds anything where field does not match any of the values as specified as an array.
$is_null Checks if the field is null. This operation does not need a value specified.
$not_null Checks if the field is not null. This operation does not need a value specified.
$lt Matches when the field is less than the value.
$lte Matches when the field is less than or equal to the value.
$gt Matches when the field is greater than the value.
$gte Matches when the field is greater than or equal to the value.

So to filter for Account names starting with the letter “B” we’ll use the $starts operator. So instead of “filter[0][name]=Burger Palace” we can use filter[0][name][$starts]=B.

SugarCRM stores email addresses as normalized values. To search for an Account with an email address we need to search using the relationship for email addresses which is email_addresses. Specifically, we want to filter on the field email_address within that relationship. So to do an exact match on a specific email address we pass in  filter[0][email_addresses.email_address]  Our request will look like /rest/v10/Accounts?filter[0][name][$starts]=B&filter[0][email_addresses.email_address],account_type,description,email . You will notice that we also added email to the list of fields that we wish to have returned which will cause it to return a collection of all the email addresses that are associated with this record.

Continue to Part 2 – Retrieving, Updating, and Relating Records 

23 responses to SugarCRM Cookbook – The School of REST – Part 1


    This is good information on SugarCRM V7 REST.

    Concerning filters, can custom expressions be used with multiple fields? For example, say I have custom latitude and longitude fields for my Accounts module. Based on a search by radius (estimation) expression, how would I pass in an expression using these two fields? The expression would require two fields and math functions such as COS() & SQRT(). Would I need to pull all records and then do the calculation in JavaScript?


      Hi Jeff- Thank you we are looking forward to providing a lot of great content around Sugar 7. Right now you can’t pass up custom expressions, but in an upcoming blog post we’ll show how to add custom REST endpoints that may help you out. Of course with Latitude and Longitude you can always use the existing filters to create bounding boxes and then to do additional work on the JS side to do calculations on any point within that bounding box.


    Great article! I was looking for this…asking about it in other posts. Just must note that url in curl should be between quotes, brackets escaped and space replaced by %20 (otherwise, you’ll get a globbing error from curl).
    This worked for me:


    Jeff, you reminded me things that can be done using mongoDB.


    Could you please expand and explain how and why “email_addresses.email_address” works in the filter? There is no email_addresses “relationship” in the GUI or relationships table.

    Which other “relationships” work? I experimented with a few (accounts, accounts_contacts, etc) and none succeeded. Which other items are available to the filter like this? Where is this documented?


    This has been incredibly helpful, however I cannot for the life of me figure out how to use the $in and $not_in filters….

    I’ve tried filter[0][name][$in]=one,two

    It always says “$in requires an array”. I ended up using two equals filters but it would be nice to see an example using an array.

      dranneysugarcrm May 20, 2015 at 5:39 pm

      I’m not sure what the “right” way to do it is, but the way that user created custom filters handle the “is any of” condition is something along the lines of:



    Hello, I’m looking for the method ‘get_module_fields’ that it was in SugarCRM 6, and I don’t find it in SugarCRM 7 API Help.

    Basically, I’m Looking for listing fields from a Module.

    Any help? Thanks!


      You could probably find equivalent information by inspecting the metadata response if you use the Sugar 7 Metadata API (the /rest/v10/metadata endpoint). Also, the Sugar 6 web services APIs are still available in Sugar 7 too so you could still continue using the old ‘get_module_fields’ API as well.


    Could you please explain the scenario with 3 email addresses. I tried by entering in primary email, in email1 and in email2. However, the API returns –


    The order of non-primary email addresses changes and nothing appears in email2. Do I need to do something else to get emails in desired order? Thank you.


    After some serious googling and trial and error I found out how to use the OR-statement. As always it’s simple. But hey, if you’re not an expert (like me)…

    this is what I need: field=0 or field is null. It translates to:


    Hope it helps


    What is the expected way for passing in multiple parameters to $in clause ?

    While this works, filter[0][name][$in][]=one&filter[0][name][$in][]=two, I was expecting if we could pass in an array of values in one filter like below

    filter[0][name][$in][]=[one,two] (or)
    filter[0][name][$in][]={one,two} (or)


    How can I access records in a custom module? Is there any specific way to provide the custom module name? When I tried to access my custom module, it returns only null.


      Accessing data in Custom Modules should be same as accessing data in out of the box modules. The REST API does not differentiate. Are you certain you are using your correct custom module identifier? There may be a package prefix you are leaving off (for example, pkg_CustomModule would be your custom module’s ID if the package in module builder was “pkg” and the module you created was called “CustomModule”).


    Can you explain me how to filter in collection. I want to filter user’ name . I use the following GET request:

    the Reply:
    “records”: [
    “id”: “seed_chris_id”,
    “name”: “Chris Olliver”,
    “date_modified”: “2016-12-08T11:24:52-08:00”,
    “_acl”: {
    “fields”: {}
    “_module”: “Users”,
    “_link”: “users”
    “id”: “e21bd475-0090-2448-082c-523cc7dff4d2”,
    “name”: “Brandi Steel”,
    “date_modified”: “2013-09-25T19:35:16-07:00”,
    “locked_fields”: [],
    “_acl”: {
    “fields”: {}
    “_module”: “Contacts”,
    “_link”: “contacts”
    “next_offset”: {
    “contacts”: -1,
    “leads”: -1,
    “users”: -1

    I expected no record will return. it looks like the filter didn’t work


      Name fields on ‘person’ records like Contacts, Leads, and Users are tricky. They’re non-db fields that are calculated from first_name and last_name fields. Try something like filter[0][$or][0][first_name][$starts]=abc&filter[0][$or][1][last_name][$starts]=abc and you’ll see the result you’re looking for.

    Mehul Bhandari July 6, 2017 at 3:23 am

    how to use refresh_token in request ??

Trackbacks and Pingbacks:

  1. SugarCRM Cookbook – The School of REST – Part 3 « SugarCRM Developer Blog - February 28, 2014

    […] already created our Account “Burger Palace” in Part 1 and showed how to filter lists with various […]

  2. SugarCRM Cookbook – The School of REST – Part 2 « SugarCRM Developer Blog - February 28, 2014

    […] is part 2 of 3 of The School of REST. In Part 1 we covered creating our Account “Burger Palace” and using the filter API to get just […]

  3. daily 03/06/2014 | Cshonea's Blog - March 6, 2014

    […] SugarCRM Cookbook – The School of REST – Part 1 « SugarCRM Developer Blog […]

  4. SugarCRM Cookbook – So you wanna override an endpoint « SugarCRM Developer Blog - March 21, 2014

    […] need to have some basic idea of how to interact with the SugarCRM API from a client standpoint and The School of REST – Part 1 is a great place to start. After that you should probably learn how to add a new API so you could […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s