Blog Details
Blog Post Actions
Related
Recommended

SugarCRM Cookbook - The School of REST - Part 2

SugarCRM Developers
10+ minute read time

Post originally written by sugarmajed.

This is part 2 of 3 of The School of REST. In Part 1 we covered creating our Account "Burger Palace" and using the filter API to get just the records we wanted. Today we'll cover retrieving records, creating our Contact "Bob Burger", updating records, and associating records together. 

6. Retrieve a specific Account - Burger Palace 

We created "Burger Palace" with the id "demo_burger_palace". To retrieve it using the RESTful interface, we just need to do a GET to rest/v10/Accounts/demo_burger_palace

CURL GET Account.sh

curl -X GET -H OAuth-Token:e2505ba8-fc56-de05-ce9f-530d1bf56227 -H Cache-Control:no-cache -H Postman-Token:7e4c0a5d-db74-55d7-64a7-8c363686f9de http://server/pro720/rest/v10/Accounts/demo_burger_palace?fields=name,email,account_type,description


GET Account.http

GET /pro720/rest/v10/Accounts/demo_burger_palace?fields=name%2Cemail%2Caccount_type%2Cdescription HTTP/1.1
Host: server
OAuth-Token: e2505ba8-fc56-de05-ce9f-530d1bf56227
Cache-Control: no-cache
Postman-Token: 7e2f14d9-3868-3d38-c9f2-b3c36a3105b0


Response.json

{
 "id": "demo_burger_palace",
 "date_modified": "2014-02-25T14:32:25-08:00",
 "description": "My Example Account",
 "email": [
        {
 "email_address": "burgers@example.com",
 "invalid_email": false,
 "opt_out": false,
 "primary_address": false,
 "reply_to_address": false
        }
    ],
 "account_type": "Customer",
 "_acl": {
 "fields": {}
    },
 "_module": "Accounts"
}


7. Create a Contact - Bob Burger 

We have our customer account "Burger Palace", but relationships are all about the people. Let's create a Contact named "Bob Burger". Using what we learned against Accounts, we can apply it to Contacts. Let's do a POST to /rest/v10/Contacts

We'll create "Bob Burger" with the id "demo_bob_burger". Remember the we DO NOT need to pass in the id. We are only doing this for demo purposes right now. SugarCRM will automatically generate an id and return it as part of the response.

CURL POST Contacts.sh

curl -X POST -H OAuth-Token:8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4 -H Cache-Control:no-cache -H Postman-Token:0444b90d-ba1d-c395-a259-694115e5ec1e -d '{ "id":"demo_bob_burger", "first_name":"Bob", "last_name": "Burger", "description":"Bob Burger is a new contact" }' http://server/pro720/rest/v10/Contacts


POST Contacts.http

POST /pro720/rest/v10/Contacts HTTP/1.1
Host: server
OAuth-Token: 8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4
Cache-Control: no-cache
Postman-Token: 27bb113b-ef6f-86dc-601e-e2f8e2c4878c

{ "id":"demo_bob_burger", "first_name":"Bob", "last_name": "Burger", "description":"Bob Burger is a new contact" }

Response.json

{
 "id": "demo_bob_burger",
 "name": "Bob Burger",
 "date_entered": "2014-02-25T12:16:41-08:00",
 "date_modified": "2014-02-25T12:16:41-08:00",
 "modified_user_id": "1",
 "modified_by_name": "Administrator",
 "created_by": "1",
 "created_by_name": "Administrator",
 "doc_owner": "",
 "user_favorites": "",
 "description": "Bob Burger is a new contact",
 "deleted": false,
 "assigned_user_id": "",
 "assigned_user_name": "",
 "team_count": "",
 "team_name": [
        {
 "id": 1,
 "name": "Global",
 "name_2": "",
 "primary": true
        }
    ],
 "email": [],
 "email1": "",
 "email2": "",
 "invalid_email": "",
 "email_opt_out": "",
 "salutation": "",
 "first_name": "Bob",
 "last_name": "Burger",
 "full_name": "Bob Burger",
 "title": "",
 "facebook": "",
 "twitter": "",
 "googleplus": "",
 "department": "",
 "do_not_call": false,
 "phone_home": "",
 "phone_mobile": "",
 "phone_work": "",
 "phone_other": "",
 "phone_fax": "",
 "primary_address_street": "",
 "primary_address_street_2": "",
 "primary_address_street_3": "",
 "primary_address_city": "",
 "primary_address_state": "",
 "primary_address_postalcode": "",
 "primary_address_country": "",
 "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": "",
 "account_name": "",
 "account_id": "",
 "dnb_principal_id": "",
 "opportunity_role_fields": "",
 "opportunity_role_id": "",
 "opportunity_role": "",
 "reports_to_id": "",
 "report_to_name": "",
 "birthdate": "",
 "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,
 "my_favorite": false,
 "_acl": {
 "fields": {}
    },
 "following": true,
 "_module": "Contacts"
}

8. Update a Record - Bob Burger 

Great, we've created "Bob Burger" by doing a POST request. Now let's update him by doing a PUT request to /rest/v10/Contacts/demo_bob_burger

CURL PUT Contact.sh

curl -X PUT -H OAuth-Token:8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4 -H Cache-Control:no-cache -H Postman-Token:63ba84bf-612d-7210-c328-29f50f3f4b92 -d '{ "email":[{"email_address":"bob.burger@example.com"}], "description":"Bob Burger was updated" }' http://server/pro720/rest/v10/Contacts/demo_bob_burger

PUT Contact.http

PUT /pro720/rest/v10/Contacts/demo_bob_burger HTTP/1.1
Host: server
OAuth-Token: 8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4
Cache-Control: no-cache
Postman-Token: 24ae44a6-1720-b644-f236-f347226f18e4

{ "email":[{"email_address":"bob.burger@example.com"}], "description":"Bob Burger was updated" }

Response.json

{
 "id": "demo_bob_burger",
 "name": "Bob Burger",
 "date_entered": "2014-02-25T12:16:41-08:00",
 "date_modified": "2014-02-25T12:21:22-08:00",
 "modified_user_id": "1",
 "modified_by_name": "Administrator",
 "created_by": "1",
 "created_by_name": "Administrator",
 "doc_owner": "",
 "user_favorites": "",
 "description": "Bob Burger was updated",
 "deleted": false,
 "assigned_user_id": "",
 "assigned_user_name": "",
 "team_count": "",
 "team_name": [
        {
 "id": 1,
 "name": "Global",
 "name_2": "",
 "primary": true
        }
    ],
 "email": [
        {
 "email_address": "bob.burger@example.com",
 "invalid_email": false,
 "opt_out": false,
 "primary_address": false,
 "reply_to_address": false
        }
    ],
 "email1": "bob.burger@example.com",
 "email2": "",
 "invalid_email": false,
 "email_opt_out": false,
 "salutation": "",
 "first_name": "Bob",
 "last_name": "Burger",
 "full_name": "Bob Burger",
 "title": "",
 "facebook": "",
 "twitter": "",
 "googleplus": "",
 "department": "",
 "do_not_call": false,
 "phone_home": "",
 "phone_mobile": "",
 "phone_work": "",
 "phone_other": "",
 "phone_fax": "",
 "primary_address_street": "",
 "primary_address_street_2": "",
 "primary_address_street_3": "",
 "primary_address_city": "",
 "primary_address_state": "",
 "primary_address_postalcode": "",
 "primary_address_country": "",
 "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": "",
 "account_name": "",
 "account_id": "",
 "dnb_principal_id": "",
 "opportunity_role_fields": "",
 "opportunity_role_id": "",
 "opportunity_role": "",
 "reports_to_id": "",
 "report_to_name": "",
 "birthdate": "",
 "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,
 "my_favorite": false,
 "_acl": {
 "fields": {}
    },
 "following": true,
 "_module": "Contacts"
}

9. Let's associate our Contact and Account 

We have "Burger Palace" and "Bob Burger" now let's bring them together by doing a POST to /rest/v10/Accounts/demo_burger_palace/link

We'll need to pass two arguments.

  1.  a list of ids we wish to relate to "Burger Palace" which in this case is demo_bob_burger.
  2.  a link_name which is the name of the relationship we wish to use. In this case it is "contacts", but it's not always the name of the related module.

CURL Associate Account Contact.sh

curl -X POST -H OAuth-Token:8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4 -H Cache-Control:no-cache -H Postman-Token:f6e69685-303c-14b4-d1a7-c70cfa00f17f -d '{ "link_name": "contacts", "ids": ["demo_bob_burger"] }' http://server/pro720/rest/v10/Accounts/demo_burger_palace/link

POST Link.http

POST /pro720/rest/v10/Accounts/demo_burger_palace/link HTTP/1.1
Host: server
OAuth-Token: 8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4
Cache-Control: no-cache
Postman-Token: 20fc86b9-644b-f2fb-ca11-8b304587eff6

{ "link_name": "contacts", "ids": ["demo_bob_burger"] }


Response.json

{
 "related_records": [
        {
 "id": "demo_bob_burger",
 "name": "Bob Burger",
 "date_entered": "2014-02-25T12:16:41-08:00",
 "date_modified": "2014-02-25T12:21:22-08:00",
 "modified_user_id": "1",
 "modified_by_name": "Administrator",
 "created_by": "1",
 "created_by_name": "Administrator",
 "doc_owner": "",
 "user_favorites": "",
 "description": "Bob Burger was updated",
 "deleted": false,
 "assigned_user_id": "",
 "assigned_user_name": "",
 "team_count": "",
 "team_name": [
                {
 "id": 1,
 "name": "Global",
 "name_2": "",
 "primary": true
                }
            ],
 "email": [
                {
 "email_address": "bob.burger@example.com",
 "invalid_email": false,
 "opt_out": false,
 "primary_address": false,
 "reply_to_address": false
                }
            ],
 "email1": "bob.burger@example.com",
 "email2": "",
 "invalid_email": false,
 "email_opt_out": false,
 "salutation": "",
 "first_name": "Bob",
 "last_name": "Burger",
 "full_name": "Bob Burger",
 "title": "",
 "facebook": "",
 "twitter": "",
 "googleplus": "",
 "department": "",
 "do_not_call": false,
 "phone_home": "",
 "phone_mobile": "",
 "phone_work": "",
 "phone_other": "",
 "phone_fax": "",
 "primary_address_street": "",
 "primary_address_street_2": "",
 "primary_address_street_3": "",
 "primary_address_city": "",
 "primary_address_state": "",
 "primary_address_postalcode": "",
 "primary_address_country": "",
 "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": "",
 "account_name": "",
 "account_id": "",
 "dnb_principal_id": "",
 "opportunity_role_fields": "",
 "opportunity_role_id": "",
 "opportunity_role": "",
 "reports_to_id": "",
 "report_to_name": "",
 "birthdate": "",
 "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,
 "my_favorite": false,
 "_acl": {
 "fields": {}
            },
 "following": true,
 "_module": "Contacts"
        }
    ],
 "record": {
 "id": "demo_burger_palace",
 "name": "Burger Palace",
 "date_entered": "2014-02-25T10:51:51-08:00",
 "date_modified": "2014-02-25T10:51:51-08:00",
 "modified_user_id": "1",
 "modified_by_name": "Administrator",
 "created_by": "1",
 "created_by_name": "Administrator",
 "doc_owner": "",
 "user_favorites": "",
 "description": "My Example Account",
 "deleted": false,
 "assigned_user_id": "",
 "assigned_user_name": "",
 "team_count": "",
 "team_name": [
            {
 "id": 1,
 "name": "Global",
 "name_2": "",
 "primary": true
            }
        ],
 "email": [
            {
 "email_address": "burgers@example.com",
 "invalid_email": false,
 "opt_out": false,
 "primary_address": false,
 "reply_to_address": false
            }
        ],
 "email1": "burgers@example.com",
 "email2": "",
 "invalid_email": false,
 "email_opt_out": false,
 "facebook": "",
 "twitter": "",
 "googleplus": "",
 "account_type": "Customer",
 "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": "",
 "campaign_id": "",
 "campaign_name": "",
 "my_favorite": false,
 "_acl": {
 "fields": {}
        },
 "following": true,
 "_module": "Accounts"
    }
}


10. Get Contacts Associated to an Account - Burger Palace

We just related "Bob Burger" to "Burger Palace" now let's view that relationship by retrieving the contacts related to "Burger Palace". All we need to do is a GET request to /rest/v10/Accounts/demo_burger_palace/link/contacts where "contacts" is the same link_name we passed up in step 9. 

CURL Related Contacts.sh

curl -X GET -H OAuth-Token:e2505ba8-fc56-de05-ce9f-530d1bf56227 -H Cache-Control:no-cache -H Postman-Token:54bc4cd3-b893-ca1e-1ad4-2eaf40ca9f8e http://server/pro720/rest/v10/Accounts/demo_burger_palace/link/contacts?fields=name,first_name,last_name,email,description

GET  Related Contacts.http

GET /pro720/rest/v10/Accounts/demo_burger_palace/link/contacts?fields=name%2Cfirst_name%2Clast_name%2Cemail%2Cdescription HTTP/1.1
Host: server
OAuth-Token: e2505ba8-fc56-de05-ce9f-530d1bf56227
Cache-Control: no-cache
Postman-Token: 7edacde4-62c2-72ea-8c33-645df954e0cf


Response.json

{
 "next_offset": -1,
 "records": [
        {
 "id": "demo_bob_burger",
 "name": "Bob Burger",
 "date_modified": "2014-02-25T14:44:24-08:00",
 "description": "Bob Burger was updated",
 "email": [
                {
 "email_address": "bob.burger@example.com",
 "invalid_email": false,
 "opt_out": false,
 "primary_address": false,
 "reply_to_address": false
                }
            ],
 "first_name": "Bob",
 "last_name": "Burger",
 "_acl": {
 "fields": {}
            },
 "_module": "Contacts"
        }
    ]
}

Now you'll see in the response that "Bob Burger" is associated to "Burger Palace"

Continue on to Part 3  - Filtering on Relationships, Favorites, and Deleting Records