Step Three: Walk Through the Sample Code

To access different types of resources in Salesforce, make a series of REST requests. Before you try these examples, make sure to complete the prerequisites and obtain an access token in Step 1 of this Quick Start.

You can copy and paste these examples to send them with cURL. But first replace MyDomainName in the base URI with your Salesforce domain. For information on the anatomy of a REST request, see REST Resources and Requests.

Get the Salesforce Version

To retrieve information about each available Salesforce version, submit a Versions request. In this case, the request doesn’t require authentication.

1curl https://MyDomainName.my.salesforce.com/services/data/

The output from this request, including the response header, specifies all valid versions. Your result can include more than one value.

1Content-Length: 88 
2Content-Type: application/json; 
3charset=UTF-8 Server:
4[
5    {
6        "label":"Spring '11",
7        "url":"/services/data/v21.0",
8        "version":"21.0"
9    }
10    ...
11]

Get a List of Resources

To retrieve a list of the resources available for Salesforce, in this example, for version 63.0, submit a Resources by Version request.

1curl https://MyDomainName.my.salesforce.com/services/data/v63.0/ -H "Authorization: Bearer access_token"

The output from this request shows that sobjects is one of the available resources in Salesforce version 63.0.

1{
2    "sobjects" : "/services/data/v63.0/sobjects",
3    "search" : "/services/data/v63.0/search",
4    "query" : "/services/data/v63.0/query",
5    "recent" : "/services/data/v63.0/recent"
6}

Get a List of Available Objects

To request a list of the available objects, submit a Describe Global request.

1curl https://MyDomainName.my.salesforce.com/services/data/v63.0/sobjects/ -H "Authorization: Bearer access_token"

The output from this request shows that the Account object is available.

1Transfer-Encoding: chunked 
2Content-Type: application/json; 
3charset=UTF-8 Server:
4{
5 "encoding" : "UTF-8",
6 "maxBatchSize" : 200,
7 "sobjects" : [ {
8    "name" : "Account",
9    "label" : "Account",
10    "custom" : false,
11    "keyPrefix" : "001",
12    "updateable" : true,
13    "searchable" : true,
14    "labelPlural" : "Accounts",
15    "layoutable" : true,
16    "activateable" : false,
17    "urls" : { "sobject" : "/services/data/v63.0/sobjects/Account",
18    "describe" : "/services/data/v63.0/sobjects/Account/describe",
19    "rowTemplate" : "/services/data/v63.0/sobjects/Account/{ID}" },
20    "createable" : true,
21    "customSetting" : false,
22    "deletable" : true,
23    "deprecatedAndHidden" : false,
24    "feedEnabled" : false,
25    "mergeable" : true,
26    "queryable" : true,
27    "replicateable" : true,
28    "retrieveable" : true,
29    "undeletable" : true,
30    "triggerable" : true },
31   },
32...

Get Basic Object Information

To retrieve basic information about the available Account object’s metadata, submit a sObject Basic Information request.

1curl https://MyDomainName.my.salesforce.com/services/data/v63.0/sobjects/Account/ -H "Authorization: Bearer access_token"

The output from this request shows basic attributes of the Account object such as its name and label, and it lists the most recently used accounts.

1{
2    "objectDescribe" : 
3    {  
4        "name" : "Account",  
5        "updateable" : true,  
6        "label" : "Account",  
7        "keyPrefix" : "001",  
8        
9        ...
10        
11        "replicateable" : true,  
12        "retrieveable" : true,  
13        "undeletable" : true,  
14        "triggerable" : true
15    },
16    "recentItems" : 
17    [ 
18        {  
19            "attributes" : 
20            {    
21                "type" : "Account",    
22                "url" : "/services/data/v63.0/sobjects/Account/001D000000INjVeIAL"  
23            },  
24            "Id" : "001D000000INjVeIAL",  
25            "Name" : "asdasdasd"
26        }, 
27
28        ...
29
30    ]
31}

Get a List of Fields

To retrieve more detailed information, submit a sObject Describe request.

1curl https://MyDomainName.my.salesforce.com/services/data/v63.0/sobjects/Account/describe/ -H "Authorization: Bearer access_token"

The output from this request shows more detailed information about the Account object, such as its field attributes and child relationships.

1{
2    "name" : "Account",
3    "fields" : 
4    [
5        {
6            "length" : 18,
7            "name" : "Id",
8            "type" : "id",
9            "defaultValue" : { "value" : null },
10            "updateable" : false,
11            "label" : "Account ID",
12            ...
13        },
14        ...
15    ],
16    "updateable" : true,
17    "label" : "Account",
18    ...
19    "urls" : 
20    {  
21        "uiEditTemplate" : "https://MyDomainName.my.salesforce.com/{ID}/e",  
22        "sobject" : "/services/data/v63.0/sobjects/Account",  
23        "uiDetailTemplate" : "https://MyDomainName.my.salesforce.com/{ID}",  
24        "describe" : "/services/data/v63.0/sobjects/Account/describe",  
25        "rowTemplate" : "/services/data/v63.0/sobjects/Account/{ID}",  
26        "uiNewRecord" : "https://MyDomainName.my.salesforce.com/001/e"
27    },
28    "childRelationships" : 
29    [ 
30        {  
31            "field" : "ParentId",  
32            "deprecatedAndHidden" : false,  
33            ...
34        }, 
35        ...
36    ],
37     
38    "createable" : true,
39    "customSetting" : false,
40    ...
41}

Execute a SOQL Query

To execute a SOQL query that retrieves a list of all the Account name values, submit a Query request.

1curl https://MyDomainName.my.salesforce.com/services/data/v63.0/query?q=SELECT+name+from+Account -H "Authorization: Bearer access_token"

The output lists the available Account names, and each name’s preceding attributes include the Account IDs.

1{
2    "done" : true,
3    "totalSize" : 14,
4    "records" :
5    [
6        {
7            "attributes" :
8            {
9                "type" : "Account",
10                "url" : "/services/data/v63.0/sobjects/Account/001D000000IRFmaIAH"
11            },
12            "Name" : "Test 1"
13        },
14        {
15            "attributes" :
16            {
17                "type" : "Account",
18                "url" : "/services/data/v63.0/sobjects/Account/001D000000IomazIAB"
19            },
20            "Name" : "Test 2"
21        },
22        ...
23    ]
24}

You can find more information about SOQL in the Salesforce SOQL and SOSL Reference Guide.

Note

Update a Field on a Record

To retrieve one of the accounts and update its billing city, submit an sObject Rows request. To update the object, create a text file called patchaccount.json containing the new billing city information.

1{
2    "BillingCity" : "Fremont"
3}

Specify this JSON file in the REST request. The cURL notation requires the —d option when specifying data. For more information, see http://curl.haxx.se/docs/manpage.html.

Also, specify the PATCH method, which is used to update a REST resource. This cURL command retrieves the specified Account object using its ID field and updates its billing city.

1curl https://MyDomainName.my.salesforce.com/services/data/v63.0/sobjects/Account/001D000000IroHJ -H "Authorization: Bearer access_token" -H "Content-Type: application/json" --data-binary @patchaccount.json -X PATCH

No response body is returned, just the headers.

1HTTP/1.1 204 No Content
2Server: 
3Content-Length: 0

To see that the billing address has changed to Fremont, refresh the page on the account.

REST API Developer Guide