Let the platform do the work
SugarClubContact+1 (877) 842-7276

How to Manipulate Records (CRUD)

Overview

A PHP example demonstrating how to use the CRUD (Create, Read, Update, Delete) endpoints in the REST v11 API.

CRUD Operations

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.

Creating a Record

Next, we need to submit the record to the Sugar instance using the /<module> endpoint. In this example we are going to create an Account record with a Name of 'Test Record' and an email of 'test@sugar.com'.

  //Create Records - POST /<module>
$url = $instance_url . "/Accounts";
//Set up the Record details
$record = array(
    'name' => 'Test Record',
    'email' => array(
        array(
            'email_address' => 'test@sugar.com',
            'primary_address' => true
        )
    ),
);

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

//convert arguments to json
$json_arguments = json_encode($record);
curl_setopt($curl_request, CURLOPT_POSTFIELDS, $json_arguments);
//execute request
$curl_response = curl_exec($curl_request);
//decode json
$createdRecord = json_decode($curl_response);

//display the created record
print_r($createdRecord);
curl_close($curl_request);

More information on this API endpoint can be found in the /<module> - POST documentation.

Request Payload

The data sent to the server is shown below:

  {
    "name": "Test Record",
    "email": [{ "email_address": "test@sugar.com", "primary_address": true }]
}

Response

The data received from the server is shown below:

  {
    "id": "ae78a068-7a0c-11e8-8b9e-6a0001bcacb0",
    "name": "Test Record",
    "date_entered": "2018-06-27T15:19:11+02:00",
    "date_modified": "2018-06-27T15:19:11+02:00",
    "modified_user_id": "1",
    "modified_by_name": "Administrator",
    "modified_user_link": {
        "full_name": "Administrator",
        "id": "1",
        "_acl": {
            "fields": {
                "pwd_last_changed": { "write": "no", "create": "no" },
                "last_login": { "write": "no", "create": "no" }
            },
            "delete": "no",
            "_hash": "08b99a97c2e8d792f7a44d8882b5af6d"
        }
    },
    "created_by": "1",
    "created_by_name": "Administrator",
    "created_by_link": {
        "full_name": "Administrator",
        "id": "1",
        "_acl": {
            "fields": {
                "pwd_last_changed": { "write": "no", "create": "no" },
                "last_login": { "write": "no", "create": "no" }
            },
            "delete": "no",
            "_hash": "08b99a97c2e8d792f7a44d8882b5af6d"
        }
    },
    "description": "",
    "deleted": false,
    "facebook": "",
    "twitter": "",
    "googleplus": "",
    "account_type": "",
    "industry": "",
    "annual_revenue": "",
    "phone_fax": "",
    "billing_address_street": "",
    "billing_address_street_2": "",
    "billing_address_street_3": "",
    "billing_address_street_4": "",
    "billing_address_city": "",
    "billing_address_state": "",
    "billing_address_postalcode": "",
    "billing_address_country": "",
    "rating": "",
    "phone_office": "",
    "phone_alternate": "",
    "website": "",
    "ownership": "",
    "employees": "",
    "ticker_symbol": "",
    "shipping_address_street": "",
    "shipping_address_street_2": "",
    "shipping_address_street_3": "",
    "shipping_address_street_4": "",
    "shipping_address_city": "",
    "shipping_address_state": "",
    "shipping_address_postalcode": "",
    "shipping_address_country": "",
    "parent_id": "",
    "sic_code": "",
    "duns_num": "",
    "parent_name": "",
    "member_of": {
        "name": "",
        "id": "",
        "_acl": { "fields": [], "_hash": "654d337e0e912edaa00dbb0fb3dc3c17" }
    },
    "campaign_id": "",
    "campaign_name": "",
    "campaign_accounts": {
        "name": "",
        "id": "",
        "_acl": { "fields": [], "_hash": "654d337e0e912edaa00dbb0fb3dc3c17" }
    },
    "following": true,
    "my_favorite": false,
    "tag": [],
    "locked_fields": [],
    "assigned_user_id": "",
    "assigned_user_name": "",
    "assigned_user_link": {
        "full_name": "",
        "id": "",
        "_acl": { "fields": [], "_hash": "654d337e0e912edaa00dbb0fb3dc3c17" }
    },
    "team_count": "",
    "team_count_link": {
        "team_count": "",
        "id": "1",
        "_acl": { "fields": [], "_hash": "654d337e0e912edaa00dbb0fb3dc3c17" }
    },
    "team_name": [
        {
            "id": "1",
            "name": "Global",
            "name_2": "",
            "primary": true,
            "selected": false
        }
    ],
    "email": [
        {
            "email_address": "test@sugar.com",
            "invalid_email": false,
            "opt_out": false,
            "email_address_id": "85125194-7a0a-11e8-9c17-6a0001bcacb0",
            "primary_address": true,
            "reply_to_address": false
        }
    ],
    "email1": "test@sugar.com",
    "email2": "",
    "invalid_email": false,
    "email_opt_out": false,
    "email_addresses_non_primary": "",
    "test_c": "",
    "dri_workflow_template_id": "",
    "dri_workflow_template_name": "",
    "dri_workflow_template_link": {
        "name": "",
        "id": "",
        "_acl": { "fields": [], "_hash": "654d337e0e912edaa00dbb0fb3dc3c17" }
    },
    "_acl": { "fields": {} },
    "_module": "Accounts"
}

Getting a Record

Next, we can get the created record from the Sugar instance using the /<module>/:record endpoint. In this example, we are going to get an Account record by it's ID, but only request the Name, Email, and Industry fields.

  $id = $createdRecord->id;

//Get Record - GET //:record
$url = $instance_url . "/Accounts/$id";

//Setup request to only return some fields on module
$data = array(
    'fields' => 'name,email1,industry'
);

//Add data to the URL
$url = $url."?".http_build_query($data);

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

//execute request
$curl_response = curl_exec($curl_request);
//decode json
$record = json_decode($curl_response);

//display the created record
print_r($record);
curl_close($curl_request);

Updating a Record

Next, we can update  the record in the Sugar instance using the /<module>/:record endpoint, and the PUT Http method. In this example, we are going to update the Account record and change it's name to "Updated Test Record".

  $id = $record->id;
//Update Record - PUT /<module>/:record
$url = $instance_url . "/Accounts/$id";
//Set up the Record details
$record->name = 'Updated Test Record';

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

//convert arguments to json
$json_arguments = json_encode($record);
curl_setopt($curl_request, CURLOPT_POSTFIELDS, $json_arguments);
//execute request
$curl_response = curl_exec($curl_request);
//decode json
$updatedRecord = json_decode($curl_response);

//display the created record
echo "Updated Record Name:".$updatedRecord->name;
curl_close($curl_request);

More information on this API endpoint can be found in the /<module>/:record - PUT documentation.

Request Payload

The URL sent to the server is shown below:

  {"name":"Updated Test Record"}

Response

The data received from the server is shown below:

  {
    "id": "ae78a068-7a0c-11e8-8b9e-6a0001bcacb0",
    "name": "Updated Test Record",
    "date_entered": "2018-06-27T15:19:11+02:00",
    "date_modified": "2018-06-27T15:23:19+02:00",
    "modified_user_id": "1",
    "modified_by_name": "Administrator",
    "modified_user_link": {
        "full_name": "Administrator",
        "id": "1",
        "_acl": {
            "fields": {
                "pwd_last_changed": { "write": "no", "create": "no" },
                "last_login": { "write": "no", "create": "no" }
            },
            "delete": "no",
            "_hash": "08b99a97c2e8d792f7a44d8882b5af6d"
        }
    },
    "created_by": "1",
    "created_by_name": "Administrator",
    "created_by_link": {
        "full_name": "Administrator",
        "id": "1",
        "_acl": {
            "fields": {
                "pwd_last_changed": { "write": "no", "create": "no" },
                "last_login": { "write": "no", "create": "no" }
            },
            "delete": "no",
            "_hash": "08b99a97c2e8d792f7a44d8882b5af6d"
        }
    },
    "description": "",
    "deleted": false,
    "facebook": "",
    "twitter": "",
    "googleplus": "",
    "account_type": "",
    "industry": "",
    "annual_revenue": "",
    "phone_fax": "",
    "billing_address_street": "",
    "billing_address_street_2": "",
    "billing_address_street_3": "",
    "billing_address_street_4": "",
    "billing_address_city": "",
    "billing_address_state": "",
    "billing_address_postalcode": "",
    "billing_address_country": "",
    "rating": "",
    "phone_office": "",
    "phone_alternate": "",
    "website": "",
    "ownership": "",
    "employees": "",
    "ticker_symbol": "",
    "shipping_address_street": "",
    "shipping_address_street_2": "",
    "shipping_address_street_3": "",
    "shipping_address_street_4": "",
    "shipping_address_city": "",
    "shipping_address_state": "",
    "shipping_address_postalcode": "",
    "shipping_address_country": "",
    "parent_id": "",
    "sic_code": "",
    "duns_num": "",
    "parent_name": "",
    "member_of": {
        "name": "",
        "id": "",
        "_acl": { "fields": [], "_hash": "654d337e0e912edaa00dbb0fb3dc3c17" }
    },
    "campaign_id": "",
    "campaign_name": "",
    "campaign_accounts": {
        "name": "",
        "id": "",
        "_acl": { "fields": [], "_hash": "654d337e0e912edaa00dbb0fb3dc3c17" }
    },
    "following": true,
    "my_favorite": false,
    "tag": [],
    "locked_fields": [],
    "assigned_user_id": "",
    "assigned_user_name": "",
    "assigned_user_link": {
        "full_name": "",
        "id": "",
        "_acl": { "fields": [], "_hash": "654d337e0e912edaa00dbb0fb3dc3c17" }
    },
    "team_count": "",
    "team_count_link": {
        "team_count": "",
        "id": "1",
        "_acl": { "fields": [], "_hash": "654d337e0e912edaa00dbb0fb3dc3c17" }
    },
    "team_name": [
        {
            "id": "1",
            "name": "Global",
            "name_2": "",
            "primary": true,
            "selected": false
        }
    ],
    "email": [
        {
            "email_address": "test@sugar.com",
            "invalid_email": false,
            "opt_out": false,
            "email_address_id": "85125194-7a0a-11e8-9c17-6a0001bcacb0",
            "primary_address": true,
            "reply_to_address": false
        }
    ],
    "email1": "test@sugar.com",
    "email2": "",
    "invalid_email": false,
    "email_opt_out": false,
    "email_addresses_non_primary": "",
    "test_c": "",
    "dri_workflow_template_id": "",
    "dri_workflow_template_name": "",
    "dri_workflow_template_link": {
        "name": "",
        "id": "",
        "_acl": { "fields": [], "_hash": "654d337e0e912edaa00dbb0fb3dc3c17" }
    },
    "_acl": { "fields": {} },
    "_module": "Accounts"
}

Deleting a Record

Next, we can delete the record from the Sugar instance using the /<module>/:record endpoint, by using the DELETE Http Method.

  $id = $updatedRecord->id;
//Delete Record - DELETE /<module>/:record
$url = $instance_url . "/Accounts/$id";

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

//execute request
$curl_response = curl_exec($curl_request);
//decode json
$deletedRecord = json_decode($curl_response);

//display the created record
echo "Deleted Record:".$deletedRecord->id;
curl_close($curl_request);

More information on this API endpoint can be found in the /<module>/:record - DELETE documentation.

Request Payload

The URL sent to the server is shown below:

  No payload is sent for this request.

Response

The data received from the server is shown below:

  {"id":"ae78a068-7a0c-11e8-8b9e-6a0001bcacb0"}

Download

You can download the full API example here.