How to Filter a List of Records

Overview

A PHP example demonstrating how to filter records using the v11 /<module>/filter REST POST endpoints.

Filtering Records

Authenticating

First, you will need to authenticate to the Sugar API. An example is shown below:

  <?php

$instance_url = "http://{site_url}/rest/v11";
$username = "admin";
$password = "password";

//Login - POST /oauth2/token
$auth_url = $instance_url . "/oauth2/token";

$oauth2_token_arguments = array(
    "grant_type" => "password",
    //client id - default is sugar. 
    //It is recommended to create your own in Admin > OAuth Keys
    "client_id" => "sugar", 
    "client_secret" => "",
    "username" => $username,
    "password" => $password,
    //platform type - default is base.
    //It is recommend to change the platform to a custom name such as "custom_api" to avoid authentication conflicts.
    "platform" => "custom_api" 
);

$auth_request = curl_init($auth_url);
curl_setopt($auth_request, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);
curl_setopt($auth_request, CURLOPT_HEADER, false);
curl_setopt($auth_request, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($auth_request, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($auth_request, CURLOPT_FOLLOWLOCATION, 0);
curl_setopt($auth_request, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json"
));

//convert arguments to json
$json_arguments = json_encode($oauth2_token_arguments);
curl_setopt($auth_request, CURLOPT_POSTFIELDS, $json_arguments);

//execute request
$oauth2_token_response = curl_exec($auth_request);

//decode oauth2 response to get token
$oauth2_token_response_obj = json_decode($oauth2_token_response);
$oauth_token = $oauth2_token_response_obj->access_token;

More information on authenticating can be found in the How to Authenticate and Log Out example and /oauth2/logout endpoint documentation.

Filtering Records

Next, we can filter the records we want to return using the /<module>/filter endpoint with a POST request.

  //Identify records to export - POST /<module>/filter

$filter_url = $instance_url . "/Accounts/filter";

$filter_arguments = array(
    "filter" => array(
        array(
            '$or' => array(
                array(
                    //name starts with 'a'
                    "name" => array(
                        '$starts'=>"A",
                    )
                ),
                array(
                    //name starts with 'b'
                    "name" => array(
                        '$starts'=>"b",
                    )
                )
            ),
        ),
    ),
    "max_num" => 2,
    "offset" => 0,
    "fields" => "id",
    "order_by" => "date_entered",
    "favorites" => false,
    "my_items" => false,
);

$filter_request = curl_init($filter_url);
curl_setopt($filter_request, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);
curl_setopt($filter_request, CURLOPT_HEADER, false);
curl_setopt($filter_request, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($filter_request, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($filter_request, CURLOPT_FOLLOWLOCATION, 0);
curl_setopt($filter_request, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "oauth-token: {$oauth_token}"
));

//convert arguments to json
$json_arguments = json_encode($filter_arguments);
curl_setopt($filter_request, CURLOPT_POSTFIELDS, $json_arguments);

//execute request
$filter_response = curl_exec($filter_request);

//decode json
$filter_response_obj = json_decode($filter_response);

More information on the filter API can be found in the /<module>/filter documentation.

Note : The /<module>/filter endpoint can be called using a GET request as well, though long URL requests can have issues so the POST request is recommended. 

Request Payload

The data sent to the server is shown below:

  {  
   "filter":[  
      {  
         "$or":[  
            {  
               "name":{  
                  "$starts":"A"
               }
            },
            {  
               "name":{  
                  "$starts":"b"
               }
            }
         ]
      }
   ],
   "max_num":2,
   "offset":0,
   "fields":"id",
   "order_by":"date_entered",
   "favorites":false,
   "my_items":false
}

Response

The data received from the server is shown below:

  {  
   "next_offset":2,
   "records":[  
      {  
         "id":"f16760a4-3a52-f77d-1522-5703ca28925f",
         "date_modified":"2016-04-05T10:23:28-04:00",
         "_acl":{  
            "fields":{  

            }
         },
         "_module":"Accounts"
      },
      {  
         "id":"ec409fbb-2b22-4f32-7fa1-5703caf78dc3",
         "date_modified":"2016-04-05T10:23:28-04:00",
         "_acl":{  
            "fields":{  

            }
         },
         "_module":"Accounts"
      }
   ]
}

Download

You can download the full API example using POST here and using GET here.