How to Manipulate Tags (CRUD)
Overview
A PHP example demonstrating how to work with tags using the v11 REST endpoints.
Authentication
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 POST endpoint documentation.
Creating Tags
Once you get oauth_token you would need to use it in the following API Calls to create tags.
//Create Tags - /Tags POST
$url = $instance_url . "/Tags";
//Set up the tag name
$record = array(
'name' => 'Tag Name',
);
$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
{"name":"Tag Name"}
Response
{
"id": "12c6ee48-1000-11e8-8838-6a0001bcacb0",
"name": "Tag Name",
"date_entered": "2018-02-12T15:21:52+01:00",
"date_modified": "2018-02-12T15:21:52+01: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,
"name_lower": "tag name",
"following": "",
"my_favorite": false,
"locked_fields": [],
"source_id": "",
"source_type": "",
"source_meta": "",
"assigned_user_id": "1",
"assigned_user_name": "Administrator",
"assigned_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"
}
},
"_acl": { "fields": {} },
"_module": "Tags"
}
Creating Records with Tags
You can also create tags when creating new records. All you need to do populate the tag field as an array when creating a record. Here is an example that demonstrates using the /<module> POST endpoint.
//Create Records with Tags - / POST
$url = $instance_url . "/Accounts";
//Set up the Record details with Tags
$record = array(
'name' => 'Test Record',
'tag' => array(
'First Tag',
'Second Tag'
)
);
$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",
"tag": [
"First Tag",
"Second Tag"
]
}
Response
The data sent to the server is shown below:
{
"id": "ea507760-0ffd-11e8-bcf5-6a0001bcacb0",
"name": "Test Record",
"date_entered": "2018-02-12T15:06:25+01:00",
"date_modified": "2018-02-12T15:06:25+01: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": [
{
"id": "ea69c120-0ffd-11e8-b5f6-6a0001bcacb0",
"name": "First Tag",
"tags__name_lower": "first tag"
},
{
"id": "eafb28e0-0ffd-11e8-8d80-6a0001bcacb0",
"name": "Second Tag",
"tags__name_lower": "second 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": [],
"email1": "",
"email2": "",
"invalid_email": "",
"email_opt_out": "",
"email_addresses_non_primary": "",
"calculated_c": "",
"_acl": { "fields": {} },
"_module": "Accounts"
}
Reading/Retrieving Tags
Next, we can retrieve the records using the /Tags/:record GET endpoint. An example for retrieving the tag records is shown below.
//Reading/Retrieving Tags - /Tags GET
$url = $instance_url . "/Tags/12c6ee48-1000-11e8-8838-6a0001bcacb0";
$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>/:record GET documentation.
Request Payload
No payload is sent for this request.
Response
{
"id": "12c6ee48-1000-11e8-8838-6a0001bcacb0",
"name": "Tag Name",
"date_entered": "2018-02-12T15:21:52+01:00",
"date_modified": "2018-02-12T15:21:52+01: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,
"name_lower": "tag name",
"following": "",
"my_favorite": false,
"locked_fields": [],
"source_id": "",
"source_type": "",
"source_meta": "",
"assigned_user_id": "1",
"assigned_user_name": "Administrator",
"assigned_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"
}
},
"_acl": { "fields": {} },
"_module": "Tags"
}
Updating Tags
You can update a tag using the /Tags/:record PUT endpoint. In this example, we are going to update the Tag record that we created in Creating Tags section and change its name to "Renamed Tag Name".
//Update Tags - /Tags PUT
$url = $instance_url . "/Tags/12c6ee48-1000-11e8-8838-6a0001bcacb0";
//Set up the new tag name
$record = array(
'name' => 'Renamed Tag Name',
);
$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
{"name": "Renamed Tag Name"}
Response
{
"id": "12c6ee48-1000-11e8-8838-6a0001bcacb0",
"name": "Renamed Tag Name",
"date_entered": "2018-02-12T15:21:52+01:00",
"date_modified": "2018-02-12T16:07:18+01: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,
"name_lower": "renamed tag name",
"following": "",
"my_favorite": false,
"locked_fields": [],
"source_id": "",
"source_type": "",
"source_meta": "",
"assigned_user_id": "1",
"assigned_user_name": "Administrator",
"assigned_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"
}
},
"_acl": { "fields": {} },
"_module": "Tags"
}
Deleting Tags
Finally, we can delete the record we created using the /Tags/:record DELETE API request.
//Delete Tags - /Tags DELETE
$url = $instance_url . "/Tags/12c6ee48-1000-11e8-8838-6a0001bcacb0";
$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
No payload is sent for this request.
Response
{"id":"12c6ee48-1000-11e8-8838-6a0001bcacb0"}