How to Manipulate Records (CRUD)
Overview
The following page will provide examples in bash script 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:
curl -X POST -H Cache-Control:no-cache -H "Content-Type: application/json" -d '{
"grant_type":"password",
"client_id":"sugar",
"client_secret":"",
"username":"admin",
"password":"password",
"platform":"custom_api"
}' https://{site_url}/rest/v11/oauth2/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'.
curl -X POST -H OAuth-Token:<access_token> -H Cache-Control:no-cache -H "Content-Type: application/json -d '{
"name":"Test Record",
"email1":"test@sugar.com"
}' http://<site_url>/rest/v11/Accounts
More information on this API endpoint can be found in the /<module> - POST documentation.
Response
The data received from the server is shown below:
{
"id":"ab2222df-73da-0e92-6887-5705428f4d68",
"name":"Test Record",
"date_entered":"2016-04-06T13:07:41-04:00",
"date_modified":"2016-04-06T13:07:41-04:00",
"modified_user_id":"1",
"modified_by_name":"Administrator",
"modified_user_link":{
"full_name":"Administrator",
"id":"1",
"_acl":{
"fields":[
],
"delete":"no",
"_hash":"8e11bf9be8f04daddee9d08d44ea891e"
}
},
"created_by":"1",
"created_by_name":"Administrator",
"created_by_link":{
"full_name":"Administrator",
"id":"1",
"_acl":{
"fields":[
],
"delete":"no",
"_hash":"8e11bf9be8f04daddee9d08d44ea891e"
}
},
"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":[
],
"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
}
],
"email":[
{
"email_address":"test@sugar.com",
"invalid_email":false,
"opt_out":false,
"primary_address":true,
"reply_to_address":false
}
],
"email1":"test@sugar.com",
"email2":"",
"invalid_email":false,
"email_opt_out":false,
"email_addresses_non_primary":"",
"_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.
curl -H OAuth-Token:<access_token> -H Cache-Control:no-cache http://<site_url>/rest/v11/Accounts/<record_id>?fields=name,email1,industry
More information on this API endpoint can be found in the /<module>/:record - GET documentation.
Response
The data received from the server is shown below:
{
"id":"ab2222df-73da-0e92-6887-5705428f4d68",
"name":"Test Record",
"date_modified":"2016-04-06T15:03:21-04:00",
"industry":"",
"email1":"test@sugar.com",
"_acl":{
"fields":{
}
},
"_module":"Accounts"
}
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".
curl -X PUT -H OAuth-Token:<access_token> -H Cache-Control:no-cache -d '{
"name":"Updated Record"
}' http://<site_url>/rest/v11/Accounts/<record_id>
More information on this API endpoint can be found in the /<module>/:record - PUT documentation.
Response
The data received from the server is shown below:
{
"id":"ab2222df-73da-0e92-6887-5705428f4d68",
"name":"Updated Test Record",
"date_entered":"2016-04-06T15:03:21-04:00",
"date_modified":"2016-04-06T15:03:22-04:00",
"modified_user_id":"1",
"modified_by_name":"Administrator",
"modified_user_link":{
"full_name":"Administrator",
"id":"1",
"_acl":{
"fields":[
],
"delete":"no",
"_hash":"8e11bf9be8f04daddee9d08d44ea891e"
}
},
"created_by":"1",
"created_by_name":"Administrator",
"created_by_link":{
"full_name":"Administrator",
"id":"1",
"_acl":{
"fields":[
],
"delete":"no",
"_hash":"8e11bf9be8f04daddee9d08d44ea891e"
}
},
"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":[
],
"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
}
],
"email":[
{
"email_address":"test@sugar.com",
"invalid_email":false,
"opt_out":false,
"primary_address":true,
"reply_to_address":false
}
],
"email1":"test@sugar.com",
"email2":"",
"invalid_email":false,
"email_opt_out":false,
"email_addresses_non_primary":"",
"_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.
curl -X DELETE -H OAuth-Token:<access_token> -H Cache-Control:no-cache http://<site_url>/rest/v11/Accounts/<record_id>
More information on this API endpoint can be found in the /<module>/:record - DELETE documentation.
Response
The data received from the server is shown below:
{
"id":"ab2222df-73da-0e92-6887-5705428f4d68"
}