How to Fetch Related Records
Overview
A PHP example demonstrating how to fetch related records using the v11 /<module>/:record/link/:link REST GET endpoints.
Fetching Related 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.
Fetching Related Records
Next, we can fetch the related records we want to return using the /<module>/:record/link/:link endpoint with a GET request where
| Element | Meaning |
| <module> | The parent module name |
| :record | The parent records ID |
| link | the actual word "link" |
| :link | The name of the relationship to fetch |
In this example, we will fetch the related Contacts for an Account
//Identify records to fetch - POST /<module>/:record/link/:link
$fetch_url = $instance_url . "/Accounts/d8f05e67-dee3-553d-0040-5342e88f2fd1/link/contacts";
$fetch_request = curl_init($fetch_url);
curl_setopt($fetch_request, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);
curl_setopt($fetch_request, CURLOPT_HEADER, false);
curl_setopt($fetch_request, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($fetch_request, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($fetch_request, CURLOPT_FOLLOWLOCATION, 0);
curl_setopt($fetch_request, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json",
"oauth-token: {$oauth_token}"
));
//execute request
$fetch_response = curl_exec($fetch_request);
//decode json
$fetch_response_obj = json_decode($fetch_response);
Request
http://{site_url}/rest/v11/Accounts/d8f05e67-dee3-553d-0040-5342e88f2fd1/link/contacts
Response
The data received from the server is shown below:
{
"next_offset":-1,
"records":[
{
"my_favorite":false,
"following":false,
"id":"819f4149-b007-a6da-a5fa-56fedbf2de77",
"name":"Florine Marcus",
"date_entered":"2016-04-01T15:34:00-05:00",
"date_modified":"2016-04-01T15:34:00-05: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":"support27@example.tv",
"primary_address":true,
"reply_to_address":false,
"invalid_email":false,
"opt_out":false
},
{
"email_address":"support.support.kid@example.net",
"primary_address":false,
"reply_to_address":false,
"invalid_email":false,
"opt_out":true
}
],
"email1":"support27@example.tv",
"email2":"",
"invalid_email":false,
"email_opt_out":false,
"email_addresses_non_primary":"",
"salutation":"",
"first_name":"Florine",
"last_name":"Marcus",
"full_name":"Florine Marcus",
"title":"President",
"facebook":"",
"twitter":"",
"googleplus":"",
"department":"",
"do_not_call":false,
"phone_home":"(746) 162-2314",
"phone_mobile":"(941) 088-2874",
"phone_work":"(827) 541-9614",
"phone_other":"",
"phone_fax":"",
"primary_address_street":"1715 Scott Dr",
"primary_address_street_2":"",
"primary_address_street_3":"",
"primary_address_city":"Alabama",
"primary_address_state":"NY",
"primary_address_postalcode":"70187",
"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":"Employee",
"account_name":"MTM Investment Bank F S B",
"account_id":"e8c641ca-1b8c-74c1-d08d-56fedbdd3187",
"dnb_principal_id":"",
"opportunity_role_fields":"",
"opportunity_role_id":"",
"opportunity_role":"",
"reports_to_id":"",
"report_to_name":"",
"birthdate":"",
"portal_name":"FlorineMarcus119",
"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"
},
{
"my_favorite":false,
"following":false,
"id":"527cc1a9-7984-91fe-4148-56fedbc356aa",
"name":"Shaneka Aceto",
"date_entered":"2016-04-01T15:34:00-05:00",
"date_modified":"2016-04-01T15:34:00-05: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":"support17@example.cn",
"primary_address":true,
"reply_to_address":false,
"invalid_email":false,
"opt_out":false
},
{
"email_address":"section.sugar.the@example.tv",
"primary_address":false,
"reply_to_address":false,
"invalid_email":false,
"opt_out":true
}
],
"email1":"support17@example.cn",
"email2":"",
"invalid_email":false,
"email_opt_out":false,
"email_addresses_non_primary":"",
"salutation":"",
"first_name":"Shaneka",
"last_name":"Aceto",
"full_name":"Shaneka Aceto",
"title":"IT Developer",
"facebook":"",
"twitter":"",
"googleplus":"",
"department":"",
"do_not_call":false,
"phone_home":"(502) 528-5151",
"phone_mobile":"(816) 719-3739",
"phone_work":"(994) 769-5855",
"phone_other":"",
"phone_fax":"",
"primary_address_street":"123 Anywhere Street",
"primary_address_street_2":"",
"primary_address_street_3":"",
"primary_address_city":"Denver",
"primary_address_state":"NY",
"primary_address_postalcode":"15128",
"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":"Email",
"account_name":"MTM Investment Bank F S B",
"account_id":"e8c641ca-1b8c-74c1-d08d-56fedbdd3187",
"dnb_principal_id":"",
"opportunity_role_fields":"",
"opportunity_role_id":"",
"opportunity_role":"",
"reports_to_id":"",
"report_to_name":"",
"birthdate":"",
"portal_name":"ShanekaAceto151",
"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"
},
{
"my_favorite":false,
"following":false,
"id":"42d703ed-f834-f87c-967d-56fedb044051",
"name":"Johnnie Pina",
"date_entered":"2016-04-01T15:34:00-05:00",
"date_modified":"2016-04-01T15:34:00-05: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":"sugar.support.hr@example.co.uk",
"primary_address":true,
"reply_to_address":false,
"invalid_email":false,
"opt_out":false
},
{
"email_address":"support.im@example.tw",
"primary_address":false,
"reply_to_address":false,
"invalid_email":false,
"opt_out":true
}
],
"email1":"sugar.support.hr@example.co.uk",
"email2":"",
"invalid_email":false,
"email_opt_out":false,
"email_addresses_non_primary":"",
"salutation":"",
"first_name":"Johnnie",
"last_name":"Pina",
"full_name":"Johnnie Pina",
"title":"VP Operations",
"facebook":"",
"twitter":"",
"googleplus":"",
"department":"",
"do_not_call":false,
"phone_home":"(159) 335-1423",
"phone_mobile":"(580) 140-4050",
"phone_work":"(418) 792-9611",
"phone_other":"",
"phone_fax":"",
"primary_address_street":"345 Sugar Blvd.",
"primary_address_street_2":"",
"primary_address_street_3":"",
"primary_address_city":"Denver",
"primary_address_state":"NY",
"primary_address_postalcode":"70648",
"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":"Direct Mail",
"account_name":"MTM Investment Bank F S B",
"account_id":"e8c641ca-1b8c-74c1-d08d-56fedbdd3187",
"dnb_principal_id":"",
"opportunity_role_fields":"",
"opportunity_role_id":"",
"opportunity_role":"",
"reports_to_id":"",
"report_to_name":"",
"birthdate":"",
"portal_name":"JohnniePina194",
"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"
}
]
}
Download
You can download the full API example here