How to Use the Global Search
Overview
A PHP example demonstrating how to globally search for records using the REST v11 /search GET endpoint.
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.
Searching Records
So, we will need to identify the records we want to see using the /search endpoint. In this case, we are going to search for all records that have the email address of 'jsmith@sugar.com'. In this example, there are 3 records, an Account, a Contact and a Lead.
//Set up the search parameters - GET /search
$search_url = $instance_url . "/search";
$search_arguments = array(
"q" => 'jsmith@sugar.com',
"max_num" => 3,
"offset" => 0,
"fields" => "",
"order_by" => "",
"favorites" => false,
"my_items" => false,
);
//As this request is a GET we will add the arguments to the URL
$search_url .= "?" . http_build_query($search_arguments);
$search_request = curl_init($search_url);
curl_setopt($search_request, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);
curl_setopt($search_request, CURLOPT_HEADER, false);
curl_setopt($search_request, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($search_request, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($search_request, CURLOPT_FOLLOWLOCATION, 0);
curl_setopt($search_request, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json",
"oauth-token: {$oauth_token}"
));
//execute request
$search_response = curl_exec($search_request);
//decode json
$search_response_obj = json_decode($search_response);
More information on the search API can be found in the /search documentation.
Request
http://{site_url}/rest/v11/search?q=jsmith%40sugar.com&max_num=3&offset=0&fields=&order_by=&favorites=0&my_items=0
Response
The data received from the server is shown below:
{
"next_offset":-1,
"records":[
{
"my_favorite":false,
"following":false,
"id":"f31b2f00-468c-3d35-1e88-56fedbd3921d",
"name":"Kaycee Gibney",
"date_entered":"2016-04-01T20:34:00+00:00",
"date_modified":"2016-04-06T15:16:24+00:00",
"modified_user_id":"1",
"modified_by_name":"Administrator",
"created_by":"1",
"created_by_name":"Administrator",
"doc_owner":"",
"user_favorites":"",
"description":"",
"deleted":false,
"assigned_user_id":"seed_jim_id",
"assigned_user_name":"Jim Brennan",
"team_count":"",
"team_name":[
{
"id":"East",
"name":"East",
"name_2":"",
"primary":true
}
],
"email":[
{
"email_address":"jsmith@sugar.com",
"invalid_email":false,
"opt_out":false,
"primary_address":true,
"reply_to_address":false
},
{
"email_address":"sales.kid.dev@example.info",
"invalid_email":false,
"opt_out":true,
"primary_address":false,
"reply_to_address":false
}
],
"email1":"jsmith@sugar.com",
"email2":"sales.kid.dev@example.info",
"invalid_email":false,
"email_opt_out":false,
"email_addresses_non_primary":"",
"salutation":"",
"first_name":"Kaycee",
"last_name":"Gibney",
"full_name":"Kaycee Gibney",
"title":"Mgr Operations",
"facebook":"",
"twitter":"",
"googleplus":"",
"department":"",
"do_not_call":false,
"phone_home":"(599) 165-2396",
"phone_mobile":"(215) 591-9574",
"phone_work":"(771) 945-3648",
"phone_other":"",
"phone_fax":"",
"primary_address_street":"321 University Ave.",
"primary_address_street_2":"",
"primary_address_street_3":"",
"primary_address_city":"Santa Monica",
"primary_address_state":"NY",
"primary_address_postalcode":"96154",
"primary_address_country":"USA",
"alt_address_street":"",
"alt_address_street_2":"",
"alt_address_street_3":"",
"alt_address_city":"",
"alt_address_state":"",
"alt_address_postalcode":"",
"alt_address_country":"",
"assistant":"",
"assistant_phone":"",
"picture":"",
"email_and_name1":"",
"lead_source":"Existing Customer",
"account_name":"Tracker Com LP",
"account_id":"72ad6f00-e345-1cab-b370-56fedbd23deb",
"dnb_principal_id":"",
"opportunity_role_fields":"",
"opportunity_role_id":"",
"opportunity_role":"",
"reports_to_id":"",
"report_to_name":"",
"birthdate":"",
"portal_name":"KayceeGibney33",
"portal_active":true,
"portal_password":true,
"portal_password1":null,
"portal_app":"",
"preferred_language":"en_us",
"campaign_id":"",
"campaign_name":"",
"c_accept_status_fields":"",
"m_accept_status_fields":"",
"accept_status_id":"",
"accept_status_name":"",
"accept_status_calls":"",
"accept_status_meetings":"",
"sync_contact":false,
"mkto_sync":false,
"mkto_id":null,
"mkto_lead_score":null,
"_acl":{
"fields":{
}
},
"_module":"Contacts",
"_search":{
"score":0.70710677,
"highlighted":{
"email1":{
"text":"\u003Cstrong\u003Ejsmith@sugar.com\u003C\/strong\u003E",
"module":"Contacts",
"label":"LBL_EMAIL_ADDRESS"
}
}
}
},
{
"my_favorite":false,
"following":false,
"id":"e8c641ca-1b8c-74c1-d08d-56fedbdd3187",
"name":"MTM Investment Bank F S B",
"date_entered":"2016-04-01T20:34:00+00:00",
"date_modified":"2016-04-06T15:16:52+00:00",
"modified_user_id":"1",
"modified_by_name":"Administrator",
"created_by":"1",
"created_by_name":"Administrator",
"doc_owner":"",
"user_favorites":"",
"description":"",
"deleted":false,
"assigned_user_id":"seed_will_id",
"assigned_user_name":"Will Westin",
"team_count":"",
"team_name":[
{
"id":"East",
"name":"East",
"name_2":"",
"primary":true
},
{
"id":"West",
"name":"West",
"name_2":"",
"primary":false
}
],
"email":[
{
"email_address":"jsmith@sugar.com",
"invalid_email":false,
"opt_out":false,
"primary_address":true,
"reply_to_address":false
},
{
"email_address":"the60@example.us",
"invalid_email":false,
"opt_out":false,
"primary_address":false,
"reply_to_address":false
}
],
"email1":"jsmith@sugar.com",
"email2":"the60@example.us",
"invalid_email":false,
"email_opt_out":false,
"email_addresses_non_primary":"",
"facebook":"",
"twitter":"",
"googleplus":"",
"account_type":"Customer",
"industry":"a",
"annual_revenue":"",
"phone_fax":"",
"billing_address_street":"67321 West Siam St.",
"billing_address_street_2":"",
"billing_address_street_3":"",
"billing_address_street_4":"",
"billing_address_city":"Alabama",
"billing_address_state":"NY",
"billing_address_postalcode":"52272",
"billing_address_country":"USA",
"rating":"",
"phone_office":"(012) 704-8075",
"phone_alternate":"",
"website":"www.salesqa.it",
"ownership":"",
"employees":"",
"ticker_symbol":"",
"shipping_address_street":"67321 West Siam St.",
"shipping_address_street_2":"",
"shipping_address_street_3":"",
"shipping_address_street_4":"",
"shipping_address_city":"Alabama",
"shipping_address_state":"NY",
"shipping_address_postalcode":"52272",
"shipping_address_country":"USA",
"parent_id":"",
"sic_code":"",
"duns_num":"",
"parent_name":"",
"campaign_id":"",
"campaign_name":"",
"_acl":{
"fields":{
}
},
"_module":"Accounts",
"_search":{
"score":0.70710677,
"highlighted":{
"email1":{
"text":"\u003Cstrong\u003Ejsmith@sugar.com\u003C\/strong\u003E",
"module":"Accounts",
"label":"LBL_EMAIL_ADDRESS"
}
}
}
},
{
"my_favorite":false,
"following":false,
"id":"f3951f4d-2d17-7939-c5ec-56fedbb9e92f",
"name":"Talia Knupp",
"date_entered":"2016-04-01T20:34:00+00:00",
"date_modified":"2016-04-06T15:33:24+00:00",
"modified_user_id":"1",
"modified_by_name":"Administrator",
"created_by":"1",
"created_by_name":"Administrator",
"doc_owner":"",
"user_favorites":"",
"description":"",
"deleted":false,
"assigned_user_id":"seed_will_id",
"assigned_user_name":"Will Westin",
"team_count":"",
"team_name":[
{
"id":"East",
"name":"East",
"name_2":"",
"primary":true
},
{
"id":"West",
"name":"West",
"name_2":"",
"primary":false
}
],
"email":[
{
"email_address":"jsmith@sugar.com",
"invalid_email":false,
"opt_out":false,
"primary_address":true,
"reply_to_address":false
},
{
"email_address":"cjsmith@sugar.com",
"invalid_email":false,
"opt_out":false,
"primary_address":false,
"reply_to_address":false
}
],
"email1":"jsmith@sugar.com",
"email2":"cjsmith@sugar.com",
"invalid_email":false,
"email_opt_out":false,
"email_addresses_non_primary":"",
"salutation":"",
"first_name":"Talia",
"last_name":"Knupp",
"full_name":"Talia Knupp",
"title":"Senior Product Manager",
"facebook":"",
"twitter":"",
"googleplus":"",
"department":"",
"do_not_call":false,
"phone_home":"(963) 741-3689",
"phone_mobile":"(600) 831-9872",
"phone_work":"(680) 991-2837",
"phone_other":"",
"phone_fax":"",
"primary_address_street":"111 Silicon Valley Road",
"primary_address_street_2":"",
"primary_address_street_3":"",
"primary_address_city":"Sunnyvale",
"primary_address_state":"NY",
"primary_address_postalcode":"99452",
"primary_address_country":"USA",
"alt_address_street":"",
"alt_address_street_2":"",
"alt_address_street_3":"",
"alt_address_city":"",
"alt_address_state":"",
"alt_address_postalcode":"",
"alt_address_country":"",
"assistant":"",
"assistant_phone":"",
"picture":"",
"converted":false,
"refered_by":"",
"lead_source":"Word of mouth",
"lead_source_description":"",
"status":"In Process",
"status_description":"",
"reports_to_id":"",
"report_to_name":"",
"dnb_principal_id":"",
"account_name":"First National S\/B",
"account_description":"",
"contact_id":"",
"contact_name":"",
"account_id":"",
"opportunity_id":"",
"opportunity_name":"",
"opportunity_amount":"",
"campaign_id":"",
"campaign_name":"",
"c_accept_status_fields":"",
"m_accept_status_fields":"",
"accept_status_id":"",
"accept_status_name":"",
"accept_status_calls":"",
"accept_status_meetings":"",
"webtolead_email1":[
{
"email_address":"jsmith@sugar.com",
"invalid_email":false,
"opt_out":false,
"primary_address":true,
"reply_to_address":false
},
{
"email_address":"cjsmith@sugar.com",
"invalid_email":false,
"opt_out":false,
"primary_address":false,
"reply_to_address":false
}
],
"webtolead_email2":[
{
"email_address":"jsmith@sugar.com",
"invalid_email":false,
"opt_out":false,
"primary_address":true,
"reply_to_address":false
},
{
"email_address":"cjsmith@sugar.com",
"invalid_email":false,
"opt_out":false,
"primary_address":false,
"reply_to_address":false
}
],
"webtolead_email_opt_out":"",
"webtolead_invalid_email":"",
"birthdate":"",
"portal_name":"",
"portal_app":"",
"website":"",
"preferred_language":"",
"mkto_sync":false,
"mkto_id":null,
"mkto_lead_score":null,
"fruits_c":"Apples",
"_acl":{
"fields":{
}
},
"_module":"Leads",
"_search":{
"score":0.70710677,
"highlighted":{
"email1":{
"text":"\u003Cstrong\u003Ejsmith@sugar.com\u003C\/strong\u003E",
"module":"Leads",
"label":"LBL_EMAIL_ADDRESS"
}
}
}
}
]
}
There are 3 records shown above, the _module field tells you if the record is from Accounts, Contacts or Leads. The _search field is an array that tells you where in the record it found the search string. It gives you back a highlighted string that you can use for display.
Downloads
You can download the full API example here