0% found this document useful (0 votes)

324 views

Api Rest

SFDC Rest API

Uploaded by

ankitearly

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

324 views

Api Rest

SFDC Rest API

Uploaded by

ankitearly

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 220

Force.

com REST API Developer

Guide
Version 38.0, Winter 17

@salesforcedocs
Last updated: December 12, 2016

as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.

CONTENTS
Chapter 1: Introducing Force.com REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Force.com REST Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Using Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Using Conditional Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Using cURL in the REST Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Understanding Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Defining Connected Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Understanding OAuth Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Understanding the Web Server OAuth Authentication Flow . . . . . . . . . . . . . . . . . . . . . . 6
Understanding the User-Agent OAuth Authentication Flow . . . . . . . . . . . . . . . . . . . . . . 12
Understanding the Username-Password OAuth Authentication Flow . . . . . . . . . . . . . . . 15
Understanding the OAuth Refresh Token Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Finding Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Use CORS to Access Supported Salesforce APIs, Apex REST, and Lightning Out . . . . . . . . . . . . 20

Chapter 2: Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step One: Obtain a Salesforce Developer Edition Organization
Step Two: Set Up Authorization . . . . . . . . . . . . . . . . . . . . . .
Step Three: Send HTTP Requests with cURL . . . . . . . . . . . . . .
Step Four: Walk Through the Sample Code . . . . . . . . . . . . . .
Using Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.

22
22
22
25
26
32

Chapter 3: Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Getting Information About My Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
List Available REST API Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
List Organization Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
List Available REST Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Get a List of Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Get a List of Objects If Metadata Has Changed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Working with Object Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Retrieve Metadata for an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Get Field and Other Metadata for an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Get Object Metadata Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Working with Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Create a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Update a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Delete a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Get Field Values from a Standard Object Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Contents

Get Field Values from an External Object Record by Using the Salesforce ID . . . . . . . . . . 46
Get Field Values from an External Object Record by Using the External ID Standard
Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Retrieve a Record Using an External ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Insert or Update (Upsert) a Record Using an External ID . . . . . . . . . . . . . . . . . . . . . . . 47
Traverse Relationships with Friendly URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Get Attachment Content from a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Insert or Update Blob Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Get a List of Deleted Records Within a Given Timeframe . . . . . . . . . . . . . . . . . . . . . . . 60
Get a List of Updated Records Within a Given Timeframe . . . . . . . . . . . . . . . . . . . . . . . 61
Working with Searches and Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Execute a SOQL Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Execute a SOQL Query that Includes Deleted Items . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Get Feedback on Query Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Search for a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Get the Default Search Scope and Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Get Search Result Layouts for Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
View Relevant Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Working with Recently Viewed Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
View Recently Viewed Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Mark Records as Recently Viewed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Managing User Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Manage User Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Working with Approval Processes and Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Get a List of All Approval Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Submit a Record for Approval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Approve a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Reject a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Bulk Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Get a List of Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Get a Particular Process Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Trigger Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Using Event Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Describe Event monitoring Using REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Query Event Monitoring Data with REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Get Event Monitoring Content from a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Download Large Event Log Files Using cURL with REST . . . . . . . . . . . . . . . . . . . . . . . . . 87
Using Composite Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Update a Record and Get Its Field Values in a Single Request . . . . . . . . . . . . . . . . . . . 88
Create Nested Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Create Multiple Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Chapter 4: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Contents

Resources by Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Describe Global . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
SObject Basic Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
SObject Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
SObject Get Deleted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
SObject Get Updated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
SObject Named Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
SObject Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
SObject Rows by External ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
SObject Blob Retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
SObject ApprovalLayouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
SObject CompactLayouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Describe Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
SObject PlatformAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
SObject Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
SObject Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
SObject Suggested Articles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
SObject User Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
AppMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Compact Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
FlexiPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Standard Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Custom Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
List View Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
List View Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
List Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Support Knowledge with REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Data Category Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Data Category Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Articles List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Articles Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Parameterized Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Process Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
QueryAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Recent List Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Recently Viewed Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Relevant Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Retrieve Knowledge Language Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Contents

Search Scope and Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Search Result Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Search Suggested Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Search Suggested Article Title Matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Search Suggested Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Composite Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
SObject Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Assignment Rule Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Call Options Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Limit Info Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Package Version Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Query Options Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Status Codes and Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

CHAPTER 1
In this chapter ...

Force.com REST
Resources

Using Compression

Using Conditional
Requests

Using cURL in the

REST Examples

Understanding
Authentication

Use CORS to Access

Supported Salesforce
APIs, Apex REST, and
Lightning Out

Introducing Force.com REST API

REST API provides a powerful, convenient, and simple Web services API for interacting with Force.com.
Its advantages include ease of integration and development, and its an excellent choice of technology
for use with mobile applications and Web 2.0 projects. However, if you have many records to process,
consider using Bulk API, which is based on REST principles and optimized for large sets of data.
REST API uses the same underlying data model and standard objects as those in SOAP API. See the SOAP
API Developer's Guide for details. REST API also follows the same limits as SOAP API. See the Limits section
in the SOAP API Developer's Guide.
To use the API requires basic familiarity with software development, web services, and the Salesforce
user interface.
Use this introduction to understand:
The key characteristics and architecture of REST API. This will help you understand how your
applications can best use the Force.com REST resources.
How to set up your development environment so you can begin working with REST API immediately.
How to use REST API by following a quick start that leads you step by step through a typical use case.

Introducing Force.com REST API

Force.com REST Resources

A REST resource is an abstraction of a piece of information or an action, such as a single data record, a collection of records, or a query.
Each resource in REST API is identified by a named Uniform Resource Identifier (URI) and is accessed using standard HTTP methods
(HEAD, GET, POST, PATCH, DELETE). REST API is based on the usage of resources, their URIs, and the links between them.
You use a resource to interact with your Salesforce org. For example, you can:
Retrieve summary information about the API versions available to you.
Obtain detailed information about a Salesforce object, such as Account, User, or a custom object.
Perform a query or search.
Update or delete records.
Suppose you want to retrieve information about the Salesforce version. Submit a request for the Versions resource.
curl https://yourInstance.salesforce.com/services/data/

The output from this request is as follows.

[
{
"version":"20.0",
"url":"/services/data/v20.0",
"label":"Winter '11"
}
...
]

Note: Salesforce runs on multiple server instances. The examples in this guide use yourInstance in place of a specific
instance. Replace that text with the instance for your org.
Important characteristics of the Force.com REST API resources and architecture:
Stateless
Each request from client to server must contain all the information necessary to understand the request, and not use any stored
context on the server. However, the representations of the resources are interconnected using URLs, which allow the client to progress
between states.
Caching behavior
Responses are labeled as cacheable or non-cacheable.
Uniform interface
All resources are accessed with a generic interface over HTTP.
Named resources
All resources are named using a base URI that follows your Force.com URI.
Layered components
The Force.com REST API architecture allows for the existence of such intermediaries as proxy servers and gateways to exist between
the client and the resources.
Authentication
The Force.com REST API supports OAuth 2.0 (an open protocol to allow secure API authorization). See Understanding Authentication
for more details.

Introducing Force.com REST API

Using Compression

Support for JSON and XML

JSON is the default. You can use the HTTP ACCEPT header to select either JSON or XML, or append .json or .xml to the URI
(for example, /Account/001D000000INjVe.json).
The JavaScript Object Notation (JSON) format is supported with UTF-8. Date-time information is in ISO8601 format.
XML serialization is similar to SOAP API. XML requests are supported in UTF-8 and UTF-16, and XML responses are provided in UTF-8.
Friendly URLs
Why make two API calls when you can make just one? A friendly URL provides an intuitive way to construct REST API requests and
minimizes the number of round-trips between your app and Salesforce org. Friendly URLs are available in API version 36.0 and later.
Accessing a contacts parent account without a friendly URL involves requesting the contact record using the SObject Rows resource.
Then you examine the account relationship field to obtain the account ID and request the account record with another call to SObject
Rows. Using a friendly URL, you can access the account in a single call directly from the contacts path:
/services/data/v36.0/sobjects/contact/id/account.
This functionality is exposed via the SObject Relationships on page 116 resource. For more examples of using friendly URLs to access
relationship fields, see Traverse Relationships with Friendly URLs on page 51.

Using Compression
The REST API allows the use of compression on the request and the response, using the standards defined by the HTTP 1.1 specification.
Compression is automatically supported by some clients, and can be manually added to others. Visit Salesforce Developers for more
information on particular clients.
Tip: For better performance, we suggest that clients accept and support compression as defined by the HTTP 1.1 specification.
To use compression, include the HTTP header Accept-Encoding: gzip or Accept-Encoding: deflate in a request.
The REST API compresses the response if the client properly specifies this header. The response includes the header
Content-Encoding: gzip or Accept-Encoding: deflate. You can also compress any request by including a
Content-Encoding: gzip or Content-Encoding: deflate header.

Response Compression
The REST API can optionally compress responses. Responses are compressed only if the client sends an Accept-Encoding header.
The REST API is not required to compress the response even if you have specified Accept-Encoding, but it normally does. If the
REST API compresses the response, it also specifies a Content-Encoding header.

Request Compression
Clients can also compress requests. The REST API decompresses any requests before processing. The client must send a
Content-Encoding HTTP header in the request with the name of the appropriate compression algorithm. For more information,
see:
Content-Encoding at: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11
Accept-Encoding at: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
Content Codings at: www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.5

Introducing Force.com REST API

Using Conditional Requests

To support response caching, REST API allows conditional request headers that follow the standards defined by the HTTP 1.1 specification.
For strong validation, include either the If-Match or If-None-Match header in a request, and reference the entity tags (ETag)
of the records you want to match against. For weak validation, include either the If-Modified-Since or
If-Unmodified-Since header in a request along with the date and time you want to check against. The REST API conditional
headers follow the HTTP 1.1 specification with the following exceptions.
When you include an invalid header value for If-Match, If-None-Match, or If-Unmodified-Since on a PATCH,
POST, or DELETE request, a 400 Bad Request status code is returned.
The If-Range header isnt supported.
ETag

HTTP 1.1 specification: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19

The ETag header is a response header thats returned when you access the SObject Rows resource. Its a hash of the content thats
used by the If-Match and If-None-Match request headers in subsequent requests to determine if the content has changed.
Supported resources: SObject Rows (account records only)
Example: ETag: "U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"
If-Match

HTTP 1.1 specification: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.24

The If-Match header is a request header for SObject Rows that includes a list of ETags. If the ETag of the record youre requesting
matches an ETag specified in the header, the request is processed. Otherwise, a 412 Precondition Failed status code is
returned, and the request isnt processed.
Supported resources: SObject Rows (account records only)
Example: If-Match: "Jbjuzw7dbhaEG3fd90kJbx6A0ow=-gzip",
"U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"
If-None-Match

HTTP 1.1 specification: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26

The If-None-Match header is a request header for SObject Rows thats the inverse of If-Match. If the ETag of the record
youre requesting matches an ETag specified in the header, the request isnt processed. A 304 Not Modified status code is
returned for GET or HEAD requests, and a 412 Precondition Failed status code is returned for PATCH requests.
Supported resources: SObject Rows (account records only)
Example: If-None-Match: "Jbjuzw7dbhaEG3fd90kJbx6A0ow=-gzip",
"U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"
If-Modified-Since

HTTP 1.1 specification: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25

The If-Modified-Since header is a time-based request header. The request is processed only if the data has changed since
the date and time specified in the header. Otherwise, a 304 Not Modified status code is returned, and the request isnt
processed.
Supported resources: SObject Rows, SObject Describe, Describe Global, and Invocable Actions
Example: If-Modified-Since: Tue, 10 Aug 2015 00:00:00 GMT
If-Unmodified-Since
HTTP 1.1 specification: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.28

Introducing Force.com REST API

Using cURL in the REST Examples

The If-Unmodified-Since header is a request header thats the inverse of If-Modified-Since. If you make a request
and include the If-Unmodified-Since header, the request is processed only if the data hasnt changed since the specified
date. Otherwise, a 412 Precondition Failed status code is returned, and the request isnt processed.
Supported resources: SObject Rows, SObject Describe, Describe Global, and Invocable Actions
Example: If-Unmodified-Since: Tue, 10 Aug 2015 00:00:00 GMT

Using cURL in the REST Examples

The examples in this guide use the cURL tool to send HTTP requests to access, create, and manipulate REST resources on the Force.com
platform. cURL is pre-installed on many Linux and Mac systems. Windows users can download a version at curl.haxx.se/. When
using HTTPS on Windows, ensure that your system meets the cURL requirements for SSL.
Note: cURL is an open source tool and is not supported by Salesforce.
Escaping the Session ID or Using Single Quotes on Mac and Linux Systems
When running the cURL examples for the REST resources, you may get an error on Mac and Linux systems due to the presence of
the exclamation mark special character in the session ID argument. To avoid getting this error, do one of the following:
Escape the exclamation mark (!) special character in the session ID by inserting a backslash before it (\!) when the session ID is
enclosed within double quotes. For example, the session ID string in this cURL command has the exclamation mark (!) escaped:
curl https://instance_name.salesforce.com/services/data/v38.0/
-H "Authorization: Bearer
00D50000000IehZ\!AQcAQH0dMHZfz972Szmpkb58urFRkgeBGsxL_QJWwYMfAbUeeG7c1E6
LYUfiDUkWe6H34r1AAwOR8B8fLEz6n04NPGRrq0FM"

Enclose the session ID within single quotes. For example:

curl https://instance_name.salesforce.com/services/data/v38.0/
-H 'Authorization: Bearer sessionID'

Understanding Authentication
Salesforce uses the OAuth protocol to allow users of applications to securely access data without having to reveal username and password
credentials.
Before making REST API calls, you must authenticate the application user using OAuth 2.0. To do so, youll need to:
Set up your application as a connected app in the Salesforce organization.
Determine the correct Salesforce OAuth endpoint for your connected app to use.
Authenticate the connected app user via one of several different OAuth 2.0 authentication flows. An OAuth authentication flow
defines a series of steps used to coordinate the authentication process between your application and Salesforce. Supported OAuth
flows include:
Web server flow, where the server can securely protect the consumer secret.
User-agent flow, used by applications that cannot securely store the consumer secret.
Username-password flow, where the application has direct access to user credentials.
After successfully authenticating the connected app user with Salesforce, youll receive an access token which can be used to make
authenticated REST API calls.

Introducing Force.com REST API

Defining Connected Apps

To authenticate using OAuth, you must create a connected app that defines your applications OAuth settings for the Salesforce
organization.
When you develop an external application that needs to authenticate with Salesforce, you need to define it as a new connected app
within the Salesforce organization that informs Salesforce of this new authentication entry point.
Use the following steps to create a new connected app.
1. From Setup, enter Apps in the Quick Find box, then select Apps and click New to start defining a connected app.
2. Enter the name of your application.
3. Enter the contact email information, as well as any other information appropriate for your application.
4. Select Enable OAuth Settings.
5. Enter a Callback URL. Depending on which OAuth flow you use, this is typically the URL that a users browser is redirected to
after successful authentication. As this URL is used for some OAuth flows to pass an access token, the URL must use secure HTTP
(HTTPS) or a custom URI scheme.
6. Add all supported OAuth scopes to Selected OAuth Scopes. These scopes refer to permissions given by the user running the
connected app.
7. Enter a URL for Info URL. This is where the user can go for more information about your application.
8. Click Save. The Consumer Key is created and displayed, and the Consumer Secret is created (click the link to reveal it).
Once you define a connected app, you use the consumer key and consumer secret to authenticate your application. See Creating a
Connected App in the Salesforce online help for specific steps to create a connected app for the type of authentication you need.

Understanding OAuth Endpoints

OAuth endpoints are the URLs you use to make OAuth authentication requests to Salesforce.
You need to use the correct Salesforce OAuth endpoint when issuing authentication requests in your application. The primary OAuth
endpoints are:
For authorization: https://login.salesforce.com/services/oauth2/authorize
For token requests: https://login.salesforce.com/services/oauth2/token
For revoking OAuth tokens: https://login.salesforce.com/services/oauth2/revoke
All endpoints require secure HTTP (HTTPS). Each OAuth flow defines which endpoints you need to use and what request data you need
to provide.
If youre verifying authentication on a sandbox organization, use test.salesforce.com instead of login.salesforce.com in all the OAuth
endpoints listed above.

Understanding the Web Server OAuth Authentication Flow

The web server authentication flow is used by applications that are hosted on a secure server. A critical aspect of the web server flow is
that the server must be able to protect the consumer secret. You can also use code challenge and verifier values in the flow to prevent
authorization code interception.
In this flow, the client application requests the authorization server to redirect the user to another web server or resource that authorizes
the user and sends the application an authorization code. The application uses the authorization code to request an access token. The
following shows the steps for this flow.

Introducing Force.com REST API

Understanding the Web Server OAuth Authentication Flow

1. The application redirects the user to the appropriate Salesforce authorization endpoint, such as
https://login.salesforce.com/services/oauth2/authorize. The following parameters are required:
Parameter

Description

response_type

Must be code for this authentication flow.

client_id

The Consumer Key from the connected app definition.

redirect_uri

The Callback URL from the connected app definition.

The following parameters are optional:

Parameter

Description

code_challenge

Specifies the SHA256 hash value of the code_verifier

value in the token request to help prevent authorization code
interception attacks. The hash value must be base64url encoded
as defined here:
https://tools.ietf.org/html/rfc4648#section-5.

Introducing Force.com REST API

Understanding the Web Server OAuth Authentication Flow

Parameter

Description
If the code_challenge value is provided in the
authorization request and a code_verifier value is
provided in the token request, Salesforce compares the
code_challenge to the code_verifier. If the
code_challenge is invalid or doesnt match, the login
fails with the invalid_request error code.
If the code_challenge value is provided in the
authorization request, but a code_verifier value is
not provided in the token request, the login fails with the
invalid_grant error code.
Note: The value should be base64url-encoded only once.
Changes the login pages display type. Valid values are:

display

pageFull-page authorization screen. This is the default

value if none is specified.
popupCompact dialog optimized for modern Web
browser popup windows.
touchMobile-optimized dialog designed for modern
smartphones such as Android and iPhone.
mobileMobile optimized dialog designed for
smartphones such as BlackBerry OS 5 that dont support
touch screens.
Determines whether the user should be prompted for login and
approval. Values are either true or false. Default is false.

immediate

If set to true, and if the user is currently logged in and has

previously approved the application, the approval step is
skipped.
If set to true and the user is not logged in or has not
previously approved the application, the session is
immediately terminated with the
immediate_unsuccessful error code.
login_hint

Provides a valid username value to pre-populate the login page

with the username. For
example:[email protected]. If a
user already has an active session in the browser, then the
login_hint parameter does nothing; the active user session
continues.

nonce

Specifies a value to be returned in the response; this is useful for

detecting "replay" attacks. Optional with the openid scope for
getting a user ID token.

Introducing Force.com REST API

Understanding the Web Server OAuth Authentication Flow

Parameter

Description

prompt

Specifies how the authorization server prompts the user for

reauthentication and reapproval. This parameter is optional. The
only values Salesforce supports are:
loginThe authorization server must prompt the user for
reauthentication, forcing the user to log in again.
consentThe authorization server must prompt the user
for reapproval before returning information to the client.
It is valid to pass both values, separated by a space, to require
the user to both log in and reauthorize. For example:
?prompt=login%20consent

scope

Specifies what data your application can access. See Scope

Parameter Values in the online help for more information.

state

Specifies any additional URL-encoded state data to be returned

in the callback URL after approval.

An example authorization URL might look something like the following:

https://login.salesforce.com/services/oauth2/authorize?response_type=code
&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3X
HrXDiCQjK1mdgAvhCscA9GE&redirect_uri=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fwww.mysite.com%2F
code_callback.jsp&state=mystate

2. The user logs into Salesforce with their credentials. The user is interacting with the authorization endpoint directly, so the application
never sees the users credentials. After successfully logging in, the user is asked to authorize the application. Note that if the user has
already authorized the application, this step is skipped.
3. After Salesforce confirms that the client application is authorized, the end-users Web browser is redirected to the callback URL
specified by the redirect_uri parameter. Salesforce appends authorization information to the redirect URL with the following
values:
Parameters

Description

code

Authorization code the consumer must use to obtain the access

and refresh tokens.

state

The state value that was passed in as part of the initial request,
if applicable.

An example callback URL with authorization information might look something like:
https://www.mysite.com/authcode_callback?code=aWekysIEeqM9PiT
hEfm0Cnr6MoLIfwWyRJcqOqHdF8f9INokharAS09ia7UNP6RiVScerfhc4w%3D%3D

Introducing Force.com REST API

Understanding the Web Server OAuth Authentication Flow

4. The application extracts the authorization code and passes it in a request to Salesforce for an access token. This request is a POST
request sent to the appropriate Salesforce token request endpoint, such as
https://login.salesforce.com/services/oauth2/token. The following parameters are required:
Parameter

Description

grant_type

Value must be authorization_code for this flow.

client_id

The Consumer Key from the connected app definition.

client_secret

The Consumer Secret from the connected app definition.

redirect_uri

The Callback URL from the connected app definition.

code

Authorization code the consumer must use to obtain the access

and refresh tokens.

The following parameters are optional:

Parameter

Description

client_assertion

Instead of passing in client_secret you can choose to

provide a client_assertion and
client_assertion_type. If a client_secret
parameter is not provided, Salesforce checks for the
client_assertion and client_assertion_type
automatically. The value of client_assertion must be a
typical JWT bearer token, signed with the private key associated
with the OAuth consumers uploaded certificate. Only the RS256
algorithm is currently supported. For more information on using
client_assertion, see the OpenID Connect specifications
for the private_key_jwt client authentication method.

client_assertion_type

Provide this value when using the client_assertion

parameter. The value of client_assertion_type must be
urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

Specifies 128 bytes of random data with high enough entropy

to make it difficult to guess the value to help prevent
authorization code interception attacks. The value also must be
base64url encoded as defined here:
https://tools.ietf.org/html/rfc4648#section-5.

code_verifier

If the code_verifier value is provided in the token

request and a code_challenge value is in the
authorization request, Salesforce compares the
code_verifier to the code_challenge. If the
code_verifier is invalid or doesnt match, the login
fails with the invalid_grant error code.
If the code_verifier value is provided in the token
request, but a code_challenge value was not provided

Introducing Force.com REST API

Understanding the Web Server OAuth Authentication Flow

Parameter

Description
in the authorization request, the login fails with the
invalid_grant error code.
Note: The value should be base64url-encoded only once.
Expected return format. The default is json. Values are:

format

urlencoded
json
xml
The return format can also be specified in the header of the
request using one of the following:
Accept:
application/x-www-form-urlencoded

Accept: application/json
Accept: application/xml

An example access token POST request might look something like:

POST /services/oauth2/token HTTP/1.1
Host: login.salesforce.com
grant_type=authorization_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZ
VEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&client_id=3MVG9lKcPoNI
NVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCs
cA9GE&client_secret=1955279925675241571&
redirect_uri=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fwww.mysite.com%2Fcode_callback.jsp

5. If this request is successful, the server returns a response body that contains the following:
Parameters

Description

access_token

Access token that acts as a session ID that the application uses

for making requests. This token should be protected as though
it were user credentials.

refresh_token

Token that can be used in the future to obtain new access tokens.
Warning: This value is a secret. You should treat it like
the user's password and use appropriate measures to
protect it.

instance_url

Identifies the Salesforce instance to which API calls should be

sent.

Identity URL that can be used to both identify the user as well
as query for more information about the user. Can be used in an
HTTP request to get more information about the end user.

Introducing Force.com REST API

Understanding the User-Agent OAuth Authentication Flow

Parameters

Description

issued_at

When the signature was created, represented as the number of

seconds since the Unix epoch (00:00:00 UTC on 1 January 1970).

signature

Base64-encoded HMAC-SHA256 signature signed with the

consumer's private key containing the concatenated ID and
issued_at value. The signature can be used to verify
that the identity URL wasnt modified because it was sent by the
server.

An example JSON response body might look something like:

{"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448101416",
"refresh_token":"5Aep8614iLM.Dq661ePDmPEgaAW9Oh_L3JKkDpB4xReb54_
pZebnUG0h6Sb4KUVDpNtWEofWM39yg==",
"instance_url":"https://yourInstance.salesforce.com/",
"signature":"CMJ4l+CCaPQiKjoOEwEig9H4wqhpuLSk4J2urAe+fVg=",
"access_token":"00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0R
NBaT1cyWk7TrqoDjoNIWQ2ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4"}

6. The application uses the provided access token and refresh token to access protected user data.

Understanding the User-Agent OAuth Authentication Flow

The user-agent authentication flow is used by client applications (consumers) residing in the users device. This could be implemented
in a browser using a scripting language such as JavaScript, or from a mobile device or a desktop application. These consumers cannot
keep the client secret confidential.
In this flow, the client application requests the authorization server to redirect the user to another Web server or resource which is capable
of extracting the access token and passing it back to the application. The following shows the steps for this flow.

Introducing Force.com REST API

Understanding the User-Agent OAuth Authentication Flow

Description

response_type

Must be token for this authentication flow

client_id

The Consumer Key from the connected app definition.

redirect_uri

The Callback URL from the connected app definition.

The following parameters are optional:

Parameter

Description

display

Changes the login pages display type. Valid values are:

pageFull-page authorization screen. This is the default
value if none is specified.
popupCompact dialog optimized for modern Web
browser popup windows.
touchMobile-optimized dialog designed for modern
smartphones such as Android and iPhone.

Introducing Force.com REST API

Understanding the User-Agent OAuth Authentication Flow

Parameter

Description
mobileMobile optimized dialog designed for
smartphones such as BlackBerry OS 5 that dont support
touch screens.

scope

Specifies what data your application can access. See Scope

Parameter Values in the online help for more information.

state

Specifies any additional URL-encoded state data to be returned

in the callback URL after approval.

An example authorization URL might look something like the following:

https://login.salesforce.com/services/oauth2/authorize?response_type=token&
client_id=3MVG9lKcPoNINVBIPJjdw1J9LLJbP_pqwoJYyuisjQhr_LLurNDv7AgQvDTZwCoZuD
ZrXcPCmBv4o.8ds.5iE&redirect_uri=https%3A%2F%2Ffanyv88.com%3A443%2Fhttps%2Fwww.mysite.com%2Fuser_callback.jsp&
state=mystate

2. The user logs into Salesforce with their credentials. The user interacts with the authorization endpoint directly, so the application
never sees the users credentials.
3. Once authorization is granted, the authorization endpoint redirects the user to the redirect URL. This URL is defined in the remote
access application created for the application. Salesforce appends access token information to the redirect URL with the following
values:
Parameters

Description

access_token

Access token that acts as a session ID that the application uses

for making requests. This token should be protected as though
it were user credentials.

expires_in

Amount of time the access token is valid, in seconds.

refresh_token

Token that can be used in the future to obtain new access tokens.
Warning: This value is a secret. You should treat it like
the user's password and use appropriate measures to
protect it.
The refresh token is only returned if the redirect URI is
https://login.salesforce.com/services/oauth2/success

or used with a custom protocol that is not HTTPS.

state

The state value that was passed in as part of the initial request,
if applicable.

instance_url

Identifies the Salesforce instance to which API calls should be

sent.

Identity URL that can be used to both identify the user as well
as query for more information about the user. Can be used in an
HTTP request to get more information about the end user.

Introducing Force.com REST API

Understanding the Username-Password OAuth

Authentication Flow

Parameters

Description

issued_at

When the signature was created, represented as the number of

seconds since the Unix epoch (00:00:00 UTC on 1 January 1970).

signature

Base64-encoded HMAC-SHA256 signature signed with the

consumer's private key containing the concatenated ID and
issued_at value. The signature can be used to verify
that the identity URL wasnt modified because it was sent by the
server.

An example callback URL with access information appended after the hash sign (#) might look something like:
https://www.mysite.com/user_callback.jsp#access_token=00Dx0000000BV7z%21AR8
AQBM8J_xr9kLqmZIRyQxZgLcM4HVi41aGtW0qW3JCzf5xdTGGGSoVim8FfJkZEqxbjaFbberKGk
8v8AnYrvChG4qJbQo8&refresh_token=5Aep8614iLM.Dq661ePDmPEgaAW9Oh_L3JKkDpB4xR
eb54_pZfVti1dPEk8aimw4Hr9ne7VXXVSIQ%3D%3D&expires_in=7200&state=mystate

4. The application uses the provided access token and refresh token to access protected user data.
Keep the following considerations in mind when using the user-agent OAuth flow:
Because the access token is encoded into the redirection URI, it might be exposed to the end-user and other applications residing
on the computer or device. If youre authenticating using JavaScript, call window.location.replace(); to remove the
callback from the browsers history.

Understanding the Username-Password OAuth Authentication Flow

The username-password authentication flow can be used to authenticate when the consumer already has the users credentials.
In this flow, the users credentials are used by the application to request an access token as shown in the following steps.
Warning: This OAuth authentication flow involves passing the users credentials back and forth. Use this authentication flow
only when necessary. No refresh token will be issued.

Introducing Force.com REST API

Understanding the Username-Password OAuth

Authentication Flow

1. The application uses the users username and password to request an access token. This is done via an out-of-band POST request
to the appropriate Salesforce token request endpoint, such as
https://login.salesforce.com/services/oauth2/token. These request fields are required:
Parameter

Description

grant_type

Must be password for this authentication flow.

client_id

The Consumer Key from the connected app definition.

client_secret

The Consumer Secret from the connected app definition.

username

End-users username.

password

End-users password.
Note: You must append the users security token to their
password A security token is an automatically-generated
key from Salesforce. For example, if a user's password is
mypassword, and their security token is XXXXXXXXXX,
then the value provided for this parmeter must be
mypasswordXXXXXXXXXX. For more information on
security tokens see Reset Your Security Token in the
online help.

Introducing Force.com REST API

Understanding the OAuth Refresh Token Process

An example request body might look something like the following:

grant_type=password&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82Hn
FVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&client_secret=
1955279925675241571&username=testuser%40salesforce.com&password=mypassword123456

2. Salesforce verifies the user credentials, and if successful, sends a response to the application with the access token. This response
contains the following values:
Parameters

Description

access_token

Access token that acts as a session ID that the application uses

for making requests. This token should be protected as though
it were user credentials.

instance_url

Identifies the Salesforce instance to which API calls should be

sent.

Identity URL that can be used to both identify the user as well
as query for more information about the user. Can be used in an
HTTP request to get more information about the end user.

issued_at

When the signature was created, represented as the number of

seconds since the Unix epoch (00:00:00 UTC on 1 January 1970).

signature

Base64-encoded HMAC-SHA256 signature signed with the

consumer's private key containing the concatenated ID and
issued_at value. The signature can be used to verify
that the identity URL wasnt modified because it was sent by the
server.

An example response body might look something like:

{"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448832702","instance_url":"https://yourInstance.salesforce.com/",
"signature":"0CmxinZir53Yex7nE0TD+zMpvIWYGb/bdJh6XfOH6EQ=","access_token":
"00Dx0000000BV7z!AR8AQAxo9UfVkh8AlV0Gomt9Czx9LjHnSSpwBMmbRcgKFmxOtvxjTrKW1
9ye6PE3Ds1eQz3z8jr3W7_VbWmEu4Q8TVGSTHxs"}

3. The application uses the provided access token to access protected user data.
Keep the following considerations in mind when using the username-password OAuth flow:
Since the user is never redirected to login at Salesforce in this flow, the user cant directly authorize the application, so no refresh
tokens can be used. If your application requires refresh tokens, you should consider using the Web server or user-agent OAuth flow.

Understanding the OAuth Refresh Token Process

The Web server OAuth authentication flow and user-agent flow both provide a refresh token that can be used to obtain a new access
token.
Access tokens have a limited lifetime specified by the session timeout in Salesforce. If an application uses an expired access token, a
Session expired or invalid error is returned. If the application is using the Web server or user-agent OAuth authentication flows, a refresh
token may be provided during authorization that can be used to get a new access token.

Introducing Force.com REST API

Understanding the OAuth Refresh Token Process

The client application obtains a new access token by sending a POST request to the token request endpoint with the following request
parameters:
Parameters

Description

grant_type

Value must be refresh_token.

refresh_token

The refresh token the client application already received.

client_id

The Consumer Key from the connected app definition.

client_secret

The Consumer Secret from the connected app definition.

This parameter is optional.

format

Expected return format. The default is json. Values are:

urlencoded
json
xml
The return format can also be specified in the header of the request
using one of the following:
Accept:
application/x-www-form-urlencoded

Accept: application/json
Accept: application/xml
This parameter is optional.

An example refresh token POST request might look something like:

POST /services/oauth2/token HTTP/1.1
Host: https://login.salesforce.com/
grant_type=refresh_token&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0
QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&client_secret=1955279925675241571
&refresh_token=your token here

Once Salesforce verifies the refresh token request, it sends a response to the application with the following response body parameters:
Parameters

Description

access_token

Access token that acts as a session ID that the application uses for
making requests. This token should be protected as though it were
user credentials.

instance_url

Identifies the Salesforce instance to which API calls should be sent.

Identity URL that can be used to both identify the user as well as
query for more information about the user. Can be used in an HTTP
request to get more information about the end user.

issued_at

When the signature was created, represented as the number of

seconds since the Unix epoch (00:00:00 UTC on 1 January 1970).

Introducing Force.com REST API

Finding Additional Resources

Parameters

Description

signature

Base64-encoded HMAC-SHA256 signature signed with the

consumer's private key containing the concatenated ID and
issued_at value. The signature can be used to verify that
the identity URL wasnt modified because it was sent by the server.

An example JSON response body might look something like:

{ "id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448384422","instance_url":"https://yourInstance.salesforce.com/",
"signature":"SSSbLO/gBhmmyNUvN18ODBDFYHzakxOMgqYtu+hDPsc=",
"access_token":"00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0RNBaT1cyWk7T
rqoDjoNIWQ2ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4"}

Keep in mind the following considerations when using the refresh token OAuth process:
The session timeout for an access token can be configured in Salesforce from Setup by entering Session Settings in the
Quick Find box, then selecting Session Settings.
If the application uses the username-password OAuth authentication flow, no refresh token is issued, as the user cannot authorize
the application in this flow. If the access token expires, the application using username-password OAuth flow must re-authenticate
the user.

Finding Additional Resources

The following resources provide additional information about using OAuth with Salesforce:
Authenticating Apps with OAuth
Digging Deeper into OAuth on Force.com
Using OAuth to Authorize External Applications
The following resources are examples of third party client libraries that implement OAuth that you might find useful:
For Ruby on Rails: OmniAuth
For Java: Apache Amber
Additional OAuth client libraries: OAuth.net

Introducing Force.com REST API

Use CORS to Access Supported Salesforce APIs, Apex REST,

and Lightning Out

Use CORS to Access Supported Salesforce APIs, Apex REST, and

Lightning Out
Chatter REST API, REST API, Lightning Out, Bulk API, and Apex REST support CORS (cross-origin
resource sharing). To access these APIs from JavaScript in a web browser, add the origin serving
the script to the CORS whitelist.
CORS is a W3C recommendation that enables web browsers to request resources from origins other
than their own (cross-origin request). For example, using CORS, a JavaScript script at
https://www.example.com could request a resource from
https://www.salesforce.com.
If a browser that supports CORS makes a request to an origin in the Salesforce CORS whitelist,
Salesforce returns the origin in the Access-Control-Allow-Origin HTTP header, along
with any additional CORS HTTP headers. If the origin is not included in the whitelist, Salesforce
returns HTTP status code 403.
1. From Setup, enter CORS in the Quick Find box, then select CORS.
2. Select New.

EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in: Developer,
Enterprise, Performance,
and Unlimited

USER PERMISSIONS
To create, read, update, and
delete:
Modify All Data

3. Enter an origin URL pattern.

The origin URL pattern must include the HTTPS protocol (unless youre using your localhost)
and a domain name and can include a port. The wildcard character (*) is supported and must be in front of a second-level domain
name. For example, https://*.example.com adds all subdomains of example.com to the whitelist.
The origin URL pattern can be an IP address. However, an IP address and a domain that resolve to the same address are not the same
origin, and you must add them to the CORS whitelist as separate entries.
Important: You must still pass an OAuth token with requests that require it.

CHAPTER 2 Quick Start

In this chapter ...

Prerequisites

Step One: Obtain a

Salesforce Developer
Edition Organization

Step Two: Set Up

Authorization

Step Three: Send

HTTP Requests with
cURL

Step Four: Walk

Through the Sample
Code

Using Workbench

Create a sample REST application in your development environment to see the power and flexibility of
the REST API.

Quick Start

Prerequisites

Prerequisites
Completing the prerequisites makes it easier to build and use the quick-start sample.
If youre unfamiliar with cURL and JavaScript Object Notation (JSON), you can also use Workbench to obtain data.
Install your development platform according to its product documentation.
Become familiar with cURL, the tool used to execute REST requests in this quick start. If you use another tool, you should be familiar
enough with it to translate the example code.
Become familiar with JSON which is used in this quick start, or be able to translate samples from JSON to the standard you use.
Enable an SSL endpoint in your application server.
Become familiar with OAuth 2.0, which requires some setup. We provide the steps, but it will help if you are familiar with the basic
concepts and workflow.
Read through all the steps before beginning this quick start. You may also wish to review the rest of this document to familiarize
yourself with terms and concepts.

Step One: Obtain a Salesforce Developer Edition Organization

This completes the authentication.

4. Once authenticated, every request must pass in the access_token value in the header. It cannot be passed as a request
parameter.
HttpClient httpclient = new HttpClient();
GetMethod gm = new GetMethod(serviceUrl);
//set the token in the header
gm.setRequestHeader("Authorization", "Bearer "+accessToken);
//set the SOQL as a query param
NameValuePair[] params = new NameValuePair[1];
/**
* other option instead of query string, pass just the fields you want back:
* https://instance_name.salesforce.com/services/data/v20.0/sobjects/Account/
*
001D000000INjVe?fields=AccountNumber,BillingPostalCode
*/
params[0] = new NameValuePair("q","SELECT name, title FROM Contact LIMIT 100");
gm.setQueryString(params);
httpclient.executeMethod(gm);
String responseBody = gm.getResponseBodyAsString();
//exception handling removed for brevity
JSONObject json = new JSONObject(responseBody);
JSONArray results = json.getJSONArray("records");
for(int i = 0; i < results.length(); i++)
response.getWriter().write(results.getJSONObject(i).getString("Name")+
"+results.getJSONObject(i).getString("Title")+"\n");

The syntax to provide the access token in your REST requests:

Authorization: Bearer access_token

For example:
curl https://instance_name.salesforce.com/services/data/v20.0/ -H 'Authorization: Bearer
access_token'

Session ID Authorization
You can use a session ID instead of an OAuth 2.0 access token if you arent handling someone elses password:

Step Four: Walk Through the Sample Code

3. Use one of the resources to get a list of the available objects.

4. Select one of the objects and get a description of its metadata.
5. Get a list of fields on that same object.
6. Execute a SOQL query to retrieve values from all name fields on Account records.
7. Update the Billing City for one of the Account objects.

Get the Salesforce Version

Begin by retrieving information about each available Salesforce version. To do this, submit a request for the Versions resource. In this
case the request does not require authentication:
curl https://yourInstance.salesforce.com/services/data/

The output from this request, including the response header:

Content-Length: 88
Content-Type: application/json;
charset=UTF-8 Server:
[
{
"version":"20.0",
"url":"/services/data/v20.0",
"label":"Winter '11"
}
...
]

The output specifies the resources available for all valid versions (your result may include more than one value). Next, use one of these
versions to discover the resources it contains.

Get a List of Resources

The next step is to retrieve a list of the resources available for Salesforce, in this example for version 20.0. To do this, submit a request for
the Resources by Version:
curl https://yourInstance.salesforce.com/services/data/v20.0/ -H "Authorization: Bearer
access_token" -H "X-PrettyPrint:1"

The output from this request is as follows:

{
"sobjects" : "/services/data/v20.0/sobjects",
"search" : "/services/data/v20.0/search",
"query" : "/services/data/v20.0/query",
"recent" : "/services/data/v20.0/recent"
}

From this output you can see that sobjects is one of the available resources in Salesforce version 20.0. You will be able to use this
resource in the next request to retrieve the available objects.

Quick Start

Step Four: Walk Through the Sample Code

Get a List of Available Objects

Now that you have the list of available resources, you can request a list of the available objects. To do this, submit a request for the
Describe Global:
curl https://yourInstance.salesforce.com/services/data/v20.0/sobjects/ -H "Authorization:
Bearer access_token" -H "X-PrettyPrint:1"

The output from this request is as follows:

Transfer-Encoding: chunked
Content-Type: application/json;
charset=UTF-8 Server:
{
"encoding" : "UTF-8",
"maxBatchSize" : 200,
"sobjects" : [ {
"name" : "Account",
"label" : "Account",
"custom" : false,
"keyPrefix" : "001",
"updateable" : true,
"searchable" : true,
"labelPlural" : "Accounts",
"layoutable" : true,
"activateable" : false,
"urls" : { "sobject" : "/services/data/v20.0/sobjects/Account",
"describe" : "/services/data/v20.0/sobjects/Account/describe",
"rowTemplate" : "/services/data/v20.0/sobjects/Account/{ID}" },
"createable" : true,
"customSetting" : false,
"deletable" : true,
"deprecatedAndHidden" : false,
"feedEnabled" : false,
"mergeable" : true,
"queryable" : true,
"replicateable" : true,
"retrieveable" : true,
"undeletable" : true,
"triggerable" : true },
},
...

From this output you can see that the Account object is available. You will be able to get more information about the Account object
in the next steps.

Get Basic Object Information

Now that you have identified the Account object as an available resource, you can retrieve some basic information about its metadata.
To do this, submit a request for the SObject Basic Information:
curl https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Account/ -H
"Authorization: Bearer access_token" -H "X-PrettyPrint:1"

Quick Start

Step Four: Walk Through the Sample Code

The output from this request is as follows:

{
"objectDescribe" :
{
"name" : "Account",
"updateable" : true,
"label" : "Account",
"keyPrefix" : "001",
...
"replicateable" : true,
"retrieveable" : true,
"undeletable" : true,
"triggerable" : true
},
"recentItems" :
[
{
"attributes" :
{
"type" : "Account",
"url" : "/services/data/v20.0/sobjects/Account/001D000000INjVeIAL"
},
"Id" : "001D000000INjVeIAL",
"Name" : "asdasdasd"
},
...
]
}

From this output you can see some basic attributes of the Account object, such as its name and label, as well as a list of the most recently
used Accounts. Since you may need more information about its fields, such as length and default values, in the next step you will retrieve
more detailed information about the Account object.

Get a List of Fields

Now that you have some basic information about the Account object's metadata, you may be interested in retrieving more detailed
information. To do this, submit a request for the SObject Describe:
curl https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Account/describe/
-H "Authorization: Bearer access_token" -H "X-PrettyPrint:1"

The output from this request is as follows:

{
"name" : "Account",
"fields" :
[
{
"length" : 18,
"name" : "Id",

Quick Start

Step Four: Walk Through the Sample Code

"type" : "id",
"defaultValue" : { "value" : null },
"updateable" : false,
"label" : "Account ID",
...
},
...
],
"updateable" : true,
"label" : "Account",
...
"urls" :
{
"uiEditTemplate" : "https://yourInstance.salesforce.com/{ID}/e",
"sobject" : "/services/data/v20.0/sobjects/Account",
"uiDetailTemplate" : "https://yourInstance.salesforce.com/{ID}",
"describe" : "/services/data/v20.0/sobjects/Account/describe",
"rowTemplate" : "/services/data/v20.0/sobjects/Account/{ID}",
"uiNewRecord" : "https://yourInstance.salesforce.com/001/e"
},
"childRelationships" :
[
{
"field" : "ParentId",
"deprecatedAndHidden" : false,
...
},
...
],
"createable" : true,
"customSetting" : false,
...
}

From this output you can see much more detailed information about the Account object, such as its field attributes and child relationships.
Now you have enough information to construct useful queries and updates for the Account objects in your organization, which you will
do in the next steps.

Execute a SOQL Query

Now that you know the field names on the Account object, you can execute a SOQL query, for example, to retrieve a list of all the Account
name values. To do this, submit a Query request:
curl
https://yourInstance.salesforce.com/services/data/v20.0/query?q=SELECT+name+from+Account
-H "Authorization: Bearer access_token" -H "X-PrettyPrint:1"

The output from this request is as follows:

{
"done" : true,
"totalSize" : 14,
"records" :

Quick Start

Step Four: Walk Through the Sample Code

[
{
"attributes" :
{
"type" : "Account",
"url" : "/services/data/v20.0/sobjects/Account/001D000000IRFmaIAH"
},
"Name" : "Test 1"
},
{
"attributes" :
{
"type" : "Account",
"url" : "/services/data/v20.0/sobjects/Account/001D000000IomazIAB"
},
"Name" : "Test 2"
},
...
]
}

From this output you have a listing of the available Account names, and each name's preceding attributes include the Account IDs. In
the next step you will use this information to update one of the accounts.
Note: You can find more information about SOQL in the Salesforce SOQL and SOSL Reference Guide.

Update a Field on a Record

Now that you have the Account names and IDs, you can retrieve one of the accounts and update its Billing City. To do this, you will need
to submit an SObject Rows request. To update the object, supply the new information about the Billing City. Create a text file called
patchaccount.json containing the following information:
{
"BillingCity" : "Fremont"
}

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 for updating a REST resource. The following cURL command retrieves the specified
Account object using its ID field, and updates its Billing City.
curl
https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Account/001D000000IroHJ
-H "Authorization: Bearer access_token" -H "X-PrettyPrint:1" -H "Content-Type:
application/json" --data-binary @patchaccount.json -X PATCH

No response body is returned, just the headers:

HTTP/1.1 204 No Content
Server:
Content-Length: 0

Refresh the page on the account and you will see that the Billing Address has changed to Fremont.

Quick Start

Using Workbench

Other Resources
Search for Ruby on developer.salesforce.com
Force.com Cookbook recipe for getting started in Ruby
Force.com REST API Board

Using Workbench
Use the Workbench tool to obtain data about your organization.
If you dont want to use CURL, you can use the Workbench REST explorer to obtain response data.
1. Log in to your organization.
2. Open a new browser tab and navigate to https://developer.salesforce.com/page/Workbench.
3. Log in to Workbench and allow access to your organization. Workbench is a public site and wont retain your data.
4. Click Utilities > REST Explorer.
5. Ensure that Get is selected. The Execute text box is prepopulated with a portion of a resource path. Add the remaining information
for your resource. For example, if your cURL syntax is
https://yourInstance.salesforce.com/services/data/v32.0/sobjects/EventLogFile/describe
-H "Authorization: Bearer token"

type
/services/data/v32.0/sobjects/EventLogFile/describe.

6. Click Execute.
7. Click Expand All or Show Raw Response to view your data.
Tip: If you receive a Service not found message, verify your resource path.

CHAPTER 3 Examples
In this chapter ...

Getting Information
About My
Organization

Working with Object

Metadata

Working with
Records

Working with
Searches and
Queries

Working with
Recently Viewed
Information

Managing User
Passwords

Working with
Approval Processes
and Process Rules

Using Event
Monitoring

Using Composite
Resources

This section provides examples of using REST API resources to do a variety of different tasks, including
working with objects, organization information, and queries.
For complete reference information on REST API resources, see Reference on page 93.

Examples

Getting Information About My Organization

The examples in this section use REST API resources to retrieve organization-level information, such as a list of all objects available in
your organization.
IN THIS SECTION:
List Available REST API Versions
Use the Versions resource to list summary information about each REST API version currently available, including the version, label,
and a link to each version's root. You do not need authentication to retrieve the list of versions.
List Organization Limits
Use the Limits resource to list limits information for your organization.
List Available REST Resources
Use the Resources by Version resource to list the resources available for the specified API version. This provides the name and URI
of each additional resource.
Get a List of Objects
Use the Describe Global resource to list the objects available in your org and available to the logged-in user. This resource also returns
the org encoding, as well as maximum batch size permitted in queries.
Get a List of Objects If Metadata Has Changed
Use the Describe Global resource and the If-Modified-Since HTTP header to determine if an objects metadata has changed.

List Available REST API Versions

Use the Versions resource to list summary information about each REST API version currently available, including the version, label, and
a link to each version's root. You do not need authentication to retrieve the list of versions.
Example usage
curl https://yourInstance.salesforce.com/services/data/

Example request body

none required
Example JSON response body
[
{
"version" : "20.0",
"label" : "Winter '11",
"url" : "/services/data/v20.0"
},
{
"version" : "21.0",
"label" : "Spring '11",
"url" : "/services/data/v21.0"
},
...
{
"version" : "26.0",
"label" : "Winter '13",

Examples

List Organization Limits

"url" : "/services/data/v26.0"
}
]

Example XML response body

<?xml version="1.0" encoding="UTF-8"?>
<Versions>
<Version>
<label>Winter '11</label>
<url>/services/data/v20.0</url>
<version>20.0</version>
</Version>
<Version>
<label>Spring '11</label>
<url>/services/data/v21.0</url>
<version>21.0</version>
</Version>
...
<Version>
<label>Winter '13</label>
<url>/services/data/v26.0</url>
<version>26.0</version>
</Version>
</Versions>

List Organization Limits

Use the Limits resource to list limits information for your organization.
Max is the limit total for the organization.
Remaining is the total number of calls or events left for the organization.
Example usage
curl https://instance.salesforce.com/services/data/v37.0/limits/ -H "Authorization:
Bearer token "X-PrettyPrint:1"

Example request body

none required
Example response body
{
"ConcurrentAsyncGetReportInstances" : {
"Max" : 200,
"Remaining" : 200
},
"ConcurrentSyncReportRuns" : {
"Max" : 20,
"Remaining" : 20
},
"DailyApiRequests" : {
"Max" : 15000,
"Remaining" : 14998

Examples

List Organization Limits

},
"DailyAsyncApexExecutions" : {
"Max" : 250000,
"Remaining" : 250000
},
"DailyBulkApiRequests" : {
"Max" : 5000,
"Remaining" : 5000
},
"DailyDurableGenericStreamingApiEvents" : {
"Max" : 10000,
"Remaining" : 10000
},
"DailyDurableStreamingApiEvents" : {
"Max" : 10000,
"Remaining" : 10000
},
"DailyGenericStreamingApiEvents" : {
"Max" : 10000,
"Remaining" : 10000
},
"DailyStreamingApiEvents" : {
"Max" : 10000,
"Remaining" : 10000
},
"DailyWorkflowEmails" : {
"Max" : 390,
"Remaining" : 390
},
"DataStorageMB" : {
"Max" : 5,
"Remaining" : 5
},
"DurableStreamingApiConcurrentClients" : {
"Max" : 20,
"Remaining" : 20
},
"FileStorageMB" : {
"Max" : 20,
"Remaining" : 20
},
"HourlyAsyncReportRuns" : {
"Max" : 1200,
"Remaining" : 1200
},
"HourlyDashboardRefreshes" : {
"Max" : 200,
"Remaining" : 200
},
"HourlyDashboardResults" : {
"Max" : 5000,
"Remaining" : 5000
},
"HourlyDashboardStatuses" : {

Examples

List Available REST Resources

"Max" : 999999999,
"Remaining" : 999999999
},
"HourlyODataCallout" : {
"Remaining" : 9999,
"Max" : 10000
},
"HourlySyncReportRuns" : {
"Max" : 500,
"Remaining" : 500
},
"HourlyTimeBasedWorkflow" : {
"Max" : 50,
"Remaining" : 50
},
"MassEmail" : {
"Max" : 10,
"Remaining" : 10
},
"SingleEmail" : {
"Max" : 15,
"Remaining" : 15
},
"StreamingApiConcurrentClients" : {
"Max" : 20,
"Remaining" : 20
}
}

List Available REST Resources

Use the Resources by Version resource to list the resources available for the specified API version. This provides the name and URI of
each additional resource.
Example
curl https://yourInstance.salesforce.com/services/data/v26.0/ -H "Authorization: Bearer
token"

Example request body

none required
Example JSON response body
{
"sobjects" : "/services/data/v26.0/sobjects",
"licensing" : "/services/data/v26.0/licensing",
"connect" : "/services/data/v26.0/connect",
"search" : "/services/data/v26.0/search",
"query" : "/services/data/v26.0/query",
"tooling" : "/services/data/v26.0/tooling",
"chatter" : "/services/data/v26.0/chatter",
"recent" : "/services/data/v26.0/recent"
}

Examples

Get a List of Objects

Example XML response body

<?xml version="1.0" encoding="UTF-8"?>
<urls>
<sobjects>/services/data/v26.0/sobjects</sobjects>
<licensing>/services/data/v26.0/licensing</licensing>
<connect>/services/data/v26.0/connect</connect>
<search>/services/data/v26.0/search</search>
<query>/services/data/v26.0/query</query>
<tooling>/services/data/v26.0/tooling</tooling>
<chatter>/services/data/v26.0/chatter</chatter>
<recent>/services/data/v26.0/recent</recent>
</urls>

Get a List of Objects

Use the Describe Global resource to list the objects available in your org and available to the logged-in user. This resource also returns
the org encoding, as well as maximum batch size permitted in queries.
Example usage
curl https://yourInstance.salesforce.com/services/data/v37.0/sobjects/ -H "Authorization:
Bearer token"

Example request body

none required
Example response body
{
"encoding" : "UTF-8",
"maxBatchSize" : 200,
"sobjects" : [ {
"activateable" : false,
"custom" : false,
"customSetting" : false,
"createable" : true,
"deletable" : true,
"deprecatedAndHidden" : false,
"feedEnabled" : true,
"keyPrefix" : "001",
"label" : "Account",
"labelPlural" : "Accounts",
"layoutable" : true,
"mergeable" : true,
"mruEnabled" : true,
"name" : "Account",
"queryable" : true,
"replicateable" : true,
"retrieveable" : true,
"searchable" : true,
"triggerable" : true
"undeletable" : true,
"updateable" : true,
"urls" : {

Examples

Get a List of Objects If Metadata Has Changed

"sobject" : "/services/data/v37.0/sobjects/Account",
"describe" : "/services/data/v37.0/sobjects/Account/describe",
"rowTemplate" : "/services/data/v37.0/sobjects/Account/{ID}"
},
},
...
]
}

Get a List of Objects If Metadata Has Changed

Get Object Metadata Changes

"createable" : true,
"customSetting" : false,
...
}

Get Object Metadata Changes

Use the SObject Describe resource and the If-Modified-Since HTTP header to determine if object metadata has changed.
You can include the If-Modified-Since header with a date in EEE, dd MMM yyyy HH:mm:ss z format when you use
the SObject Describe resource. If you do, response metadata will only be returned if the object metadata has changed since the provided
date. If the metadata has not been modified since the provided date, a 304 Not Modified status code is returned, with no response
body.
The following example assumes that no changes, such as new custom fields, have been made to the Merchandise__c object after July
3rd, 2013.
Example SObject Describe request
/services/data/v29.0/sobjects/Merchandise__c/describe

Example If-Modified-Since header used with request

If-Modified-Since: Wed, 3 Jul 2013 19:43:31 GMT

Example response body

No response body returned
Example response status code
HTTP/1.1 304 Not Modified
Date: Fri, 12 Jul 2013 05:03:24 GMT

If there were changes to Merchandise__c made after July 3rd, 2013, the response body would contain the metadata for Merchandise__c.
See Get Field and Other Metadata for an Object for an example.

Working with Records

The examples in this section use REST API resources to create, retrieve, update, and delete records, along with other record-related
operations.
IN THIS SECTION:
Create a Record
Use the SObject Basic Information resource to create new records. You supply the required field values in the request data, and then
use the POST method of the resource. The response body will contain the ID of the created record if the call is successful.
Update a Record
You use the SObject Rows resource to update records. Provide the updated record information in your request data and use the
PATCH method of the resource with a specific record ID to update that record. Records in a single file must be of the same object
type.
Delete a Record
Use the SObject Rows resource to delete records. Specify the record ID and use the DELETE method of the resource to delete a record.

Examples

Create a Record

Get Field Values from a Standard Object Record

You use the SObject Rows resource to retrieve field values from a record. Specify the fields you want to retrieve in the fields
parameter and use the GET method of the resource.
Get Field Values from an External Object Record by Using the Salesforce ID
You use the SObject Rows resource to retrieve field values from a record. Specify the fields you want to retrieve in the fields
parameter and use the GET method of the resource.
Get Field Values from an External Object Record by Using the External ID Standard Field
You use the SObject Rows resource to retrieve field values from a record. Specify the fields you want to retrieve in the fields
parameter and use the GET method of the resource.
Retrieve a Record Using an External ID
You can use the GET method of the SObject Rows by External ID resource to retrieve records with a specific external ID.
Insert or Update (Upsert) a Record Using an External ID
You can use the SObject Rows by External ID resource to create records or update existing records (upsert) based on the value of a
specified external ID field.
Traverse Relationships with Friendly URLs
You can traverse relationship fields in objects by constructing friendly URLs via the SObject Relationship resource. This approach
allows you to directly access records associated with relationships. Using friendly URLs is easier than accessing records by obtaining
object IDs from relationship fields and then inspecting the associated object ID record.
Get Attachment Content from a Record
Use the SObject Blob Retrieve resource to retrieve blob data for a given record.
Insert or Update Blob Data
You can use SObject Basic Information and SObject Rows REST resources to insert or update blob data in Salesforce standard objects.
You can upload files of any type, and you must use a multipart message that conforms to the MIME multipart content-type standard.
For more information, see the WC3 Standards. You can insert or update files on any standard object that contains a blob field. The
maximum file size for uploads is 2 GB for ContentVersion objects and 500 MB for all other eligible standard objects.
Get a List of Deleted Records Within a Given Timeframe
Use the SObject Get Deleted resource to get a list of deleted records for the specified object. Specify the date and time range within
which the records for the given object were deleted. Deleted records are written to a delete log (that is periodically purged), and
will be filtered out of most operations, such as SObject Rows or Query (although QueryAll will include deleted records in results).
Get a List of Updated Records Within a Given Timeframe
Use the SObject Get Updated resource to get a list of updated (modified or added) records for the specified object. Specify the date
and time range within which the records for the given object were updated.

Create a Record
Use the SObject Basic Information resource to create new records. You supply the required field values in the request data, and then use
the POST method of the resource. The response body will contain the ID of the created record if the call is successful.
The following example creates a new Account record, with the field values provided in newaccount.json.
Example for creating a new Account
curl https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Account/ -H
"Authorization: Bearer token -H "Content-Type: application/json" -d "@newaccount.json"

Examples

Update a Record

Example request body newaccount.json file for creating a new Account

{
"Name" : "Express Logistics and Transport"
}

Example response body after successfully creating a new Account

{
"id" : "001D000000IqhSLIAZ",
"errors" : [ ],
"success" : true
}

Update a Record
You use the SObject Rows resource to update records. Provide the updated record information in your request data and use the PATCH
method of the resource with a specific record ID to update that record. Records in a single file must be of the same object type.
In the following example, the Billing City within an Account is updated. The updated record information is provided in
patchaccount.json.
Example for updating an Account object
curl
https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Account/001D000000INjVe
-H "Authorization: Bearer token" -H "Content-Type: application/json" -d
@patchaccount.json -X PATCH

Example request body patchaccount.json file for updating fields in an Account object
{
"BillingCity" : "San Francisco"
}

Example response body for updating fields in an Account object

none returned
Error response
See Status Codes and Error Responses on page 210.
The following example uses Java and HttpClient to update a record using REST API. Note that there is no PatchMethod in HttpClient, so
PostMethod is overridden to return PATCH as its method name. This example assumes the resource URL has been passed in and
contains the object name and record ID.
public static void patch(String url, String sid) throws IOException {
PostMethod m = new PostMethod(url) {
@Override public String getName() { return "PATCH"; }
};
m.setRequestHeader("Authorization", "OAuth " + sid);
Map<String, Object> accUpdate = new HashMap<String, Object>();
accUpdate.put("Name", "Patch test");
ObjectMapper mapper = new ObjectMapper();
m.setRequestEntity(new StringRequestEntity(mapper.writeValueAsString(accUpdate),

Examples

Delete a Record

"application/json", "UTF-8"));
HttpClient c = new HttpClient();
int sc = c.executeMethod(m);
System.out.println("PATCH call returned a status code of " + sc);
if (sc > 299) {
// deserialize the returned error message
List<ApiError> errors = mapper.readValue(m.getResponseBodyAsStream(), new
TypeReference<List<ApiError>>() {} );
for (ApiError e : errors)
System.out.println(e.errorCode + " " + e.message);
}
}
private static class ApiError {
public String errorCode;
public String message;
public String [] fields;
}

Example request body

None required

Examples

Retrieve a Record Using an External ID

Example response body

{
"attributes" : {
"type" : "Customer__x",
"url" : "/services/data/v32.0/sobjects/Customer__x/CACTU"
},
"Country__c" : "Argentina",
"ExternalId" : "CACTU"
}

Retrieve a Record Using an External ID

You can use the GET method of the SObject Rows by External ID resource to retrieve records with a specific external ID.
The following example assumes there is a Merchandise__c custom object with a MerchandiseExtID__c external ID field.
Example usage for retrieving a Merchandise__c record using an external ID
curl
https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Merchandise__c/MerchandiseExtID__c/123
-H "Authorization: Bearer token"

Example request body

none required
Example response body
{
"attributes" : {
"type" : "Merchandise__c",
"url" : "/services/data/v20.0/sobjects/Merchandise__c/a00D0000008oWP8IAM"
},
"Id" : "a00D0000008oWP8IAM",
"OwnerId" : "005D0000001KyEIIA0",
"IsDeleted" : false,
"Name" : "Example Merchandise",
"CreatedDate" : "2012-07-12T17:49:01.000+0000",
"CreatedById" : "005D0000001KyEIIA0",
"LastModifiedDate" : "2012-07-12T17:49:01.000+0000",
"LastModifiedById" : "005D0000001KyEIIA0",
"SystemModstamp" : "2012-07-12T17:49:01.000+0000",
"Description__c" : "Merch with external ID",
"Price__c" : 10.0,
"Total_Inventory__c" : 100.0,
"Distributor__c" : null,
"MerchandiseExtID__c" : 123.0
}

Insert or Update (Upsert) a Record Using an External ID

You can use the SObject Rows by External ID resource to create records or update existing records (upsert) based on the value of a
specified external ID field.
If the specified value doesn't exist, a new record is created.

Examples

Insert or Update (Upsert) a Record Using an External ID

If a record does exist with that value, the field values specified in the request body are updated.
If the value is not unique, REST API returns a 300 response with the list of matching records.
The following sections show you how to work with the external ID resource to retrieve records by external ID and upsert records.

Upserting New Records

This example uses the PATCH method to insert a new record. It assumes that an external ID field, customExtIdField__c, has been added
to Account. It also assumes that an Account record with a customExtIdField value of 11999 does not already exist.
Example for upserting a record that does not yet exist
curl
https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Account/customExtIdField__c/11999
-H "Authorization: Bearer token" -H "Content-Type: application/json" -d @newrecord.json
-X PATCH

Example JSON request body newrecord.json file

{
"Name" : "California Wheat Corporation",
"Type" : "New Customer"
}

Response
Successful response:
{
"id" : "00190000001pPvHAAU",
"errors" : [ ],
"success" : true
}

HTTP status code 201 is returned if a new record is created.

Error responses
Incorrect external ID field:
{
"message" : "The requested resource does not exist",
"errorCode" : "NOT_FOUND"
}

For more information, see Status Codes and Error Responses on page 210.

Inserting New Records Using Id as the External ID

This example uses the POST method as a special case to insert a record where the Id field is treated as the external ID. Because the
value of Id is null, its omitted from the request. This pattern is useful when youre writing code to upsert multiple records by different
external IDs and you dont want to request a separate resource. POST using Id is available in API version 37.0 and later.

Examples

Insert or Update (Upsert) a Record Using an External ID

Example of inserting a record that does not yet exist

curl https://yourInstance.salesforce.com/services/data/v37.0/sobjects/Account/Id -H
"Authorization: Bearer token" -H "Content-Type: application/json" -d @newrecord.json
-X POST

Example JSON request body newrecord.json file

{
"Name" : "California Wheat Corporation",
"Type" : "New Customer"
}

Response
Successful response:
{
"id" : "001D000000Kv3g5IAB",
"success" : true,
"errors" : [ ]
}

HTTP status code 201 is returned if a record is created.

Upserting Existing Records

This example uses the PATCH method to update an existing record. It assumes that an external ID field, customExtIdField__c, has been
added to Account and an Account record with a customExtIdField value of 11999 exists. The request uses updates.json to specify
the updated field values.
Example of upserting an existing record
curl
https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Account/customExtIdField__c/11999
-H "Authorization: Bearer token" -H "Content-Type: application/json" -d @updates.json
-X PATCH

Example JSON request body updates.json file

{
"BillingCity" : "San Francisco"
}

JSON example response

HTTP status code 204 is returned if an existing record is updated.
Error responses
If the external ID value isn't unique, an HTTP status code 300 is returned, plus a list of the records that matched the query. For more
information about errors, see Status Codes and Error Responses on page 210.

Examples

Insert or Update (Upsert) a Record Using an External ID

If the external ID field doesn't exist, an error message and code is returned:
{
"message" : "The requested resource does not exist",
"errorCode" : "NOT_FOUND"
}

Upserting Records and Associating with an External ID

If you have an object that references another object using a relationship, you can use REST API to both insert or update a record and
also reference another object using an external ID.
The following example creates a record and associates it with a parent record via external ID. It assumes the following:
A Merchandise__c custom object that has an external ID field named MerchandiseExtID__c.
A Line_Item__c custom object that has an external ID field named LineItemExtID__c, and a relationship to Merchandise__c.
A Merchandise__c record exists that has a MerchandiseExtID__c value of 123.
A Line_Item__c record with a LineItemExtID__c value of 456 does not exist. This is the record that gets created and associated to
the Merchandise__c record.
Example of upserting a record and referencing a related object
curl
https://yourInstance.salesforce.com/services/data/v25.0/sobjects/Line_Item__c/LineItemExtID__c/456
-H "Authorization: Bearer token" -H "Content-Type: application/json" -d @new.json -X
PATCH

Example JSON request body new.json file

Notice that the related Merchandise__c record is referenced using the Merchandise__cs external ID field.
{
"Name" : "LineItemCreatedViaExtID",
"Merchandise__r" :
{
"MerchandiseExtID__c" : 123
}
}

JSON example response

HTTP status code 201 is returned on successful create.
{
"id" : "a02D0000006YUHrIAO",
"errors" : [ ],
"success" : true
}

Error responses
If the external ID value isn't unique, an HTTP status code 300 is returned, plus a list of the records that matched the query. For more
information about errors, see Status Codes and Error Responses on page 210.
If the external ID field doesn't exist, an error message and code is returned:
{
"message" : "The requested resource does not exist",

Examples

Traverse Relationships with Friendly URLs

"errorCode" : "NOT_FOUND"
}

You can also use this approach to update existing records. For example, if you created the Line_Item__c shown in the example above,
you can try to update the related Merchandise__c using another request.
Example for updating a record
curl
https://yourInstance.salesforce.com/services/data/v25.0/sobjects/Line_Item__c/LineItemExtID__c/456
-H "Authorization: Bearer token" -H "Content-Type: application/json" -d @updates.json
-X PATCH

Example JSON request body updates.json file

This assumes another Merchandise__c record exists with a MerchandiseExtID__c value of 333.
{
"Merchandise__r" :
{
"MerchandiseExtID__c" : 333
}
}

JSON example response

HTTP status code 204 is returned if an existing record is updated.
If the relationship type is master-detail and the relationship is set to not allow reparenting, and you try to update the parent external ID,
you get an HTTP status code 400 error with an error code of INVALID_FIELD_FOR_INSERT_UPDATE.

Traverse Relationships with Friendly URLs

You can traverse relationship fields in objects by constructing friendly URLs via the SObject Relationship resource. This approach allows
you to directly access records associated with relationships. Using friendly URLs is easier than accessing records by obtaining object IDs
from relationship fields and then inspecting the associated object ID record.
Relationship names follow certain conventions that depend on the direction (parent to child, or child to parent) of the relationship and
the name of the related object. The conventions are described in Understanding Relationship Names in the Force.com SOQL and SOSL
Reference.
There are limits to the number of relationship traversals you can make in a single REST API call. These limits are the same as the limits
for SOQL, as described in Understanding Relationship Query Limitations in the Force.com SOQL and SOSL Reference. Keep the following
limitations in mind when traversing relationships.
When specifying child-to-parent relationships, no more than five levels can be traversed. The following traverses two child-to-parent
relationships.
https://instance name.salesforce.com/services/data/v38.0/sobjects/ChildOfChild__c/record
id/Child__r/ParentOfChild__r

When specifying parent-to-child relationships, no more than one level can be traversed. The following traverses one parent-to-child
relationship.
https://instance name.salesforce.com/services/data/v38.0/sobjects/ParentOfChild__c/record
id/Child__r

Examples

Traverse Relationships with Friendly URLs

Example of traversing a simple relationship

This custom object named Merchandise__c contains a lookup relationship field to a child Distributor__c custom object. The following
example retrieves the Distributor__c record related to a Merchandise__c record.
curl
https://yourInstance.salesforce.com/services/data/v36.0/sobjects/Merchandise__c/a01D000000INjVe/Distributor__r
-H "Authorization: Bearer token"

Example request body for traversing a simple relationship

none required
Example response body for traversing a simple relationship
{
"attributes" :
{
"type" : "Distributor__c",
"url" : "/services/data/v36.0/sobjects/Distributor__c/a03D0000003DUhcIAG"
},
"Id" : "a03D0000003DUhcIAG",
"OwnerId" : "005D0000001KyEIIA0",
"IsDeleted" : false,
"Name" : "Distributor1",
"CreatedDate" : "2011-12-16T17:43:01.000+0000",
"CreatedById" : "005D0000001KyEIIA0",
"LastModifiedDate" : "2011-12-16T17:43:01.000+0000",
"LastModifiedById" : "005D0000001KyEIIA0",
"SystemModstamp" : "2011-12-16T17:43:01.000+0000",
"Location__c" : "San Francisco"
}

If no related record is associated with the relationship name, the REST API call fails, because the relationship cant be traversed. Using
the previous example, if the Distributor__c field in the Merchandise__c record was set to null, the GET call would return a 404 error
response.
You can traverse multiple relationships within the same relationship hierarchy in a single REST API call as long as you dont exceed the
relationship query limits. If a Line_Item__c custom object is the child in a relationship to a Merchandise__c custom object, and
Merchandise__c also has a child Distributor__c custom object, you can access the Distributor__c record starting from the Line_Item__c
record using something like the following.
curl
https://yourInstance.salesforce.com/services/data/v36.0/sobjects/Line_Item__c/a02D0000006YL7XIAW/Merchandise__r/Distributor__r
-H "Authorization: Bearer token"

Relationship traversal also supports PATCH and DELETE methods for relationships that resolve to a single record. Using the PATCH
method, you can update the related record.
Example of using PATCH to update a relationship record
curl
https://yourInstance.salesforce.com/services/data/v36.0/sobjects/Merchandise__c/a01D000000INjVe/Distributor__r
-H "Authorization: Bearer token" -d @update_info.json -X PATCH

Examples

Traverse Relationships with Friendly URLs

Example JSON request body for updating a relationship record contained in update_info.json
{
"Location__c" : "New York"
}

Example response body for updating relationship record

none returned
Finally, using the DELETE method, you can delete the related record.
Example using DELETE to delete a relationship record
curl
https://yourInstance.salesforce.com/services/data/v36.0/sobjects/Merchandise__c/a01D000000INjVe/Distributor__r
-H "Authorization: Bearer token" -X DELETE

Example request body for deleting a relationship record

none required
Example response body for update relationship record
none returned

Traversing Relationships with Multiple Records

You can traverse relationships with multiple records, and get a response that contains the set of records. For relationships that resolve
to multiple records, only GET methods are supported.
Example traversing a relationship with multiple records
If we have a custom object named Merchandise__c that contains a masterdetail relationship field to a Line_Item__c custom
object, the following example retrieves the set of Line_Item__c records related to a Merchandise__c record.
curl
https://yourInstance.salesforce.com/services/data/v36.0/sobjects/Merchandise__c/a01D000000INjVe/Line_Items__r
-H "Authorization: Bearer token"

Example request body for traversing a relationship with multiple records

none required
Example response body for traversing a relationship with multiple records
For this example, two Line_Item__c records were retrieved.
{
"done" : true,
"totalSize" : 2,
"records" :
[
{
"attributes" :
{
"type" : "Line_Item__c",
"url" : "/services/data/v36.0/sobjects/Line_Item__c/a02D0000006YL7XIAW"
},
"Id" : "a02D0000006YL7XIAW",
"IsDeleted" : false,
"Name" : "LineItem1",

Examples

Traverse Relationships with Friendly URLs

"CreatedDate" : "2011-12-16T17:44:07.000+0000",
"CreatedById" : "005D0000001KyEIIA0",
"LastModifiedDate" : "2011-12-16T17:44:07.000+0000",
"LastModifiedById" : "005D0000001KyEIIA0",
"SystemModstamp" : "2011-12-16T17:44:07.000+0000",
"Unit_Price__c" : 9.75,
"Units_Sold__c" : 10.0,
"Merchandise__c" : "a00D0000008oLnXIAU",
"Invoice_Statement__c" : "a01D000000D85hkIAB"
},
{
"attributes" :
{
"type" : "Line_Item__c",
"url" : "/services/data/v36.0/sobjects/Line_Item__c/a02D0000006YL7YIAW"
},
"Id" : "a02D0000006YL7YIAW",
"IsDeleted" : false,
"Name" : "LineItem2",
"CreatedDate" : "2011-12-16T18:53:59.000+0000",
"CreatedById" : "005D0000001KyEIIA0",
"LastModifiedDate" : "2011-12-16T18:53:59.000+0000",
"LastModifiedById" : "005D0000001KyEIIA0",
"SystemModstamp" : "2011-12-16T18:54:00.000+0000",
"Unit_Price__c" : 8.5,
"Units_Sold__c" : 8.0,
"Merchandise__c" : "a00D0000008oLnXIAU",
"Invoice_Statement__c" : "a01D000000D85hkIAB"
}
]
}

The serialized structure for the result data is the same format as result data from executing a SOQL query via REST API. See Query on
page 173 for more details on executing SOQL queries via REST API
If no related records are associated with the relationship name, the REST API call returns a 200 response with no record data in the
response body. This result is in contrast to the results when traversing an empty relationship to a single record, which returns a 404 error
response. This behavior is because the single record case resolves to a REST resource that can be used with PATCH or DELETE methods.
In contrast, the multiple record case can only be queried.
If an initial GET request for a relationship with multiple records returns only part of the results, the end of the response contains the field
nextRecordsUrl. For example, you could get a field like the following at the end of your response.
"nextRecordsUrl" : "/services/data/v38.0/query/01gD0000002HU6KIAW-2000"

You can request the next batch of records using the provided URL with your instance and session information, and repeat until all records
have been retrieved. These requests use nextRecordsUrl and dont include any parameters. The final batch of records doesnt
have a nextRecordsUrl field.
Example usage for retrieving the remaining results
curl
https://yourInstance.salesforce.com/services/data/v36.0/query/01gD0000002HU6KIAW-2000
-H "Authorization: Bearer token"

Examples

Traverse Relationships with Friendly URLs

Example request body for retrieving the remaining results

none required
Example response body for retrieving the remaining results
{
"done" : true,
"totalSize" : 3200,
"records" : [...]
}

Filtering Result Fields

When retrieving records via relationship traversals, you can optionally specify only a subset of the record fields be returned by using the
fields parameter. Multiple fields are separated by commas. The following example retrieves just the Location__c field from the
Distributor__c record associated with a Merchandise__c record:
curl
https://yourInstance.salesforce.com/services/data/v36.0/sobjects/Merchandise__c/a01D000000INjVe/Distributor__r?fields=Location__c
-H "Authorization: Bearer token"

The JSON response data would look like the following:

{
"attributes" :
{
"type" : "Distributor__c",
"url" : "/services/data/v36.0/sobjects/Distributor__c/a03D0000003DUhhIAG"
},
"Location__c" : "Chicago",
}

Similarly, for requests that result in multiple records, you can use a list of fields to specify the fields returned in the record set. For example,
assume you have a relationship that was associated with two Line_Item__c records. You want just the Name and Units_Sold__c fields
from those records. You could use the following call.
curl
https://yourInstance.salesforce.com/services/data/v36.0/sobjects/Merchandise__c/a01D000000INjVe/Distributor__r?fields=Name,Units_Sold__c
-H "Authorization: Bearer token"

The response data would look like the following.

{
"done" : true,
"totalSize" : 2,
"records" :
[
{
"attributes" :
{
"type" : "Line_Item__c",
"url" : "/services/data/v36.0/sobjects/Line_Item__c/a02D0000006YL7XIAW"
},
"Name" : "LineItem1",
"Units_Sold__c" : 10.0

Examples

Get Attachment Content from a Record

},
{
"attributes" :
{
"type" : "Line_Item__c",
"url" : "/services/data/v36.0/sobjects/Line_Item__c/a02D0000006YL7YIAW"
},
"Name" : "LineItem2",
"Units_Sold__c" : 8.0
}
]
}

If any field listed in the fields parameter set isnt visible to the active user, the REST API call fails. In the previous example, if the Units_Sold_c
field was hidden from the active user by field-level security, the call would return a 400 error response.

Get Attachment Content from a Record

Use the SObject Blob Retrieve resource to retrieve blob data for a given record.
The following example retrieves the blob data for an Attachment record. The Attachment can be associated with a Case, Campaign, or
other object that allows attachments.
Example for retrieving blob body for an Attachment record
curl
https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Attachment/001D000000INjVe/body
-H "Authorization: Bearer token"

Example request body

none required
Example response body
Attachment body content is returned in binary form. Note that the response content type will not be JSON or XML since the returned
data is binary.
The following example retrieves the blob data for a Document record.
Example for retrieving blob body for a Document record
curl
https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Document/015D0000000NdJOIA0/body
-H "Authorization: Bearer token"

Example request body

none required
Example response body
Document body content is returned in binary form. Note that the response content type will not be JSON or XML since the returned
data is binary.

Examples

Insert or Update Blob Data

You can use SObject Basic Information and SObject Rows REST resources to insert or update blob data in Salesforce standard objects.
You can upload files of any type, and you must use a multipart message that conforms to the MIME multipart content-type standard.
For more information, see the WC3 Standards. You can insert or update files on any standard object that contains a blob field. The
maximum file size for uploads is 2 GB for ContentVersion objects and 500 MB for all other eligible standard objects.
Note: You can insert or update blob data using a non-multipart message, but if you do, you are limited to 50 MB of text data or
37.5 MB of base64encoded data.
The first part of the request message body contains nonbinary field data such as the Description or Name. The second part of the
message contains the binary data of the file that you're uploading.
The following sections provide JSON examples of how to insert or update blob data using a multipart content-type.
Inserting a New Document
Updating a Document
Inserting a ContentVersion
Multipart Message Considerations

Inserting a New Document

This section contains the syntax and code for creating a new Document. In addition to the binary data of the file itself, this code also
specifies other field data such as the Description, Keywords, Name, and so on.
Tip: After you add a new Document, you can view the results of your changes on the Documents tab.
Example for creating a new Document
curl https://yourInstance.salesforce.com/services/data/v23.0/sobjects/Document/ -H
"Authorization: Bearer token" -H "Content-Type: multipart/form-data;
boundary=\"boundary_string\"" --data-binary @newdocument.json

Example request body for creating a new Document

This code is the contents of newdocument.json. Note that the binary data for the PDF content has been omitted for brevity
and replaced with Binary data goes here. An actual request will contain the full binary content.
--boundary_string
Content-Disposition: form-data; name="entity_document";
Content-Type: application/json
{
"Description" : "Marketing brochure for Q1 2011",
"Keywords" : "marketing,sales,update",
"FolderId" : "005D0000001GiU7",
"Name" : "Marketing Brochure Q1",
"Type" : "pdf"
}
--boundary_string
Content-Type: application/pdf
Content-Disposition: form-data; name="Body"; filename="2011Q1MktgBrochure.pdf"
Binary data goes here.

Examples

Insert or Update Blob Data

--boundary_string--

Example response body for creating a new Document

On success, the ID of the new Document is returned.
{
"id" : "015D0000000N3ZZIA0",
"errors" : [ ],
"success" : true
}

Example error response

{
"fields" : [ "FolderId" ],
"message" : "Folder ID: id value of incorrect type: 005D0000001GiU7",
"errorCode" : "MALFORMED_ID"
}

Updating a Document
This section contains the syntax and code for updating an existing Document. In addition to the binary data of the file itself, this code
also updates other field data such as the Name and Keywords.
Example usage for updating fields in a Document object
curl https://yourInstance.salesforce.com/services/data/v23.0/Document/015D0000000N3ZZIA0
-H "Authorization: Bearer token" -H "Content-Type: multipart/form-data;
boundary=\"boundary_string\"" --data-binary @UpdateDocument.json -X PATCH

Example request body for updating fields in a Document object

This code is the contents of the file UpdateDocument.json. Note that the binary data for the PDF content has been omitted
for brevity and replaced with Updated document binary goes here. An actual request will contain the full binary content.
--boundary_string
Content-Disposition: form-data; name="entity_content";
Content-Type: application/json
{
"Name" : "Marketing Brochure Q1 - Sales",
"Keywords" : "sales, marketing, first quarter"
}
--boundary_string
Content-Type: application/pdf
Content-Disposition: form-data; name="Body"; filename="2011Q1MktgBrochure.pdf"
Updated document binary data goes here.
--boundary_string--

Example response body for updating fields in a Document object

none returned

Examples

Insert or Update Blob Data

Execute a SOQL Query

Example response body for executing a query

{
"done" : true,
"totalSize" : 14,
"records" :
[
{
"attributes" :
{
"type" : "Account",
"url" : "/services/data/v20.0/sobjects/Account/001D000000IRFmaIAH"
},
"Name" : "Test 1"
},
{
"attributes" :
{
"type" : "Account",
"url" : "/services/data/v20.0/sobjects/Account/001D000000IomazIAB"
},
"Name" : "Test 2"
},
...
]
}

Retrieving the Remaining SOQL Query Results

If the initial query returns only part of the results, the end of the response will contain a field called nextRecordsUrl. For example,
you might find this attribute at the end of your query:
"nextRecordsUrl" : "/services/data/v20.0/query/01gD0000002HU6KIAW-2000"

In such cases, request the next batch of records and repeat until all records have been retrieved. These requests use nextRecordsUrl,
and do not include any parameters.
Example usage for retrieving the remaining query results
curl
https://yourInstance.salesforce.com/services/data/v20.0/query/01gD0000002HU6KIAW-2000
-H "Authorization: Bearer token"

Example request body for retrieving the remaining query results

none required
Example response body for retrieving the remaining query results
{
"done" : true,
"totalSize" : 3214,
"records" : [...]
}

Examples

Execute a SOQL Query that Includes Deleted Items

Use the QueryAll resource to execute a SOQL query that includes information about records that have been deleted because of a merge
or delete. Use QueryAll rather than Query, because the Query resource will automatically filter out items that have been deleted.
The following query requests the value from the Name field from all deleted Merchandise__c records, in an organization that has one
deleted Merchandise__c record. The same query using Query instead of QueryAll would return no records, because Query automatically
filters out any deleted record from the result set.
Example usage for executing a query for deleted Merchandise__c records
/services/data/v29.0/queryAll/?q=SELECT+Name+from+Merchandise__c+WHERE+isDeleted+=+TRUE

Example request body for executing a query

none required
Example response body for executing a query
{
"done" : true,
"totalSize" : 1,
"records" :
[
{
"attributes" :
{
"type" : "Merchandise__c",
"url" : "/services/data/v29.0/sobjects/Merchandise__c/a00D0000008pQRAIX2"
},
"Name" : "Merchandise 1"
},
]
}

Retrieving the Remaining SOQL Query Results

In such cases, request the next batch of records and repeat until all records have been retrieved. These requests use nextRecordsUrl,
and do not include any parameters.
Note that even though nextRecordsUrl has query in the URL, it will still provide remaining results from the initial QueryAll
request. The remaining results will include deleted records that matched the initial query.
Example usage for retrieving the remaining results
/services/data/v29.0/query/01gD0000002HU6KIAW-2000

Example request body for retrieving the remaining results

none required

Examples

Get Feedback on Query Performance

Example response body for retrieving the remaining results

{
"done" : true,
"totalSize" : 3214,
"records" : [...]
}

Get Feedback on Query Performance

Use the Query resource along with the explain parameter to get feedback on how Salesforce will execute your query, report, or list
view. Salesforce analyzes each query to find the optimal approach to obtain the query results. Depending on the query and query filters,
an index or internal optimization might get used. You use the explain parameter to return details on how Salesforce will optimize
your query, without actually running the query. Based on the response, you can decide whether to fine-tune the performance of your
query by making changes like adding filters to make the query more selective.
Note: Using explain with the REST API query resource is a beta feature. There is no support associated with this beta feature.
For more information, contact Salesforce.
The response will contain one or more query execution plans that, sorted from most optimal to least optimal. The most optimal plan is
the plan thats used when the query, report, or list view is executed.
See the explain parameter in Query for more details on the fields returned when using explain. See Working with Very Large
SOQL Queries in the Apex Developer Guide for more information on making your queries more selective.
Example:
Example usage for getting performance feedback on a query that uses Merchandise__c
/services/data/v38.0/query/?explain=
SELECT+Name+FROM+Merchandise__c+WHERE+CreatedDate+=+TODAY+AND+Price__c+>+10.0

Example response body for executing a performance feedback query

{
"plans" : [ {
"cardinality" : 1,
"fields" : [ "CreatedDate" ],
"leadingOperationType" : "Index",
"notes" : [ {
"description" : "Not considering filter for optimization because unindexed",
"fields" : [ "IsDeleted" ],
"tableEnumOrId" : "Merchandise__c"
} ],
"relativeCost" : 0.0,
"sobjectCardinality" : 3,
"sobjectType" : "Merchandise__c"
}, {
"cardinality" : 1,
"fields" : [ ],
"leadingOperationType" : "TableScan",
"notes" : [ {
"description" : "Not considering filter for optimization because unindexed",
"fields" : [ "IsDeleted" ],
"tableEnumOrId" : "Merchandise__c"

Examples

Search for a String

} ],
"relativeCost" : 0.65,
"sobjectCardinality" : 3,
"sobjectType" : "Merchandise__c"
} ]
}

This response indicates that Salesforce found two possible execution plans for this query. The first plan uses the CreatedDate
index field to improve the performance of this query. The second plan scans all records without using an index. The first plan
will be used if the query is actually executed. Both plans note that a secondary optimization used when filtering out records
marked as deleted was not used because the IsDeleted field is not indexed.
Example:
Example usage for getting performance feedback on a report
/services/data/v38.0/query/?explain=00OD0000001hCzMMCU

Example response body for getting performance feedback on a report

{
"plans" : [ {
"cardinality" : 1,
"fields" : [ ],
"leadingOperationType" : "TableScan",
"notes" : [ {
"description" : "Not considering filter for optimization because unindexed",
"fields" : [ "IsDeleted" ],
"tableEnumOrId" : "Merchandise__c"
} ],
"relativeCost" : 0.65,
"sobjectCardinality" : 3,
"sobjectType" : "Merchandise__c"
} ]
}

This response indicates that Salesforce found one possible execution plan for the query behind this report. The plan scans all
records without using an index, and cant apply a secondary optimization used when filtering out records marked as deleted
because the IsDeleted field is not indexed.

Search for a String

Use the Search resource to execute a SOSL search or use the Parameterized Search resource to execute a simple RESTful search without
SOSL.

Example SOSL Search Using the GET Method

The following example executes a SOSL search for Acme. The search string in this example must be URL-encoded.
Example usage
curl
https://https://yourInstance.salesforce.com/services/data/v37.0/search/?q=FIND+%7BAcme%7D
-H "Authorization: Bearer token"

Examples

Search for a String

Example request body

None required
Example response body
{
"searchRecords" : [ {
"attributes" : {
"type" : "Account",
"url" : "/services/data/v35.0/sobjects/Account/001D000000IqhSLIAZ"
},
"Id" : "001D000000IqhSLIAZ",
}, {
"attributes" : {
"type" : "Account",
"url" : "/services/data/v35.0/sobjects/Account/001D000000IomazIAB"
},
"Id" : "001D000000IomazIAB",
} ]
}

Example Parameterized Search Using the GET Method

The following example executes a parameterized search for Acme. The search string in this example must be URL-encoded.
Example usages
Global search for all results containing Acme
curl
https://https://yourInstance.salesforce.com/services/data/v37.0/parameterizedSearch/?q=Acme

Account search for results containing Acme, returning the id and name fields
curl
https://https://yourInstance.salesforce.com/services/data/v37.0/parameterizedSearch/?q=Acme&sobject=Account&Account.fields=id,name&Account.limit=10

Example request body

None required
Example response body
{
"searchRecords" : [ {
"attributes" : {
"type" : "Account",
"url" : "/services/data/v35.0/sobjects/Account/001D000000IqhSLIAZ"
},
"Id" : "001D000000IqhSLIAZ"
}, {
"attributes" : {
"type" : "Account",
"url" : "/services/data/v35.0/sobjects/Account/001D000000IomazIAB"
},
"Id" : "001D000000IomazIAB"
} ]
}

Use the Search Result Layouts resource to retrieve the search result layout configuration for each object specified in the query string.
Example usage
curl
https://yourInstance.salesforce.com/services/data/v28.0/searchlayout/?q=Account,Contact,Lead,Asset
"Authorization: Bearer token"

Example request body

None required
Example response body
[ { "label" : "Search Results",
"limitRows" : 25,
"searchColumns" : [ { "field" : "Account.Name",
"format" : null,
"label" : "Account Name",
"name" : "Name"
},
{ "field" : "Account.Site",
"format" : null,
"label" : "Account Site",
"name" : "Site"
},
{ "field" : "Account.Phone",
"format" : null,
"label" : "Phone",
"name" : "Phone"
},
{ "field" : "User.Alias",
"format" : null,
"label" : "Account Owner Alias",
"name" : "Owner.Alias"
}
]
},
{ "label" : "Search Results",
"limitRows" : 25,

Examples

Get Search Result Layouts for Objects

"searchColumns" : [ { "field" : "Contact.Name",

"format" : null,
"label" : "Name",
"name" : "Name"
},
{ "field" : "Account.Name",
"format" : null,
"label" : "Account Name",
"name" : "Account.Name"
},
{ "field" : "Account.Site",
"format" : null,
"label" : "Account Site",
"name" : "Account.Site"
},
{ "field" : "Contact.Phone",
"format" : null,
"label" : "Phone",
"name" : "Phone"
},
{ "field" : "Contact.Email",
"format" : null,
"label" : "Email",
"name" : "Email"
},
{ "field" : "User.Alias",
"format" : null,
"label" : "Contact Owner Alias",
"name" : "Owner.Alias"
}
]
},
{ "label" : "Search Results",
"limitRows" : 25,
"searchColumns" : [ { "field" : "Lead.Name",
"format" : null,
"label" : "Name",
"name" : "Name"
},
{ "field" : "Lead.Title",
"format" : null,
"label" : "Title",
"name" : "Title"
},
{ "field" : "Lead.Phone",
"format" : null,
"label" : "Phone",
"name" : "Phone"
},
{ "field" : "Lead.Company",
"format" : null,
"label" : "Company",
"name" : "Company"
},

None required
Example response body
[ {
"apiName" : "Account",
"key" : "001",
"label" : "Accounts",
"lastUpdatedId" : "193640553",
"recordIds" : [ "001xx000003DWsT" ]
}, {
"apiName" : "User",
"key" : "005",
"label" : "Users",
"lastUpdatedId" : "102959935",
"recordIds" : [ "005xx000001Svqw", "005xx000001SvwK", "005xx000001SvwA" ]
} ]

Example usage for comparing the users current list of relevant records to a previous version
/v37.0/sobjects/relevantItems?lastUpdatedId=102959935

Example request body

None required
Example response header
lastUpdatedId: 102959935
newResultSetSinceLastQuery: true

Example response body

[ {
"apiName" : "User",
"key" : "003",
"label" : "Users",
"lastUpdatedId" : "102959935",
"recordIds" : [ "003xx000004TxBA" ]
}, {
"apiName" : "Account",
"key" : "001",
"label" : "Accounts",
"lastUpdatedId" : "193640553",
"recordIds" : [ "001xx000003DWsT" ]
}, {
"apiName" : "Case",
"key" : "005",
"label" : "Cases",
"lastUpdatedId" : "1740766611",
"recordIds" : [ "005xx000001Svqw", "005xx000001SvwA" ]
} ]

Example usage for comparing the users current list of relevant records to a previous version for a particular object
/v37.0/sobjects/relevantItems?mode=MRU&sobjects=Account,Contact&Account.lastUpdatedId=102959935

Examples

Working with Recently Viewed Information

Example request body

None required
Example response body
[ {
"apiName" : "Account",
"key" : "001",
"label" : "Accounts",
"lastUpdatedId" : "193640553",
"recordIds" : [ "001xx000003DWsT" ]
} ]

Working with Recently Viewed Information

The examples in this section use REST API Query and Recently Viewed resources to programmatically retrieve and update recently viewed
record information.
IN THIS SECTION:
View Recently Viewed Records
Use the Recently Viewed Items resource to get a list of recently viewed records.
Mark Records as Recently Viewed
To mark a record as recently viewed using REST API, use the Query resource with a FOR VIEW or FOR REFERENCE clause. Use
SOQL to mark records as recently viewed to ensure that information such as the date and time the record was viewed is correctly
set.

View Recently Viewed Records

Use the Recently Viewed Items resource to get a list of recently viewed records.
Example usage for getting the last two most recently viewed records
/services/data/v28.0/recent/?limit=2

Example request body

none required
Example response body
{
"attributes" :
{
"type" : "Account",
"url" : "/services/data/v28.0/sobjects/Account/a06U000000CelH0IAJ"
},
"Id" : "a06U000000CelH0IAJ",
"Name" : "Acme"
},
{
"attributes" :
{

Examples

Mark Records as Recently Viewed

"type" : "Opportunity",
"url" : "/services/data/v28.0/sobjects/Opportunity/a06U000000CelGvIAJ"
},
"Id" : "a06U000000CelGvIAJ",
"Name" : "Acme - 600 Widgets"
}

Mark Records as Recently Viewed

To mark a record as recently viewed using REST API, use the Query resource with a FOR VIEW or FOR REFERENCE clause. Use
SOQL to mark records as recently viewed to ensure that information such as the date and time the record was viewed is correctly set.
Use FOR VIEW to notify Salesforce when a record is viewed from a custom interface, such as a mobile application or from a custom
page. Use FOR REFERENCE when a record is referenced from a custom interface. A record is referenced every time a related record
is viewed. For more information, see FOR VIEW and FOR REFERENCE in the Force.com SOQL and SOSL Reference.
Example usage for executing a query that marks one Account record as recently viewed
/services/data/v28.0/query/?q=SELECT+Name+FROM+Account+LIMIT+1+FOR+VIEW

Example request body for executing a query

none required
Example response body for executing a query
{
"done" : true,
"totalSize" : 1,
"records" :
[
{
"attributes" :
{
"type" : "Account",
"url" : "/services/data/v28.0/sobjects/Account/001D000000IRFmaIAH"
},
"Name" : "Acme"
},
]
}

Managing User Passwords

The examples in this section use REST API resources to manage user passwords, such as setting or resetting passwords.
IN THIS SECTION:
Manage User Passwords
Use the SObject User Password resource to set, reset, or get information about a user password. Use the HTTP GET method to get
password expiration status, the HTTP POST method to set the password, and the HTTP DELETE method to reset the password.

Examples

Manage User Passwords

Use the SObject User Password resource to set, reset, or get information about a user password. Use the HTTP GET method to get
password expiration status, the HTTP POST method to set the password, and the HTTP DELETE method to reset the password.
The associated session must have permission to access the given user password information. If the session does not have proper
permissions, an HTTP error 403 response is returned from these methods.
These methods are available for both users and self-service users. For managing self-service user passwords, use SelfServiceUser
instead of User in the REST API URL.
Here is an example of retrieving the current password expiration status for a user:
Example usage for getting current password expiration status
curl
https://yourInstance.salesforce.com/services/data/v25.0/sobjects/User/005D0000001KyEIIA0/password
-H "Authorization: Bearer token"

Example request body for getting current password expiration status

None required
JSON example response body for getting current password expiration status
{
"isExpired" : false
}

XML example response body for getting current password expiration status
<Password>
<isExpired>false</isExpired>
</Password>

Example error response if session has insufficient privileges

{
"message" : "You do not have permission to view this record.",
"errorCode" : "INSUFFICIENT_ACCESS"
}

Here is an example of changing the password for a given user:

Example usage for changing a user password
curl
https://yourInstance.salesforce.com/services/data/v25.0/sobjects/User/005D0000001KyEIIA0/password
-H "Authorization: Bearer token" H "Content-Type: application/json" d @newpwd.json
X POST

Contents for file newpwd.json

{
"NewPassword" : "myNewPassword1234"
}

Example response for changing a user password

No response body on successful password change, HTTP status code 204 returned.

Examples

Working with Approval Processes and Process Rules

Example error response if new password does not meet organization password requirements
{
"message" : "Your password must have a mix of letters and numbers.",
"errorCode" : "INVALID_NEW_PASSWORD"
}

And finally, here is an example of resetting a user password:

Example usage for resetting a user password
curl
https://yourInstance.salesforce.com/services/data/v25.0/sobjects/User/005D0000001KyEIIA0/password
-H "Authorization: Bearer token" X DELETE

Example request body for resetting a user password

None required
JSON example response body for resetting a user password
{
"NewPassword" : "2sv0xHAuM"
}

XML example response body for resetting a user password

<Result>
<NewPassword>2sv0xHAuM</NewPassword>
</Result>

Working with Approval Processes and Process Rules

The examples in this section use REST API resources to work with approval processes and process rules.
IN THIS SECTION:
Get a List of All Approval Processes
Use the Process Approvals resource to get information about approvals.
Submit a Record for Approval
Use the Process Approvals resource to submit a record or a collection of records for approval. Each call takes an array of requests.
Approve a Record
Use the Process Approvals resource to approve a record or a collection of records. Each call takes an array of requests. The current
user must be an assigned approver.
Reject a Record
Use the Process Approvals resource to reject a record or a collection of records. Each call takes an array of requests. The current user
must be an assigned approver.
Bulk Approvals
Use the Process Approvals resource to do bulk approvals. You can specify a collection of different Process Approvals requests to have
them all executed in bulk.
Get a List of Process Rules
Use the Process Rules resource to get information about process rules.

Examples

Get a List of All Approval Processes

Get a Particular Process Rule

Use the Process Rules resource and specify theSObjectName and workflowRuleId of the rule you want to get the metadata
for.
Trigger Process Rules
Use the Process Rules resource to trigger process rules. All rules associated with the specified ID will be evaluated, regardless of the
evaluation criteria. All IDs must be for records on the same object.

Get a List of All Approval Processes

Use the Process Approvals resource to get information about approvals.
Example usage
curl https://yourInstance.salesforce.com/services/data/v30.0/process/approvals/ -H
"Authorization: Bearer token"

Example request body

none required
Example JSON response body
{
"approvals" : {
"Account" : [ {
"description" : null,
"id" : "04aD00000008Py9",
"name" : "Account Approval Process",
"object" : "Account",
"sortOrder" : 1
} ]
}
}

Submit a Record for Approval

Use the Process Approvals resource to submit a record or a collection of records for approval. Each call takes an array of requests.
Example usage
curl https://yourInstance.salesforce.com/services/data/v30.0/process/approvals/ -H
"Authorization: Bearer token" -H "Content-Type: application/json" -d @submit.json"

Example request body submit.json file

In the following example, the record "001D000000I8mIm" is submitted for approval process "PTO_Request_Process" by skipping its
entry criteria on behalf of submitter "005D00000015rZy."
{
"requests" : [{
"actionType": "Submit",
"contextId": "001D000000I8mIm",
"nextApproverIds": ["005D00000015rY9"],
"comments":"this is a test",
"contextActorId": "005D00000015rZy",

Examples

[ {
"actorIds" : null,
"entityId" : "001D000000I8mImIAJ",
"errors" : null,
"instanceId" : "04gD0000000CvmZIAS",
"instanceStatus" : "Approved",
"newWorkitemIds" : [ ],
"success" : true
}, {
"actorIds" : null,
"entityId" : "003D000000QBZ08IAH",
"errors" : null,
"instanceId" : "04gD0000000CvmeIAC",
"instanceStatus" : "Approved",
"newWorkitemIds" : [ ],
"success" : true
}, {
"actorIds" : [ "005D00000015rY9IAI" ],
"entityId" : "001D000000JRWBdIAP",
"errors" : null,
"instanceId" : "04gD0000000CvmfIAC",
"instanceStatus" : "Pending",
"newWorkitemIds" : [ "04iD0000000Cw6wIAC" ],
"success" : true
} ]

Get a List of Process Rules

Use the Process Rules resource to get information about process rules.
Example usage
curl https://yourInstance.salesforce.com/services/data/v30.0/process/rules/ -H
"Authorization: Bearer token"

Example request body

none required
Example JSON response body
{
"rules" : {
"Account" : [ {
"actions" : [ {
"id" : "01VD0000000D2w7",
"name" : "ApprovalProcessTask",
"type" : "Task"
} ],

Examples

Get a Particular Process Rule

"description" : null,
"id" : "01QD0000000APli",
"name" : "My Rule",
"namespacePrefix" : null,
"object" : "Account"
} ]
}
}

Get a Particular Process Rule

Use the Process Rules resource and specify theSObjectName and workflowRuleId of the rule you want to get the metadata
for.
Example usage
curl
https://yourInstance.salesforce.com/services/data/v30.0/process/rules/Account/01QD0000000APli
-H "Authorization: Bearer token"

Example request body

none required
Example JSON response body
{
"actions" : [ {
"id" : "01VD0000000D2w7",
"name" : "ApprovalProcessTask",
"type" : "Task"
} ],
"description" : null,
"id" : "01QD0000000APli",
"name" : "My Rule",
"namespacePrefix" : null,
"object" : "Account"
}

Trigger Process Rules

Use the Process Rules resource to trigger process rules. All rules associated with the specified ID will be evaluated, regardless of the
evaluation criteria. All IDs must be for records on the same object.
Example usage
curl https://yourInstance.salesforce.com/services/data/v30.0/process/rules/ -H
"Authorization: Bearer token" -H "Content-Type: application/json" -d @rules.json"

Example request body rules.json file

{
"contextIds" : [
"001D000000JRWBd",
"001D000000I8mIm",

Examples

Using Event Monitoring

"001D000000I8aaf"]
}

Example JSON response body

{
"errors" : null,
"success" : true
}

Using Event Monitoring

The examples in this section use REST APIevent monitoring data that contains information useful for assessing organizational usage
trends and user behavior. Because event monitoring is accessed through the Force.com SOAP API and REST API by way of the EventLogFile
object, you can integrate log data with your own back-end storage and data marts so that you can correlate data from multiple orgs
and across disparate systems easily.
Note: Refer to the Object Reference for Salesforce and Force.com for important information about the EventLogFile object.
When using event monitoring, keep the following in mind.
In the unlikely case where no log files are generated for 24 hours, contact Salesforce.
Log data is read-only. You cant insert, update, or delete log data.
Use the EventType field to determine which files were generated for your org.
LogDate tracks usage activity for a 24-hour period, from 12:00 a.m. to 11:59 p.m. UTC time.
An event generates log data in real time. However, log files are generated the day after an event takes place, during nonpeak hours.
Therefore, log file data is unavailable for at least one day after an event.
CreatedDate tracks when the log file was generated.
Log files, represented by the EventType field, are generated only if there is at least one event of that type for the day. If no events
took place, the file isnt generated for that day
Log files are available based on CreatedDate for the last 30 days when orgs purchase User Event Monitoring or one day for
Developer Edition orgs.
All event monitoring logs are exposed to the API through the EventLogFile object, however there is no access through the user
interface.
Event monitoring can be used with the following event types:
Apex Callout
Apex Execution
Apex SOAP
Apex Trigger
API
Async Report
Bulk API
Change Set Operation
Content Distribution
Content Document Link

Examples

Using Event Monitoring

Content Transfer
Dashboard
Document Attachment Downloads
Login
Login As
Logout
MDAPI Operation
Multiblock Report
Package Install
Queued Execution
Report
Report Export
REST API
Salesforce1 Adoption (UI Tracking)
Sandbox
Sites
Time-Based Workflow
Transaction Security
UI Tracking
URI
Visualforce Request
Wave Change
Wave Interaction
Wave Performance
All queries and examples in this section require the View Event Log Files and API Enabled user permissions. Users with the View All
Data permission can also view event monitoring data.
IN THIS SECTION:
Describe Event monitoring Using REST
Use the SObject Describe resource to retrieve all metadata for an object, including information about fields, URLs, and child relationships.
Query Event Monitoring Data with REST
Use the Query resource to retrieve field values from a record. Specify the fields you want to retrieve in the fields parameter and use
the GET method of the resource.
Get Event Monitoring Content from a Record
Use the SObject Blob Retrieve resource to retrieve BLOB data for a given record.
Download Large Event Log Files Using cURL with REST
You might have some event log files that are larger than your tool can handle. A command line tool such as cURL is one method to
download files larger than 100 MB using the SObject Blob Retrieve object

Examples

Describe Event monitoring Using REST

Use the SObject Describe resource to retrieve all metadata for an object, including information about fields, URLs, and child relationships.
Example
You can use Workbench to describe event log files. In the Execute text box, type
/services/data/v32.0/sobjects/EventLogFile/describe.

Example raw response

{
"actionOverrides" : [ ],
"activateable" : false,
"childRelationships" : [ ],
"compactLayoutable" : false,
"createable" : false,
"custom" : false,
"customSetting" : false,
"deletable" : false,
"deprecatedAndHidden" : false,
"feedEnabled" : false,
"fields" : [ {
"autoNumber" : false,
"byteLength" : 18,
"calculated" : false,
"calculatedFormula" : null,
"cascadeDelete" : false,
"caseSensitive" : false,
"controllerName" : null,
"createable" : false,
...
}

Query Event Monitoring Data with REST

Use the Query resource to retrieve field values from a record. Specify the fields you want to retrieve in the fields parameter and use the
GET method of the resource.
You can use Workbench to query event monitoring data. To retrieve event monitoring records based on LogDate and EventType,
in the Execute text box, type:
/services/data/v32.0/query?q=SELECT+Id+,+EventType+,+LogFile+
,+LogDate+,+LogFileLength+FROM+EventLogFile+WHERE+
LogDate+>+Yesterday+AND+EventType+=+'API'

Example raw response

{
"totalSize" : 4,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "EventLogFile",
"url" : "/services/data/v32.0/sobjects/EventLogFile/0ATD000000001bROAQ"
"Id" : "0ATD000000001bROAQ",

Examples

Get Event Monitoring Content from a Record

"EventType" : "API",
"LogFile" : "/services/data/v32.0/sobjects/EventLogFile/0ATD000000001bROAQ/LogFile",
"LogDate" : "2014-03-14T00:00:00.000+0000",
"LogFileLength" : 2692.0
}, {
"attributes" : {
"type" : "EventLogFile",
"url" : "/services/data/v32.0/sobjects/EventLogFile/0ATD000000001SdOAI"
"Id" : "0ATD000000001SdOAI",
"EventType" : "API",
"LogFile" :
"/services/data/v32.0/sobjects/EventLogFile/0ATD000000001SdOAI/LogFile",
"LogDate" : "2014-03-13T00:00:00.000+0000",
"LogFileLength" : 1345.0
}, {
"attributes" : {
"type" : "EventLogFile",
"url" : "/services/data/v32.0/sobjects/EventLogFile/0ATD000000003p1OAA"
"Id" : "0ATD000000003p1OAA",
"EventType" : "API",
"LogFile" :
"/services/data/v32.0/sobjects/EventLogFile/0ATD000000003p1OAA/LogFile",
"LogDate" : "2014-06-21T00:00:00.000+0000",
"LogFileLength" : 605.0
},
{
"attributes" : {
"type" : "EventLogFile",
"url" : "/services/data/v32.0/sobjects/EventLogFile/0ATD0000000055eOAA"
"Id" : "0ATD0000000055eOAA",
"EventType" : "API",
"LogFile" :
"/services/data/v32.0/sobjects/EventLogFile/0ATD0000000055eOAA/LogFile",
"LogDate" : "2014-07-03T00:00:00.000+0000",
"LogFileLength" : 605.0
} ]
}

Get Event Monitoring Content from a Record

Use the SObject Blob Retrieve resource to retrieve BLOB data for a given record.
Example
You can use Workbench to retrieve BLOB data for event monitoring. In the Execute text box, use a GET request similar to this:
/services/data/v32.0/sobjects/EventLogFile/0ATD000000000pyOAA/LogFile.
Example response body
Event monitoring content is returned in binary form. Note that the response content type wont be JSON or XML because the returned
data is binary.
HTTP/1.1 200 OK
Date: Tue, 06 Aug 2013 16:46:10 GMT
Sforce-Limit-Info: api-usage=135/5000
Content-Type: application/octetstream
Transfer-Encoding: chunked

Examples

Download Large Event Log Files Using cURL with REST

"EVENT_TYPE", "ORGANIZATION_ID", "TIMESTAMP","USER_ID", "CLIENT_IP",

"URI", "REFERRER_URI", "RUN_TIME"
"URI", "00DD0000000K5xD", "20130728185606.020", "005D0000001REDy",
"10.0.62.141", "/secur/contentDoor", "https-//login-salesforce-com/",
"11"
"URI", "00DD0000000K5xD", "20130728185556.930", "005D0000001REI0",
"10.0.62.141", "/secur/logout.jsp", "https-//yourInstance-salesforce-com/00O/o",
"54"
"URI", "00DD0000000K5xD", "20130728185536.725", "005D0000001REI0",
"10.0.62.141", "/00OD0000001ckx3",
"https-//yourInstance-salesforce-com/00OD0000001ckx3", "93"

Download Large Event Log Files Using cURL with REST

You might have some event log files that are larger than your tool can handle. A command line tool such as cURL is one method to
download files larger than 100 MB using the SObject Blob Retrieve object
Example: Use the X-PrettyPrint header and the -o flag to output large files to .csv formats
This command downloads a file onto your machine into your downloads folder.
curl
https://yourInstance.salesforce.com/services/data/v32.0/sobjects/EventLogFile/0AT30000000000uGAA/LogFile
-H "Authorization: Bearer token" -H "X-PrettyPrint:1" -o ~/downloads/outputLogFile.csv

We recommend using compression when downloading large event log files. See Using Compression.

Using Composite Resources

The examples in this section use composite resources to improve your applications performance by minimizing the number of round-trips
between the client and server.
IN THIS SECTION:
Update a Record and Get Its Field Values in a Single Request
Use the Batch resource to execute multiple requests in a single API call.
Create Nested Records
Use the SObject Tree resource to create nested records that share a root record type. For example, in a single request, you can create
an account along with its child contacts, and a second account along with its child accounts and contacts. Once the request is
processed, the records are created and parents and children are automatically linked by ID. In the request data, you supply the record
hierarchies, required and optional field values, each records type, and a reference ID for each record, and then use the POST method
of the resource. The response body will contain the IDs of the created records if the request is successful. Otherwise, the response
contains only the reference ID of the record that caused the error and the error information.
Create Multiple Records
While the SObject Tree resource can be used to create nested records, you can also create multiple, unrelated records of the same
type. In a single request, you can create up to two hundred records. In the request data, you supply the required and optional field
values for each record, each records type, and a reference ID for each record, and then use the POST method of the resource. The
response body will contain the IDs of the created records if the request is successful. Otherwise, the response contains only the
reference ID of the record that caused the error and the error information.

Examples

Update a Record and Get Its Field Values in a Single Request

Use the Batch resource to execute multiple requests in a single API call.
The following example updates the name on an account and gets some of the accounts field values in a single request. The batch.json
file contains the subrequest data.
Update a record and query its name and billing postal code in a single request
curl https://yourInstance.salesforce.com/services/data/v34.0/composite/batch/ -H
"Authorization: Bearer token -H "Content-Type: application/json" -d "@batch.json"

Request body batch.json file

{
"batchRequests" : [
{
"method" : "PATCH",
"url" : "v34.0/sobjects/account/001D000000K0fXOIAZ",
"richInput" : {"Name" : "NewName"}
},{
"method" : "GET",
"url" : "v34.0/sobjects/account/001D000000K0fXOIAZ?fields=Name,BillingPostalCode"
}]
}

Response body after successfully executing the subrequests

{
"hasErrors" : false,
"results" : [{
"statusCode" : 204,
"result" : null
},{
"statusCode" : 200,
"result": {
"attributes" : {
"type" : "Account",
"url" : "/services/data/v34.0/sobjects/Account/001D000000K0fXOIAZ"
},
"Name" : "NewName",
"BillingPostalCode" : "94105",
"Id" : "001D000000K0fXOIAZ"
}
}]
}

Create Nested Records

Use the SObject Tree resource to create nested records that share a root record type. For example, in a single request, you can create an
account along with its child contacts, and a second account along with its child accounts and contacts. Once the request is processed,
the records are created and parents and children are automatically linked by ID. In the request data, you supply the record hierarchies,
required and optional field values, each records type, and a reference ID for each record, and then use the POST method of the resource.
The response body will contain the IDs of the created records if the request is successful. Otherwise, the response contains only the
reference ID of the record that caused the error and the error information.
The following example creates two sets of nested records. The first set includes an account and two child contact records. The second
set includes an account, one child account record, and one child contact record. The record data is provided in newrecords.json.
Example for creating two new accounts and their child records
curl https://yourInstance.salesforce.com/services/data/v34.0/composite/tree/Account/
-H "Authorization: Bearer token -H "Content-Type: application/json" -d "@newrecords.json"

Example request body newrecords.json file for creating two new Accounts and their child records
{
"records" :[{
"attributes" : {"type" : "Account", "referenceId" : "ref1"},
"name" : "SampleAccount1",
"phone" : "1234567890",
"website" : "www.salesforce.com",
"numberOfEmployees" : "100",
"industry" : "Banking",
"Contacts" : {
"records" : [{
"attributes" : {"type" : "Contact", "referenceId" : "ref2"},
"lastname" : "Smith",
"Title" : "President",
"email" : "[email protected]"
},{
"attributes" : {"type" : "Contact", "referenceId" : "ref3"},
"lastname" : "Evans",
"title" : "Vice President",
"email" : "[email protected]"
}]
}
},{
"attributes" : {"type" : "Account", "referenceId" : "ref4"},
"name" : "SampleAccount2",
"phone" : "1234567890",
"website" : "www.salesforce.com",
"numberOfEmployees" : "52000",
"industry" : "Banking",
"childAccounts" : {
"records" : [{
"attributes" : {"type" : "Account", "referenceId" : "ref5"},
"name" : "SampleChildAccount1",
"phone" : "1234567890",
"website" : "www.salesforce.com",
"numberOfEmployees" : "100",
"industry" : "Banking"

Examples

Create Multiple Records

}]
},
"Contacts" : {
"records" : [{
"attributes" : {"type" : "Contact", "referenceId" : "ref6"},
"lastname" : "Jones",
"title" : "President",
"email" : "[email protected]"
}]
}
}]
}

Example response body after successfully creating records and relationships

{
"hasErrors" : false,
"results" : [{
"referenceId" : "ref1",
"id" : "001D000000K0fXOIAZ"
},{
"referenceId" : "ref4",
"id" : "001D000000K0fXPIAZ"
},{
"referenceId" : "ref2",
"id" : "003D000000QV9n2IAD"
},{
"referenceId" : "ref3",
"id" : "003D000000QV9n3IAD"
},{
"referenceId" : "ref5",
"id" : "001D000000K0fXQIAZ"
},{
"referenceId" : "ref6",
"id" : "003D000000QV9n4IAD"
}]
}

Once the request is processed, all six records are created with the parent-child relationships specified in the request.
SEE ALSO:
SObject Tree

Create Multiple Records

While the SObject Tree resource can be used to create nested records, you can also create multiple, unrelated records of the same type.
In a single request, you can create up to two hundred records. In the request data, you supply the required and optional field values for
each record, each records type, and a reference ID for each record, and then use the POST method of the resource. The response body
will contain the IDs of the created records if the request is successful. Otherwise, the response contains only the reference ID of the record
that caused the error and the error information.
The following example creates four new accounts. The record data is provided in newrecords.json.

Examples

Create Multiple Records

Example for creating four new accounts

curl https://yourInstance.salesforce.com/services/data/v34.0/composite/tree/Account/
-H "Authorization: Bearer token -H "Content-Type: application/json" -d "@newrecords.json"

Example request body newrecords.json file for creating four new accounts
{
"records" :[{
"attributes" : {"type" : "Account",
"name" : "SampleAccount1",
"phone" : "1111111111",
"website" : "www.salesforce1.com",
"numberOfEmployees" : "100",
"industry" : "Banking"
},{
"attributes" : {"type" : "Account",
"name" : "SampleAccount2",
"phone" : "2222222222",
"website" : "www.salesforce2.com",
"numberOfEmployees" : "250",
"industry" : "Banking"
},{
"attributes" : {"type" : "Account",
"name" : "SampleAccount3",
"phone" : "3333333333",
"website" : "www.salesforce3.com",
"numberOfEmployees" : "52000",
"industry" : "Banking"
},{
"attributes" : {"type" : "Account",
"name" : "SampleAccount4",
"phone" : "4444444444",
"website" : "www.salesforce4.com",
"numberOfEmployees" : "2500",
"industry" : "Banking"
}]
}

"referenceId" : "ref1"},

"referenceId" : "ref2"},

"referenceId" : "ref3"},

"referenceId" : "ref4"},

Example response body after successfully creating records

{
"hasErrors" : false,
"results" : [{
"referenceId" : "ref1",
"id" : "001D000000K1YFjIAN"
},{
"referenceId" : "ref2",
"id" : "001D000000K1YFkIAN"
},{
"referenceId" : "ref3",
"id" : "001D000000K1YFlIAN"
},{
"referenceId" : "ref4",
"id" : "001D000000K1YFmIAN"

Examples

Create Multiple Records

}]
}

URI and Description

Versions

Lists summary information about each Salesforce version currently available, including the
version, label, and a link to each version's root.
Resources by Version

/vXX.X/

Lists available resources for the specified API version, including resource name and URI.
Limits

/vXX.X/limits/

Lists information about limits in your organization.

Describe Global

/vXX.X/sobjects/

Lists the available objects and their metadata for your organizations data.
SObject Basic Information

/vXX.X/sobjects/SObject/

Describes the individual metadata for the specified object. Can also be used to create a new
record for a given object.
SObject Describe

/vXX.X/sobjects/SObject/describe/

Completely describes the individual metadata at all levels for the specified object.
SObject Get Deleted

/vXX.X/sobjects/SObject/deleted/
?start=startDateAndTime&end=endDateAndTime

Retrieves the list of individual records that have been deleted within the given timespan for
the specified object.
SObject Get Updated

/vXX.X/sobjects/SObject/updated/
?start=startDateAndTime&end=endDateAndTime

Retrieves the list of individual records that have been updated (added or changed) within the
given timespan for the specified object.
SObject Named Layouts

/vXX.X/sobjects/Object/describe/namedLayouts/layoutName

Retrieves information about alternate named layouts for a given object.

Reference

Resource Name

URI and Description

SObject Rows

/vXX.X/sobjects/SObject/id/

Accesses records based on the specified object ID. Retrieves, updates, or deletes records. This
resource can also be used to retrieve field values.
SObject Rows by External ID

/vXX.X/sobjects/SObject/fieldName/fieldValue

Creates new records or updates existing records (upserts records) based on the value of a
specified external ID field.
SObject ApprovalLayouts

/vXX.X/sobjects/SObjectName/describe/approvalLayouts/

Returns a list of approval layouts for a specified object.

SObject CompactLayouts

/vXX.X/sobjects/Object/describe/compactLayouts/

Returns a list of compact layouts for a specific object.

Describe Layouts

/vXX.X/sobjects/global/describe/layouts/
/vXX.X/sobjects/object/describe/layouts/

Returns a list of layouts and descriptions.

SObject PlatformAction

/services/data/vXX.X/sobjects/PlatformAction

PlatformAction is a virtual read-only object. It enables you to query for actions displayed in
the UI, given a user, a context, device format, and a record ID. Examples include standard and
custom buttons, quick actions, and productivity actions.
SObject Relationships

/vXX.X/sobjects/SObject/id/relationship name

Accesses records by traversing object relationships via friendly URLs. You can retrieve, update,
or delete the record associated with the traversed relationship field. If there are multiple related
records, you can retrieve the complete set of associated records.
SObject Blob Retrieve

/vXX.X/sobjects/SObject/id/blobField

Retrieves the specified blob field from an individual record.

SObject Quick Actions

/vXX.X/sobjects/object/quickActions/
/vXX.X/sobjects/object/quickActions/{action name}
/vXX.X/sobjects/object/quickActions/{action name}/describe/
services/data/vXX.X/sobjects/object/quickActions/{action
name}/defaultValues/
vXX.X/sobjects/object/quickActions/{action
name}/defaultValues/{parent id}

Returns a list of actions and their details.

SObject Suggested Articles

vXX.X/sobjects/SObject/suggestedArticles?language=article
language&subject=subject&description=description

Reference

Resource Name

URI and Description

vXX.X/sobjects/SObject/ID/suggestedArticles?language=article
language

Returns a list of suggested Salesforce Knowledge articles for a case, work order, or work order
line item.
SObject User Password

/vXX.X/sobjects/User/user id/password
/vXX.X/sobjects/SelfServiceUser/self service user id/password

Set, reset, or get information about a user password.

AppMenu

/vXX.X/appMenu/AppSwitcher/
/vXX.X/appMenu/Salesforce1/

Returns a list of items in either the Salesforce app drop-down menu or the Salesforce1
navigation menu.
Compact Layouts

/vXX.X/compactLayouts?q=object list

Returns a list of compact layouts for multiple objects.

FlexiPage

/vXX.X/flexiPage/ID of Lightning Page

Returns a list of Lightning Pages and their details. Information returned includes Lightning
Page regions, the components within each region, and each components properties, as well
as any associated QuickActions.
Invocable Actions

/vXX.X/actions/standard
/vXX.X/actions/custom

esU
onsitca
ot
dda
erm
o
ytoinuailnfct
ot
ruoy
on.sicatapipl
esohC
m
or f
drndats
o,nsitca
hcus
sa
ngitpos
ot
retCtha
ro
gnidnes
, lm
eia
ro
etaerc

Reference

Resource Name

URI and Description

onsitca
desab
no
ruoy
sm
ocynap
.dsen

Parameterized Search

/vXX.X/parameterizedSearch/?q=search string

Executes a simple RESTful search using parameters instead of a SOSL clause. Indicate parameters
in a URL in the GET method. Or, use POST for more complex JSON searches.
Process Approvals

/vXX.X/process/approvals/

Returns a list of all approval processes. Can also be used to submit a particular record if that
entity supports an approval process and one has already been defined. Records can be
approved and rejected if the current user is an assigned approver.
Process Rules

/vXX.X/process/rules/

Returns a list of all active workflow rules. If a rule has actions, the actions will be listed under
the rule. Can also be used to trigger all workflow rules that are associated with a specified
record. The actions for a rule are only fired if the rules criteria is met.
Query

/vXX.X/query/?q=soql

Executes the specified SOQL query.

QueryAll

/vXX.X/queryAll/?q=soql

Executes the specified SOQL query. Results can include deleted, merged and archived records.
Quick Actions

/vXX.X/quickActions/

Return a list of global quick actions and their types, as well as custom fields and objects that
appear in the Chatter feed.
Recently Viewed Items

/vXX.X/recent

Gets the most recently accessed items that were viewed or referenced by the current user.
Relevant Items

/vXX.X/sobjects/relevantItems

Gets the current users most relevant items. Relevant items include records for objects in the
users global search scope and also most recently used (MRU) objects.
Search

/vXX.X/search/?q=sosl

Executes the specified SOSL search. The search string must be URL-encoded.
Search Scope and Order

/vXX.X/search/scopeOrder

Reference

Versions

Resource Name

URI and Description

Search Result Layouts

/vXX.X/searchlayout/?q=Comma delimited object list

Returns search result layout information for the objects in the query string. For each object,
this call returns the list of fields displayed on the search results page as columns, the number
of rows displayed on the first page, and the label used on the search results page.
Search Suggested Article Title Matches /vXX.X/search/suggestTitleMatches?q=search
string&language=article language&publishStatus=article
publication status

Returns a list of Salesforce Knowledge article titles that match the users search query string.
Provides a shortcut to navigate directly to likely relevant articles before the user performs a
search.
Search Suggested Queries

vXX.X/search/suggestSearchQueries?q=search
string&language=language of query

Returns a list of suggested searches based on the users query string text matching searches
that other users have performed in Salesforce Knowledge. Provides a way to improve search
effectiveness, before the user performs a search.
Tabs

/vXX.X/tabs

Returns a list of all tabsincluding Lightning Page tabsavailable to the current user,
regardless of whether the user has chosen to hide tabs via the All Tabs (+) tab customization
feature.
Themes

/vXX.X/theme

Gets the list of icons and colors used by themes in the Salesforce application.

Composite Resources
Resource Name URI

Description

Batch

/vXX.X/composite/batch

Executes up to 25 subrequests in a single request.

SObject Tree

/vXX.X/composite/tree

Creates one or more sObject trees with root

records of the specified type. An sObject tree is a
collection of nested, parent-child records with a
single root record.

Versions
Lists summary information about each Salesforce version currently available, including the version, label, and a link to each version's
root.

Reference

Resources by Version

URI
/

Formats
JSON, XML
HTTP Method
GET
Authentication
none
Parameters
none
Example
See List Available REST API Versions on page 34.

Resources by Version
Lists available resources for the specified API version, including resource name and URI.
URI
/vXX.X/

Formats
JSON, XML
HTTP Method
GET
Authentication
Authorization: Bearer token

Parameters
none
Example
See List Available REST Resources. on page 37

Limits
Lists information about limits in your organization. This resource is available in REST API version 29.0 and later for API users with the View
Setup and Configuration permission. The resource returns these limits:
Daily API calls
Daily Batch Apex and future method executions
Daily Bulk API calls
Daily Streaming API events
Streaming API concurrent clients
Daily generic streaming events (if generic streaming is enabled for your organization)
Daily number of mass emails that are sent to external email addresses by using Apex or Force.com APIs
Daily number of single emails that are sent to external email addresses by using Apex or Force.com APIs

Reference

Describe Global

Concurrent REST API requests for results of asynchronous report runs

Concurrent synchronous report runs via REST API
Hourly asynchronous report runs via REST API
Hourly synchronous report runs via REST API
Hourly dashboard refreshes via REST API
Hourly REST API requests for dashboard results
Hourly dashboard status requests via REST API
Daily workflow emails
Hourly workflow time triggers
Hourly OData callouts
The resource also returns these limits if the API user has the Manage Users permission.
Data storage (MB)
File storage (MB)
URI
/vXX.X/limits/

Formats
JSON, XML
HTTP Method
GET
Authentication
Authorization: Bearer token

Example
See List Organization Limits.

Describe Global
Lists the available objects and their metadata for your organizations data. In addition, it provides the organization encoding, as well as
the maximum batch size permitted in queries. For more information on encoding, see Internationalization and Character Sets.
You can use the If-Modified-Since header with this resource, with the date format EEE, dd MMM yyyy HH:mm:ss
z. When using this header, if no available objects metadata has changed since the provided date, a 304 Not Modified status
code is returned with no response body.
URI
/vXX.X/sobjects/

Formats
JSON, XML
HTTP Method
GET
Authentication
Authorization: Bearer token

Parameters
none required

Reference

SObject Basic Information

Example
See Get a List of Objects on page 38.
Error responses
See Status Codes and Error Responses on page 210.

SObject Basic Information

Describes the individual metadata for the specified object. Can also be used to create a new record for a given object. For example, this
can be used to retrieve the metadata for the Account object using the GET method, or create a new Account object using the POST
method.
URI
/vXX.X/sobjects/SObjectName/

Formats
JSON, XML
HTTP Method
GET, POST
Authentication
Authorization: Bearer token

Parameters
none required
Examples
For an example of retrieving metadata for an object, see Retrieve Metadata for an Object on page 40.
For an example of creating a new record using POST, see Create a Record on page 43.
For an example of create a new record along with providing blob data for the record, see Insert or Update Blob Data on page
57.

SObject Describe
Completely describes the individual metadata at all levels for the specified object. For example, this can be used to retrieve the fields,
URLs, and child relationships for the Account object.
The If-Modified-Since header can be used with this resource, with a date format of EEE, dd MMM yyyy HH:mm:ss
z. When this header is used, if the object metadata has not changed since the provided date, a 304 Not Modified status code
is returned, with no response body.
URI
/vXX.X/sobjects/SObjectName/describe/

Formats
JSON, XML
HTTP Method
GET
Authentication
Authorization: Bearer token

100

Reference

SObject Get Deleted

Parameters
none required
Example
See Get Field and Other Metadata for an Object on page 40. For an example that uses the If-Modified-Since HTTP header,
see Get Object Metadata Changes on page 42.

SObject Get Deleted

Retrieves the list of individual records that have been deleted within the given timespan for the specified object. SObject Get Deleted
is available in API version 29.0 and later.
This resource is commonly used in data replication applications. Note the following considerations:
Deleted records are written to a delete log which this resource accesses. A background process that runs every two hours purges
records that have been in an organization's delete log for more than two hours if the number of records is above a certain limit.
Starting with the oldest records, the process purges delete log entries until the delete log is back below the limit. This is done to
protect Salesforce from performance issues related to massive delete logs
Information on deleted records are returned only if the current session user has access to them.
Results are returned for no more than 15 days previous to the day the call is executed (or earlier if an administrator has purged the
Recycle Bin).
See Data Replication in the SOAP API Developer's Guide for additional details on data replication and data replication limits.
URI
/vXX.X/sobjects/SObjectName/deleted/?start=startDateAndTime&end=endDateAndTime

Formats
JSON, XML
HTTP Method
GET
Authentication
Authorization: Bearer token

Parameters
Parameter

Description

start

Starting date/time (Coordinated Universal Time (UTC)not local timezone) of the

timespan for which to retrieve the data. The API ignores the seconds portion of the
specified dateTime value (for example, 12:30:15 is interpreted as 12:30:00 UTC). The
date and time should be provided in ISO 8601 format:
YYYY-MM-DDThh:mm:ss+hh:mm. The date/time value for start must
chronologically precede end. This parameter should be URL-encoded.

end

Ending date/time (Coordinated Universal Time (UTC)not local timezone) of the

timespan for which to retrieve the data. The API ignores the seconds portion of the
specified dateTime value (for example, 12:35:15 is interpreted as 12:35:00 UTC). The
date and time should be provided in ISO 8601 format:
YYYY-MM-DDThh:mm:ss+hh:mm. This parameter should be URL-encoded

101

Reference

SObject Get Updated

Response format
Property

Type

Description

deletedRecords

array

Array of deleted records that satisfy the start and end dates specified in the
request. Each entry contains the record ID and the date and time the record
was deleted in ISO 8601 format, using Coordinated Universal Time (UTC)
timezone.

earliestDateAvailable String

ISO 8601 format timestamp (Coordinated Universal Time (UTC)not local

timezone) of the last physically deleted object.

String

ISO 8601 format timestamp (Coordinated Universal Time (UTC)not local

time zone) of the last date covered in the request.

latestDateCovered

Example
For an example of getting a list of deleted items, see Get a List of Deleted Records Within a Given Timeframe on page 60.

SObject Get Updated

Retrieves the list of individual records that have been updated (added or changed) within the given timespan for the specified object.
SObject Get Updated is available in API version 29.0 and later.
This resource is commonly used in data replication applications. Note the following considerations:
Results are returned for no more than 30 days previous to the day the call is executed.
Your client application can replicate any objects to which it has sufficient permissions. For example, to replicate all data for your
organization, your client application must be logged in with View All Data access rights to the specified object. Similarly, the objects
must be within your sharing rules.
There is a limit of 600,000 IDs returned from this resource. If more than 600,000 IDs would be returned, EXCEEDED_ID_LIMIT is
returned. You can correct the error by choosing start and end dates that are closer together.
See Data Replication in the SOAP API Developer's Guide for additional details on data replication and data replication limits.
URI
/vXX.X/sobjects/SObjectName/updated/?start=startDateAndTime&end=endDateAndTime

Formats
JSON, XML
HTTP Method
GET
Authentication
Authorization: Bearer token

Parameters
Parameter

Description

start

Starting date/time (Coordinated Universal Time (UTC) time zonenot local timezone)
of the timespan for which to retrieve the data. The API ignores the seconds portion of
the specified dateTime value (for example, 12:30:15 is interpreted as 12:30:00 UTC).

102

Reference

SObject Named Layouts

Parameter

Description
The date and time should be provided in ISO 8601 format:
YYYY-MM-DDThh:mm:ss+hh:mm. The date/time value for start must
chronologically precede end. This parameter should be URL-encoded
Ending date/time (Coordinated Universal Time (UTC) time zonenot local timezone)
of the timespan for which to retrieve the data. The API ignores the seconds portion of
the specified dateTime value (for example, 12:35:15 is interpreted as 12:35:00 UTC).
The date and time should be provided in ISO 8601 format:
YYYY-MM-DDThh:mm:ss+hh:mm. This parameter should be URL-encoded

end

Response format
Property

Type

Description

ids

array

Array of updated records that satisfy the start and end dates specified in the
request. Each entry contains the record ID.

latestDateCovered

String

ISO 8601 format timestamp (Coordinated Universal Time (UTC)not local

time zone) of the last date covered in the request.

Example
For an example of getting a list of updated deleted items, see Get a List of Updated Records Within a Given Timeframe on page 61.

SObject Named Layouts

Retrieves information about alternate named layouts for a given object.

Syntax
URI
/vXX.X/sobjects/Object/describe/namedLayouts/layoutName

Available since release

31.0
Formats
JSON, XML
HTTP methods
GET
Authentication
Authorization: Bearer token

Request body
None

103

Reference

SObject Rows

Example
/services/data/v31.0/sobjects/User/describe/namedLayouts/UserAlt

This example retrieves information on the UserAlt named layout for User.

Usage
Use this resource to get information on a named layout for a given object. You must provide a valid named layout name as part of the
resource URI.
To get a list of named layouts for a given object, use the SObject Describe resource and look for the namedLayoutInfos field in the
response body.

SObject Rows
Accesses records based on the specified object ID. Retrieves, updates, or deletes records. This resource can also be used to retrieve field
values. Use the GET method to retrieve records or fields, the DELETE method to delete records, and the PATCH method to update records.
To create new records, use the SObject Basic Information resource.
URI
/vXX.X/sobjects/SObjectName/id/

Formats
JSON, XML
HTTP Method
GET, PATCH, DELETE
Authentication
Authorization: Bearer token

Parameters
Parameter

Description

fields

Optional list of fields used to return values for.

Usage
This resource can be used with external objects in API version 32.0 and later.
External objects that are associated with non-high-data-volume external data sources use the 18-character Salesforce ID for the
id. Otherwise, external objects use the External ID standard field of the external object for the id.
Examples
For examples of retrieving field values using GET, see:
Get Field Values from a Standard Object Record on page 45
Get Field Values from an External Object Record by Using the External ID Standard Field on page 46
Get Field Values from an External Object Record by Using the Salesforce ID on page 46
For an example of updating a record using PATCH, see Update a Record on page 44.
For an example of deleting a record using DELETE, see Delete a Record on page 45.

104

Reference

SObject Rows by External ID

For an example of updating the blob data for an object, see Insert or Update Blob Data on page 57.

SObject Rows by External ID

Creates new records or updates existing records (upserts records) based on the value of a specified external ID field.
If the specified value doesn't exist, a new record is created.
If a record does exist with that value, the field values specified in the request body are updated.
If the value is not unique, the REST API returns a 300 response with the list of matching records.
Note: Do not specify Id or an external ID field in the request body or an error is generated.
URI
/vXX.X/sobjects/SObjectName/fieldName/fieldValue

Formats
JSON, XML
HTTP Method
HEAD, GET, PATCH, DELETE, POST (see Usage section)
Authentication
Authorization: Bearer token

Parameters
None
Usage
As a special case, in API version 37.0 and later, you can use this resource to create a record by POSTing to
/vXX.X/sobjects/SObjectName/Id. This pattern represents the use of Id as the specified external ID field and null
as the value. Its useful when youre writing code to upsert multiple records by different external IDs and you dont want to request
a separate resource.
Examples
For an example of retrieving a record based on an external ID, see Retrieve a Record Using an External ID on page 47.
For examples of creating and updating records based on external IDs, see Insert or Update (Upsert) a Record Using an External
ID on page 47.

SObject Blob Retrieve

Retrieves the specified blob field from an individual record.
URI
/vXX.X/sobjects/SObjectName/id/blobField

Formats
Because blob fields contain binary data, you can't use JSON or XML to retrieve this data.
HTTP Method
GET
Authentication
Authorization: Bearer token

105

Reference

SObject ApprovalLayouts

Parameters
none required
Example
For an example of retrieving the blob data from an Attachment or Document, see Get Attachment Content from a Record on page
56.
Error responses
See Status Codes and Error Responses on page 210.

SObject ApprovalLayouts
Returns a list of approval layouts for a specified object. Specify a particular approval process name to limit the return value to one specific
approval layout. This resource is available in REST API version 30.0 and later.

Syntax
URI
To get an approval layout description for a specified object, use
/vXX.X/sobjects/SObjectName/describe/approvalLayouts/

To get an approval layout description for a particular approval process, use

/vXX.X/sobjects/SObjectName/describe/approvalLayouts/approvalProcessName

Formats
JSON, XML
HTTP methods
HEAD, GET
Authentication
Authorization: Bearer token

Request parameters
None required

Example
Getting all approval layouts for an sObject
curl
https://yourInstance.salesforce.com/services/data/v30.0/sobjects/Account/describe/approvalLayouts/
-H "Authorization: Bearer token"

Example JSON Response body

{
"approvalLayouts" : [ {
"id" : "04aD00000008Py9IAE",
"label" : "MyApprovalProcessName",
"layoutItems" : [...],
"name" : "MyApprovalProcessName"
}, {
"id" : "04aD00000008Q0KIAU",

106

Reference

SObject CompactLayouts

"label" : "Process1",
"layoutItems" : [...],
"name" : "Process1"
} ]
}

If you havent defined any approval layouts for an object, the response is {"approvalLayouts" : [ ]}.
Getting the approval layout for a particular approval process
curl
https://yourInstance.salesforce.com/services/data/v30.0/sobjects/Account/describe/approvalLayouts/MyApprovalProcessName
-H "Authorization: Bearer token"

Example JSON Response body

{
"approvalLayouts" : [ {
"id" : "04aD00000008Py9IAE",
"label" : "MyApprovalProcessName",
"layoutItems" : [...],
"name" : "MyApprovalProcessName"
} ]
}

SObject CompactLayouts
Returns a list of compact layouts for a specific object. This resource is available in REST API version 29.0 and later.

Syntax
URI
For a compact layout description for a specific object, use /vXX.X/sobjects/Object/describe/compactLayouts/
Formats
JSON, XML
HTTP methods
HEAD, GET
Authentication
Authorization: Bearer token

Request parameters
None required

Example
Getting compact layouts
/services/data/v29.0/sobjects/Account/describe/compactLayouts

107

Reference

SObject CompactLayouts

Example JSON Response body

This sample JSON response is for compact layouts created on the Account object. In this example, only one custom compact layout
was created for Account. The custom compact layout is assigned as the primary compact layout for the object, and it contains two
fields: Account Name and Phone.
{
"compactLayouts" : [ {
"actions" : [ {
"custom" : false,
"icons" : null,
"label" : "Call",
"name" : "CallHighlightAction"
}, {
"custom" : false,
"icons" : null,
"label" : "Send Email",
"name" : "EmailHighlightAction"
}, {
"custom" : false,
"icons" : null,
"label" : "Map",
"name" : "MapHighlightAction"
}, {
"custom" : false,
"icons" : null,
"label" : "Read News",
"name" : "NewsHighlightAction"
}, {
"custom" : false,
"icons" : null,
"label" : "View Website",
"name" : "WebsiteHighlightAction"
} ],
"fieldItems" : [ {
"editable" : false,
"label" : "Account Name",
"layoutComponents" : [ {
"components" : [ ],
"details" : {
"autoNumber" : false,
"byteLength" : 765,
"calculated" : false,
"calculatedFormula" : null,
"cascadeDelete" : false,
"caseSensitive" : false,
"controllerName" : null,
"createable" : true,
"custom" : false,
"defaultValue" : null,
"defaultValueFormula" : null,
"defaultedOnCreate" : false,
"dependentPicklist" : false,
"deprecatedAndHidden" : false,

108

Reference

SObject CompactLayouts

"digits" : 0,
"displayLocationInDecimal" : false,
"externalId" : false,
"extraTypeInfo" : null,
"filterable" : true,
"groupable" : true,
"htmlFormatted" : false,
"idLookup" : false,
"inlineHelpText" : null,
"label" : "Account Name",
"length" : 255,
"mask" : null,
"maskType" : null,
"name" : "Name",
"nameField" : true,
"namePointing" : false,
"nillable" : false,
"permissionable" : false,
"picklistValues" : [ ],
"precision" : 0,
"queryByDistance" : false,
"referenceTo" : [ ],
"relationshipName" : null,
"relationshipOrder" : null,
"restrictedDelete" : false,
"restrictedPicklist" : false,
"scale" : 0,
"soapType" : "xsd:string",
"sortable" : true,
"type" : "string",
"unique" : false,
"updateable" : true,
"writeRequiresMasterRead" : false
},
"displayLines" : 1,
"tabOrder" : 2,
"type" : "Field",
"value" : "Name"
} ],
"placeholder" : false,
"required" : false
}, {
"editable" : false,
"label" : "Phone",
"layoutComponents" : [ {
"components" : [ ],
"details" : {
"autoNumber" : false,
"byteLength" : 120,
"calculated" : false,
"calculatedFormula" : null,
"cascadeDelete" : false,
"caseSensitive" : false,
"controllerName" : null,

109

Reference

SObject CompactLayouts

"createable" : true,
"custom" : false,
"defaultValue" : null,
"defaultValueFormula" : null,
"defaultedOnCreate" : false,
"dependentPicklist" : false,
"deprecatedAndHidden" : false,
"digits" : 0,
"displayLocationInDecimal" : false,
"externalId" : false,
"extraTypeInfo" : null,
"filterable" : true,
"groupable" : true,
"htmlFormatted" : false,
"idLookup" : false,
"inlineHelpText" : null,
"label" : "Account Phone",
"length" : 40,
"mask" : null,
"maskType" : null,
"name" : "Phone",
"nameField" : false,
"namePointing" : false,
"nillable" : true,
"permissionable" : true,
"picklistValues" : [ ],
"precision" : 0,
"queryByDistance" : false,
"referenceTo" : [ ],
"relationshipName" : null,
"relationshipOrder" : null,
"restrictedDelete" : false,
"restrictedPicklist" : false,
"scale" : 0,
"soapType" : "xsd:string",
"sortable" : true,
"type" : "phone",
"unique" : false,
"updateable" : true,
"writeRequiresMasterRead" : false
},
"displayLines" : 1,
"tabOrder" : 3,
"type" : "Field",
"value" : "Phone"
} ],
"placeholder" : false,
"required" : false
} ],
"id" : "0AHD000000000AbOAI",
"imageItems" : [ {
"editable" : false,
"label" : "Photo URL",
"layoutComponents" : [ {

110

Reference

SObject CompactLayouts

"components" : [ ],
"details" : {
"autoNumber" : false,
"byteLength" : 765,
"calculated" : false,
"calculatedFormula" : null,
"cascadeDelete" : false,
"caseSensitive" : false,
"controllerName" : null,
"createable" : false,
"custom" : false,
"defaultValue" : null,
"defaultValueFormula" : null,
"defaultedOnCreate" : false,
"dependentPicklist" : false,
"deprecatedAndHidden" : false,
"digits" : 0,
"displayLocationInDecimal" : false,
"externalId" : false,
"extraTypeInfo" : "imageurl",
"filterable" : true,
"groupable" : true,
"htmlFormatted" : false,
"idLookup" : false,
"inlineHelpText" : null,
"label" : "Photo URL",
"length" : 255,
"mask" : null,
"maskType" : null,
"name" : "PhotoUrl",
"nameField" : false,
"namePointing" : false,
"nillable" : true,
"permissionable" : false,
"picklistValues" : [ ],
"precision" : 0,
"queryByDistance" : false,
"referenceTo" : [ ],
"relationshipName" : null,
"relationshipOrder" : null,
"restrictedDelete" : false,
"restrictedPicklist" : false,
"scale" : 0,
"soapType" :
"xsd:string",
"sortable" : true,
"type" : "url",
"unique" : false,
"updateable" : false,
"writeRequiresMasterRead" : false
},
"displayLines" : 1,
"tabOrder" : 1,
"type" : "Field",

111

Reference

Describe Layouts

"value" : "PhotoUrl"
} ],
"placeholder" : false,
"required" : false
} ],
"label" : "Custom Account Compact Layout",
"name" : "Custom_Account_Compact_Layout"
} ],
"defaultCompactLayoutId" : "0AHD000000000AbOAI",
"recordTypeCompactLayoutMappings" : [ {
"available" : true,
"compactLayoutId" : "0AHD000000000AbOAI",
"compactLayoutName" : "Custom_Account_Compact_Layout",
"recordTypeId" : "012000000000000AAA",
"recordTypeName" : "Master",
"urls" : {
"compactLayout" :
"/services/data/v31.0/sobjects/Account/describe/compactLayouts/012000000000000AAA"
}
} ],
"urls" : {
"primary" : "/services/data/v31.0/sobjects/Account/describe/compactLayouts/primary"
}
}

If you havent defined any compact layouts for an object, the compactLayoutId returns as Null.

Describe Layouts
Returns a list of layouts and descriptions. The list of fields and the layout name are returned.
URI
To return descriptions of global publisher layouts, the URI is: /vXX.X/sobjects/Global/describe/layouts/
For a layout description for a specific object, use /vXX.X/sobjects/Object/describe/layouts/
Formats
JSON, XML
HTTP Method
HEAD, GET
Authentication
Authorization: Bearer token

Parameters
None required
Example for getting global publisher layouts
curl
https://yourInstance.salesforce.com/services/data/v35.0/sobjects/Global/describe/layouts/
-H "Authorization: Bearer token"

112

Reference

Describe Layouts

Example JSON Response body contactlayout.json file

[ { "name" : "contactlayout",
"searchColumns" : [ { "field" : "Account.Name",
"format" : null,
"label" : "Account Name",
"name" : "Name"
},
{ "field" : "Account.Site",
"format" : null,
"label" : "Account Site",
"name" : "Site"
},
{ "field" : "Account.Phone",
"format" : null,
"label" : "Phone",
"name" : "Phone"
},
{ "field" : "User.Alias",
"format" : null,
"label" : "Account Owner Alias",
"name" : "Owner.Alias"
}
]
},
{ "label" : "Search Results",
"limitRows" : 25,
"searchColumns" : [ { "field" : "Contact.Name",
"format" : null,
"label" : "Name",
"name" : "Name"
},
{ "field" : "Account.Name",
"format" : null,
"label" : "Account Name",
"name" : "Account.Name"
},
{ "field" : "Account.Site",
"format" : null,
"label" : "Account Site",
"name" : "Account.Site"
},
{ "field" : "Contact.Phone",
"format" : null,
"label" : "Phone",
"name" : "Phone"
},
{ "field" : "Contact.Email",
"format" : null,
"label" : "Email",
"name" : "Email"
},
{ "field" : "User.Alias",
"format" : null,

113

Reference

SObject PlatformAction

"label" : "Contact Owner Alias",

"name" : "Owner.Alias"
}
]
},
{ "label" : "Search Results",
"limitRows" : 25,
"searchColumns" : [ { "field" : "Lead.Name",
"format" : null,
"label" : "Name",
"name" : "Name"
},
{ "field" : "Lead.Title",
"format" : null,
"label" : "Title",
"name" : "Title"
},
{ "field" : "Lead.Phone",
"format" : null,
"label" : "Phone",
"name" : "Phone"
},
{ "field" : "Lead.Company",
"format" : null,
"label" : "Company",
"name" : "Company"
},
{ "field" : "Lead.Email",
"format" : null,
"label" : "Email",
"name" : "Email"
},
{ "field" : "Lead.Status",
"format" : null,
"label" : "Lead Status",
"name" : "toLabel(Status)"
},
{ "field" : "Name.Alias",
"format" : null,
"label" : "Owner Alias",
"name" : "Owner.Alias"
}
]
},
]

SObject PlatformAction
PlatformAction is a virtual read-only object. It enables you to query for actions displayed in the UI, given a user, a context, device format,
and a record ID. Examples include standard and custom buttons, quick actions, and productivity actions.
Returns the description of the PlatformAction.

114

Reference

SObject Quick Actions

Syntax
URI
Use /services/data/vXX.X/sobjects/PlatformAction
Available since release
This resource is available in API version 33.0 and later.
Formats
JSON, XML
HTTP methods
GET
Authentication
Authorization: Bearer token

Request body
None.

Usage
The only thing you can do with this resource is Query it.

SObject Quick Actions

Returns a list of actions and their details. This resource is available in REST API version 28.0 and later. When working with actions, also
refer to Quick Actions.
URI
To return a specific objects actions as well as global actions, use: /vXX.X/sobjects/object/quickActions/
To return a specific action, use /vXX.X/sobjects/object/quickActions/{action name}
To return a specific actions descriptive detail, use /vXX.X/sobjects/object/quickActions/{action
name}/describe/

vXX.X/sobjects/SObject/ID/suggestedArticles?language=article language

Available since release

30.0
Formats
JSON, XML
HTTP methods
GET
Authentication
Authorization: Bearer token

Request body
None required
Request parameters
Parameter

Description

articleTypes

Optional. Three-character ID prefixes indicating the desired article types. You can specify
multiple values for this parameter in a single REST call, by repeating the parameter
name for each value. For example, articleTypes=ka0&articleTypes=ka1.

Required. Language that the article is written in.

limit

Optional. Specifies the maximum number of suggested articles to return.

publishStatus

Optional. The articles publication status. Valid values:

DraftNot published
OnlinePublished in Salesforce Knowledge
Archived

118

Reference

SObject User Password

Parameter

Description

subject

Text of the subject. Valid only for new records without an existing ID and required if
description is null. Article suggestions are based on common keywords in the
subject, description, or both.

topics

Optional. The topic of returned articles. For example:

topics=outlook&topics=email.

validationStatus

Optional. The validation status of returned articles.

Example for getting suggested articles for a case thats being created
curl
https://yourInstance.salesforce.com/services/data/v30.0/sobjects/Case/suggestedArticles?
language=en_US&subject=orange+banana&articleTypes=ka0&articleTypes=ka1
-H "Authorization: Bearer token"

Example JSON response body

[ {
"attributes" : {
"type" : "KnowledgeArticleVersion",
"url" : "/services/data/v30.0/sobjects/KnowledgeArticleVersion/ka0D00000004CcQ"
"Id" : "ka0D00000004CcQ"
}, {
"attributes" : {
"type" : "KnowledgeArticleVersion",
"url" : "/services/data/v30.0/sobjects/KnowledgeArticleVersion/ka0D00000004CXo"
},
"Id" : "ka0D00000004CXo"
} ]

Usage
Salesforce Knowledge must be enabled in your organization. The user must have the View Articles permission enabled. The articles
suggested include only the articles the user can access, based on the data categories and article types the user has permissions to view.
Articles are suggested based on a relevance algorithm. The suggestedArticles resource is designed to get the IDs of articles
relevant to a case, work order, or work order line item. Its intended to be used with other services that then use the IDs to get article
data for display.

SObject User Password

Set, reset, or get information about a user password. This resource is available in REST API version 24.0 and later.
URI
/vXX.X/sobjects/User/user ID/password

For managing passwords for self-service users, the URI is:

119

Reference

AppMenu

/vXX.X/sobjects/SelfServiceUser/self service user ID/password

Formats
JSON, XML
HTTP Method
HEAD, GET, POST, DELETE
Authentication
Authorization: Bearer token

Parameters
None required
Example
For examples of getting password information, setting a password, and resetting a password, see Manage User Passwords on page
76.
Considerations
If the session does not have permission to access the user information, an INSUFFICIENT_ACCESS error will be returned.
When using this resource to set a new password, the new password must conform to the password policies for the organization,
otherwise you will get an INVALID_NEW_PASSWORD error response.
You can only set one password per request.
When you use the DELETE method of this resource, Salesforce will reset the user password to an auto-generated password,
which will be returned in the response.

AppMenu
Returns a list of items in either the Salesforce app drop-down menu or the Salesforce1 navigation menu.

Syntax
URI
To return a list of the Salesforce app drop-down menu items, the URI is: /vXX.X/appMenu/AppSwitcher/
To return a list of the Salesforce1 navigation menu items, the URI is: /vXX.X/appMenu/Salesforce1/
Available since release
29.0
Formats
JSON, XML
HTTP methods
GET, HEAD
Authentication
Authorization: Bearer token

Request body
None
Request parameters
None required

120

Reference

AppMenu

Example
Getting appMenu types
curl https://yourInstance.salesforce.com/services/data/v29.0/appMenu/ -H "Authorization:
Bearer token"

Example response body for /vXX.X/appMenu/AppSwitcher/

{
"appMenuItems" : [ {
"type" : "Tabset",
"content" : null,
"icons" : null,
"colors" : null,
"label" : "Sales",
"url" : "/home/home.jsp?tsid=02uxx00000056Sq"
}, {
"type" : "Tabset",
"content" : null,
"icons" : null,
"colors" : null,
"label" : "Call Center",
"url" : "/home/home.jsp?tsid=02uxx00000056Sr"
}, {
"type" : "Tabset",
"content" : null,
"icons" : null,
"colors" : null,
"label" : "Marketing",
"url" : "/home/home.jsp?tsid=02uxx00000056St"
}, {
"type" : "Tabset",
"content" : null,
"icons" : null,
"colors" : null,
"label" : "Salesforce Chatter",
"url" : "/home/home.jsp?tsid=02uxx00000056Su"
}, {
"type" : "Tabset",
"content" : null,
"icons" : null,
"colors" : null,
"label" : "Community",
"url" : "/home/home.jsp?tsid=02uxx00000056Sw"
}, {
"type" : "Tabset",
"content" : null,
"icons" : null,
"colors" : null,
"label" : "App Launcher",
"url" : "/app/mgmt/applauncher/appLauncher.apexp?tsid=02uxx00000056Sx"
} ]
}

121

Reference

AppMenu

Example response body for /vXX.X/appMenu/Salesforce1/

{
"appMenuItems" : [ {
"type" : "Standard.Search",
"content" : null,
"icons" : null,
"colors" : null,
"label" : "Smart Search Items",
"url" : "/search"
}, {
"type" : "Standard.MyDay",
"content" : null,
"icons" : null,
"colors" : null,
"label" : "Today",
"url" : "/myDay"
}, {
"type" : "Standard.Tasks",
"content" : null,
"icons" : null,
"colors" : null,
"label" : "Tasks",
"url" : "/tasks"
}, {
"type" : "Standard.Dashboards",
"content" : null,
"icons" : null,
"colors" : null,
"label" : "Dashboards",
"url" : "/dashboards"
}, {
"type" : "Tab.flexiPage",
"content" : "MySampleFlexiPage",
"icons" : [ {
"contentType" : "image/png",
"width" : 32,
"height" : 32,
"theme" : "theme3",
"url" : "http://myorg.com/img/icon/custom51_100/bell32.png"
}, {
"contentType" : "image/png",
"width" : 16,
"height" : 16,
"theme" : "theme3",
"url" : "http://myorg.com/img/icon/custom51_100/bell16.png"
}, {
"contentType" : "image/svg+xml",
"width" : 0,
"height" : 0,
"theme" : "theme4",
"url" : "http://myorg.com/img/icon/t4/custom/custom53.svg"
}, {
"contentType" : "image/png",

122

Reference

AppMenu

"width" : 60,
"height" : 60,
"theme" : "theme4",
"url" : "http://myorg.com/img/icon/t4/custom/custom53_60.png"
}, {
"contentType" : "image/png",
"width" : 120,
"height" : 120,
"theme" : "theme4",
"url" : "http://myorg.com/img/icon/t4/custom/custom53_120.png"
} ],
"colors" : [ {
"context" : "primary",
"color" : "FC4F59",
"theme" : "theme4"
}, {
"context" : "primary",
"color" : "FC4F59",
"theme" : "theme3"
} ],
"label" : "My App Home Page",
"url" : "/servlet/servlet.Integration?lid=01rxx0000000Vsd&ic=1"
}, {
"type" : "Tab.apexPage",
"content" : "/apex/myapexpage",
"icons" : [ {
"contentType" : "image/png",
"width" : 32,
"height" : 32,
"theme" : "theme3",
"url" : "http://myorg.com/img/icon/cash32.png"
}, {
"contentType" : "image/png",
"width" : 16,
"height" : 16,
"theme" : "theme3",
"url" : "http://myorg.com/img/icon/cash16.png"
}, {
"contentType" : "image/svg+xml",
"width" : 0,
"height" : 0,
"theme" : "theme4",
"url" : "http://myorg.com/img/icon/t4/custom/custom41.svg"
}, {
"contentType" : "image/png",
"width" : 60,
"height" : 60,
"theme" : "theme4",
"url" : "http://myorg.com/img/icon/t4/custom/custom41_60.png"
}, {
"contentType" : "image/png",
"width" : 120,
"height" : 120,
"theme" : "theme4",

123

Reference

Compact Layouts

"url" : "http://myorg.com/img/icon/t4/custom/custom41_120.png"
} ],
"colors" : [ {
"context" : "primary",
"color" : "3D8D8D",
"theme" : "theme4"
}, {
"context" : "primary",
"color" : "3D8D8D",
"theme" : "theme3"
} ],
"label" : "label",
"url" : "/servlet/servlet.Integration?lid=01rxx0000000Vyb&ic=1"
} ]
}

Compact Layouts
Returns a list of compact layouts for multiple objects. This resource is available in REST API version 31.0 and later.
This resource returns the primary compact layout for a set of objects. The set of objects is specified using a query parameter. Up to 100
objects can be queried at once.
Note: PersonAccount isnt supported for bulk queries. If you want to get the primary compact layout for PersonAccount, get it
directly from
/services/data/v31.0/sobjects/Account/describe/compactLayouts/primaryPersonAccount.

Syntax
URI
/vXX.X/compactLayouts?q=object list

Available since release

31.0
Formats
JSON, XML
HTTP methods
GET
Authentication
Authorization: Bearer token

Request parameters
Parameter

Description

A comma-delimited list of objects. The primary compact layout for each object in this
list will be returned in the response of this resource.

124

Reference

Compact Layouts

Example
Request for getting compact layouts for multiple objects
/services/data/v31.0/compactLayouts?q=Account,Contact,CustomObj__c

Response for compact layouts for multiple objects

{
"Account" : {
"actions" : [ {
"behavior" : null,
"content" : null,
"contentSource" : null,
"custom" : false,
"encoding" : null,
"height" : null,
"icons" : null,
"label" : "Call",
"menubar" : false,
"name" : "CallHighlightAction",
"overridden" : false,
"resizeable" : false,
"scrollbars" : false,
"showsLocation" : false,
"showsStatus" : false,
"toolbar" : false,
"url" : null,
"width" : null,
"windowPosition" : null
},
...
"id" : "0AHD000000000AbOAI",
"label" : "Custom Account Compact Layout",
"name" : "Custom_Account_Compact_Layout"
},
"Contact" : {
"actions" : [ {
"behavior" : null,
"content" : null,
"contentSource" : null,
"custom" : false,
"encoding" : null,
"height" : null,
"icons" : null,
"label" : "Call",
"menubar" : false,
"name" : "CallHighlightAction",
"overridden" : false,
"resizeable" : false,
"scrollbars" : false,
"showsLocation" : false,
"showsStatus" : false,
"toolbar" : false,
"url" : null,

125

Reference

FlexiPage

"width" : null,
"windowPosition" : null
},
...
"id" : null,
"label" : "System Default",
"name" : "SYSTEM"
}
"CustomObj__c" : {
"actions" : [ {
"behavior" : null,
"content" : null,
"contentSource" : null,
"custom" : false,
"encoding" : null,
"height" : null,
"icons" : null,
"label" : "Call",
"menubar" : false,
"name" : "CallHighlightAction",
"overridden" : false,
"resizeable" : false,
"scrollbars" : false,
"showsLocation" : false,
"showsStatus" : false,
"toolbar" : false,
"url" : null,
"width" : null,
"windowPosition" : null
},
...
"id" : null,
"imageItems" : null,
"label" : "System Default",
"name" : "SYSTEM"
}
}

FlexiPage
Returns a list of Lightning Pages and their details. Information returned includes Lightning Page regions, the components within each
region, and each components properties, as well as any associated QuickActions. This resource is available in API version 29.0 and later.
Note: These pages are known as FlexiPages in the API, but are referred to as Lightning Pages in the rest of the Salesforce
documentation and UI.

Syntax
URI
To return all the details of a Lightning Page, use /vXX.X/flexiPage/ID of Lightning Page.

126

Reference

FlexiPage

Formats
JSON, XML
HTTP methods
HEAD, GET
Authentication
Authorization: Bearer token

Parameters
None required

Example
Getting root Lightning Page resource
curl https://yourInstance.salesforce.com/services/data/v29.0/flexiPage/ -H
"Authorization: Bearer token"

Getting a Lightning Page whose name is Deliveries

curl https://yourInstance.salesforce.com/services/data/v29.0/flexiPage/Deliveries -H
"Authorization: Bearer token"

Example request body for /vXX.X/flexiPage/

none required
Example response body for /vXX.X/flexiPage/
{
"urls" : {
"flexiPage" : "/services/data/v29.0/flexiPage",
"rowTemplate" : "/services/data/v29.0/flexiPage/{Developer Name of FlexiPage}"
}
}

Example request body for /vXX.X/flexiPage/{Developer Name of FlexiPage}

none required
Example response body for /vXX.X/flexiPage/{Developer Name of FlexiPage}
Note: This code example contains quickActionList information. To find out more about quick actions in the REST API, see
Quick Actions and SObject Quick Actions.
[ {
"id" : "0M0xx0000000049CAA",
"name" : "Deliveries",
"label" : "Deliveries",
"type" : "AppPage",
"regions" : [ {
"name" : "main",
"components" : [ {
"properties" : [ {
"name" : "filterName",
"value" : "Todays_Deliveries"
}, {
"name" : "entityName",

127

Reference

FlexiPage

"value" : "Delivery__c"
} ],
"typeName" : "filterListCard",
"typeNamespace" : "flexipage"
}, {
"properties" : [ {
"name" : "entityNames",
"value" : "Delivery__c,Return_Item__c"
} ],
"typeName" : "recentItems",
"typeNamespace" : "flexipage"
} ]
} ],
"quickActionList" : {
"quickActionListItems" : [ {
"quickActionName" : "New_Delivery",
"type" : "Create",
"colors" : [ {
"color" : "e1be5c",
"theme" : "theme4",
"context" : "primary"
}, {
"color" : "AA8E0A",
"theme" : "theme3",
"context" : "primary"
} ],
"accessLevelRequired" : null,
"globalAction" : true,
"miniIconUrl" :
"http://{SALESFORCE-APPSERVER-DOMAIN}/img/icon/custom51_100/truck16.png",
"label" : "New Delivery",
"urls" : {
"defaultValuesTemplate" :
"/services/data/v29.0/quickActions/New_Delivery/defaultValues/{ID}",
"quickAction" : "/services/data/v29.0/quickActions/New_Delivery",
"defaultValues" : "/services/data/v29.0/quickActions/New_Delivery/defaultValues",
"describe" : "/services/data/v29.0/quickActions/New_Delivery/describe"
},
"targetSobjectType" : "Delivery__c",
"iconUrl" :
"http://{SALESFORCE-APPSERVER-DOMAIN}/img/icon/custom51_100/truck32.png",
"icons" : [ {
"url" : "http://{SALESFORCE-APPSERVER-DOMAIN}/img/icon/custom51_100/truck32.png",
"contentType" : "image/png",
"theme" : "theme3",
"height" : 32,
"width" : 32
}, {
"url" : "http://{SALESFORCE-APPSERVER-DOMAIN}/img/icon/custom51_100/truck16.png",
"contentType" : "image/png",
"theme" : "theme3",

128

Reference

Invocable Actions

"height" : 16,
"width" : 16
}, {
"url" : "http://{SALESFORCE-APPSERVER-DOMAIN}/img/icon/t4/custom/custom98.svg",
"contentType" : "image/svg+xml",
"theme" : "theme4",
"height" : 0,
"width" : 0
}, {
"url" : "http://{SALESFORCE-APPSERVER-DOMAIN}/img/icon/t4/custom/custom98_60.png",
"contentType" : "image/png",
"theme" : "theme4",
"height" : 60,
"width" : 60
}, {
"url" :
"http://{SALESFORCE-APPSERVER-DOMAIN}/img/icon/t4/custom/custom98_120.png",
"contentType" : "image/png",
"theme" : "theme4",
"height" : 120,
"width" : 120
} ]
} ]
}
} ]

In the code sample above:

namethe name of the region
componentsan array of Lightning components in the region
propertiesan array of properties for the component
typeNamethe name of the Lightning component
typeNamespacethe namespace of the Lightning component

Invocable Actions
Represents a standard or custom invocable action.
Use actions to add more functionality to your applications. Choose from standard actions, such as posting to Chatter or sending email,
or create actions based on your companys needs.
This resource is available in REST API version 32.0 and later.

Syntax
URI
Get a list of custom actions:
/vXX.X/actions

129

Reference

Invocable Actions

Formats
JSON, XML
HTTP Methods
GET, POST
Authentication
Authorization: Bearer token

Parameters
None
Example
Using GET to retrieve a list of general action types for the current organization:
/services/data/v32.0/actions

JSON Response body

{
"standard" : "/services/data/v32.0/actions/standard",
"custom" : "/services/data/v32.0/actions/custom"
}

Example
Using POST to send a simple email message:
/services/data/v32.0/actions/standard/emailSimple

JSON Request body

{
"inputs" : [ {
"emailAddresses" : "[email protected]",
"emailSubject" : "Note",
"emailBody" : "Message of the day.",
"senderAddress" : "[email protected]"
} ]
}

JSON Response body

{
"actionName" : "emailSimple",
"errors" : null,
"isSuccess" : true,
"outputValues" : null
}

Standard actions return their name in actionName. The value of actionName varies for custom actions.
Action

actionName value

Flow

The flow name

Apex

The classs invocable method name

130

Reference

Standard Invocable Actions

Action

actionName value

Quick action

<object name>.<quick action name>

For a global quick action, theres no <object name>. prefix.

Email alert

<object name>.<email alert name>

For more information about actions, see the Force.com Actions Developer Guide.

Standard Invocable Actions

Returns the list of actions that can be statically invoked. You can also get basic information for each type of action.
This resource is available in REST API version 32.0 and later.

Syntax
URI
Get a list of standard actions:
/vXX.X/actions/standard

Formats
JSON, XML
HTTP Methods
GET, HEAD, POST
Authentication
Authorization: Bearer token

Parameters
None
Notes
The Post to Chatter action supports the following features using a special format in the body post.
@mentions using @[<id>]
Topics using #[<topicString>]
For example, the string Hi @[005000000000001] check this out #[some_topic]. is stored appropriately as
Hi @Joe, check this out #some_topic. where @Joe and #some_topic are links to the user and topic, respectively.

Examples
Retrieving a list of standard actions for the current organization
/services/data/v32.0/actions/standard

JSON Response body

{
"actions" : [ {
"label" : "Submit for Approval",

131

Reference

Standard Invocable Actions

"name" : "submit",
"type" : "SUBMITAPPROVAL"
}, {
"label" : "Post to Chatter",
"name" : "chatterPost",
"type" : "CHATTERPOST" },
}, {
"label" : "Send Email",
"name" : "emailSimple",
"type" : "EMAILSIMPLE"
} ]
}

Get the attributes of a single standard action, for example, emailSimple

/services/data/v32.0/actions/standard/emailSimple

JSON Response body

{
"description" : "Send an email where you specify the subject, body, and recipients.",
"inputs" : [ {
"byteLength" : 0,
"description" : "Optional. The email recipients specified as a comma-separated list.",
"label" : "Email Addresses (comma-separated)",
"maxOccurs" : 1,
"name" : "emailAddresses",
"picklistValues" : null,
"required" : false,
"sobjectType" : null,
"type" : "STRING"
}, {
"byteLength" : 0,
"description" : "Optional. The email recipients specified as a collection of Strings.",
"label" : "Email Addresses (collection)",
"maxOccurs" : 5,
"name" : "emailAddressesArray",
"picklistValues" : null,
"required" : false,
"sobjectType" : null,
"type" : "STRING"
}, {
"byteLength" : 0,
"description" : "Optional. Who the email is from. Defaults to the current user.",
"label" : "Sender Type",
"maxOccurs" : 1,
"name" : "senderType",
"picklistValues" : null,
"required" : false,
"sobjectType" : null,
"type" : "STRING"
}, {
"byteLength" : 0,
"description" : "Required. The email's subject.",

132

Reference

Custom Invocable Actions

"label" : "Subject",
"maxOccurs" : 1,
"name" : "emailSubject",
"picklistValues" : null,
"required" : true,
"sobjectType" : null,
"type" : "STRING"
}, {
"byteLength" : 0,
"description" : "Required. The body of the email in plain text.",
"label" : "Body",
"maxOccurs" : 1,
"name" : "emailBody",
"picklistValues" : null,
"required" : true,
"sobjectType" : null,
"type" : "TEXTAREA"
} ],
"label" : "Send Email",
"name" : "emailSimple",
"outputs" : [ ],
"standard" : true,
"targetEntityName" : null,
"type" : "EMAILSIMPLE"
}

Custom Invocable Actions

Returns the list of all custom actions. You can also get basic information for each type of action.
This resource is available in REST API version 32.0 and later.

Syntax
URI
Get a list of custom actions:
/vXX.X/actions/custom

Formats
JSON, XML
HTTP Methods
GET, HEAD, POST
Authentication
Authorization: Bearer token

Parameters
None
Notes
Sending email with the emailAlert action counts against your daily email limit for workflows. For more information, see Daily Limits
for Email Alerts in the Salesforce Help.

133

Executes the SOQL query for the list view and returns the resulting data and presentation information.
This resource is available in REST API version 32.0 and later.
URI
/vXX.X/sobjects/{sobjectType}/listviews/{listViewID}/results

Formats
JSON, XML
HTTP Method
GET
Authentication
Authorization: Bearer token

Parameters
None
Example:
Retrieving results from a specific list view
curl
https://yourInstance.salesforce.com/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcCNMA0/results
-H "Authorization: Bearer token"

JSON Response body

138

Reference

List Views

}, {
"fieldNameOrPath" : "CreatedDate",
"value" : "Fri Aug 01 21:15:46 GMT 2014"
}, {
"fieldNameOrPath" : "LastModifiedDate",
"value" : "Fri Aug 01 21:15:46 GMT 2014"
}, {
"fieldNameOrPath" : "SystemModstamp",
"value" : "Fri Aug 01 21:15:46 GMT 2014"
} ]
}, {
"columns" : [ {
"fieldNameOrPath" : "Name",
"value" : "University of Arizona"
}, {
"fieldNameOrPath" : "Site",
"value" : null
}, {
"fieldNameOrPath" : "BillingState",
"value" : "AZ"
}, {
"fieldNameOrPath" : "Phone",
"value" : "(520) 773-9050"
}, {
"fieldNameOrPath" : "Type",
"value" : "Customer - Direct"
}, {
"fieldNameOrPath" : "Owner.Alias",
"value" : "TUser"
}, {
"fieldNameOrPath" : "Id",
"value" : "001D000000JliSYIAZ"
}, {
"fieldNameOrPath" : "CreatedDate",
"value" : "Fri Aug 01 21:15:46 GMT 2014"
}, {
"fieldNameOrPath" : "LastModifiedDate",
"value" : "Fri Aug 01 21:15:46 GMT 2014"
}, {
"fieldNameOrPath" : "SystemModstamp",
"value" : "Fri Aug 01 21:15:46 GMT 2014"
} ]
} ],
"size" : 12
}

List Views
Returns the list of list views for the specified sObject, including the ID and other basic information about each list view. You can also get
basic information for a specific list view by ID.
This resource is available in REST API version 32.0 and later.

147

Reference

List Views

URI
Get a list of list views:
/vXX.X/sobjects/{sobjectType}/listviews

Get basic information about one list view:

/vXX.X/sobjects/{sobjectType}/listviews/{listViewID}

Available since release

31.0
Formats
JSON, XML
HTTP Methods
GET
Authentication
Authorization: Bearer token

Parameters
None
Example:
Retrieving a list of list views for the Account object
curl
https://yourInstance.salesforce.com/services/data/v32.0/sobjects/Account/listviews
-H "Authorization: Bearer token"

JSON Response body

{
"done" : true,
"listviews" : [ {
"describeUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcBeMAK/describe",
"developerName" : "NewThisWeek",
"id" : "00BD0000005WcBeMAK",
"label" : "New This Week",
"resultsUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcBeMAK/results",
"soqlCompatible" : true,
"url" : "/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcBeMAK"
}, {
"describeUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcBpMAK/describe",
"developerName" : "NewLastWeek",
"id" : "00BD0000005WcBpMAK",
"label" : "New Last Week",
"resultsUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcBpMAK/results",
"soqlCompatible" : true,
"url" : "/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcBpMAK"
}, {
"describeUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcC6MAK/describe",

148

Reference

List Views

"developerName" : "PlatinumandGoldSLACustomers",
"id" : "00BD0000005WcC6MAK",
"label" : "Platinum and Gold SLA Customers",
"resultsUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcC6MAK/results",
"soqlCompatible" : true,
"url" : "/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcC6MAK"
}, {
"describeUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcCEMA0/describe",
"developerName" : "RecentlyViewedAccounts",
"id" : "00BD0000005WcCEMA0",
"label" : "Recently Viewed Accounts",
"resultsUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcCEMA0/results",
"soqlCompatible" : true,
"url" : "/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcCEMA0"
}, {
"describeUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcCFMA0/describe",
"developerName" : "AllAccounts",
"id" : "00BD0000005WcCFMA0",
"label" : "All Accounts",
"resultsUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcCFMA0/results",
"soqlCompatible" : true,
"url" : "/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcCFMA0"
}, {
"describeUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcCNMA0/describe",
"developerName" : "MyAccounts",
"id" : "00BD0000005WcCNMA0",
"label" : "My Accounts",
"resultsUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcCNMA0/results",
"soqlCompatible" : true,
"url" : "/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcCNMA0"
} ],
"nextRecordsUrl" : null,
"size" : 6,
"sobjectType" : "Account"
}

Retrieving basic information about one list view

Use the ID of a list view to get basic information about a specific list view.
curl
https://yourInstance.salesforce.com/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcBeMAK
-H "Authorization: Bearer token"

JSON Response body

{
"describeUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcBeMAK/describe",

149

Reference

Support Knowledge with REST API

"developerName" : "NewThisWeek",
"id" : "00BD0000005WcBeMAK",
"label" : "New This Week",
"resultsUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcBeMAK/results",
"soqlCompatible" : true,
"url" : "/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcBeMAK"
}

Support Knowledge with REST API

Knowledge Support REST APIs allow both authorized and guest users to retrieve the users visible data categories and their associated
articles.
Authenticated users need the UserProfile.apiEnabled permission, Knowledge enabled in the organization, read rights on
the article type, and any other knowledge specific permission or preference that controls visibility to articles.
Guest users need the Guest Access to the Support API preference enabled on the relevant Site, Knowledge enabled in
the organization, and read rights on the article type and article channel that controls the visibility for guest users.

This provides a summary of data category information. The Summary and Detail responses share common properties, with the
goal of providing only as much information as is necessary from associated resources.
{
"name": String, // the unique name of the category
"label": String, // returns the translated version if it is available
"url": URL,
// the url points to the data category detail API
"childCategories": [ Data Category Summary, ....] // null if topCategoriesOnly is
true
}

Note: The URL property is a pre-calculated path to the unique resource representing this data category, in this case it is
a Data Category Detail API.

Example
Input
/services/data/v38.0/support/dataCategoryGroups?sObjectName=KnowledgeArticleVersion

Output
{
"categoryGroups" : [ {
"label" : "Doc",
"name" : "Doc",
"objectUsage" : "KnowledgeArticleVersion",
"topCategories" : [ {
"childCategories" : null,
"label" : "All",
"name" : "All",
"url" :

152

Reference

Usage
Salesforce Knowledge must be enabled in your organization. This resource can be used in API version 38.0 and later. Use the language
code format used in Which Languages Does Salesforce Support?.
Only the users visible data categories are returned. A user might be able to see several sub trees in the category group, therefore, the
top categories that are visible to the user in each group are returned.

Data Category Detail

Get data category details and the child categories by a given category.

Syntax
Available since release
38.0
Method
GET
Formats
JSON, XML
Authentication
OAuth accesstoken
Endpoint
[prefix]/support/dataCategoryGroups/[group]/dataCategories/[category]
HTTP headers
Accept: Optional. Can be either application/json or application/xml.
Accept-language: Optional. Language to translate the categories. Any ISO-639 language abbreviation, and an ISO-3166 country
code subtag in the HTTP Accept-Language header. Only one language accepted. If no language specified, the non-translated labels
are returned.

153

Reference

Data Category Detail

Input:
string sObjectName: Required. KnowledgeArticleVersion only.
Output:
Details of the category and a list of child categories (name, label, etc.).
Data Category Detail
Used for situations where the hierarchical representation of data categories is important. The child property contains a list of
child data categories.
{
"name": String, // the unique name of the category
"label": String, // returns the translated version if it is available
"url": URL,
"childCategories": [ Data Category Summary, ....],
}

Note: If the category isnt visible to the current user the return is empty.

Example
Input
/services/data/v38.0/support/dataCategoryGroups/Doc/dataCategories/All?sObjectName=KnowledgeArticleVersion

Output
{
"childCategories" : [ {
"childCategories" : null,
"label" : "Help",
"name" : "Help",
"url" :
"/services/data/v38.0/support/dataCategoryGroups/Doc/dataCategories/Help?sObjectName=KnowledgeArticleVersion"
}, {
"childCategories" : null,
"label" : "QA",
"name" : "QA",
"url" :
"/services/data/v38.0/support/dataCategoryGroups/Doc/dataCategories/QA?sObjectName=KnowledgeArticleVersion"
} ],
"label" : "All",
"name" : "All",
"url" :
"/services/data/v38.0/support/dataCategoryGroups/Doc/dataCategories/All?sObjectName=KnowledgeArticleVersion"
}

154

Reference

Articles List

Articles List
Get a page of online articles for the given language and category through either search or query.

Syntax
Available since release
38.0
Method
GET
Formats
JSON, XML
Authentication
OAuth accesstoken
Endpoint
[prefix]/support/knowledgeArticles
HTTP headers
Accept: Optional. Can be either application/json or application/xml.
Accept-language: Required. The article must be an active language in the users organization
If the language code isnt valid, an error message is returned: The language code is not valid or not supported by Knowledge.
If the language code is valid, but not supported by Knowledge, then an error message is returned: Invalid language code. Check
that the language is included in your Knowledge language settings."
Input:
string q: Optional, Performs an SOSL search. If the query string is null, empty, or not given, an SOQL query runs.
string channel: Optional, defaults to users context. For information on channel values, see Valid channel values.
App: Visible in the internal Salesforce Knowledge application
Pkb: Visible in the public knowledge base
Csp: Visible in the Customer Portal
Prm: Visible in the Partner Portal
string categories in map json format {group1:category1,group2:category2,...} )
Optional, defaults to None. Category group must be unique in each group:category pair, otherwise you get
ARGUMENT_OBJECT_PARSE_ERROR.
string queryMethod values are: AT, BELOW, ABOVE, ABOVE_OR_BELOW. Only valid when categories are specified,
defaults to ABOVE_OR_BELOW.
string sort: Optional, a sortable field name LastPublishedDate, CreatedDate, Title, ViewScore. Defaults
to LastPublishedDate for query and relevance for search.
Note: When sorting on ViewScore it is only available for query, not search, and no pagination is supported. You only get
one page of results.
string order: Optional, either ASC or DESC, defaults to DESC. Valid only when sort is valid.
integer pageSize: Optional, defaults to 20. Valid range 1 to 100.
integer pageNumber : Optional, defaults to 1.

155

Reference

Articles List

Output:
A page of online articles in the given language and category visible to the current user.
Article Page
A page of articles. The individual entries are article summaries so the size can be kept at a minimum.
{
articles: [ Article Summary, ], // list of articles
currentPageUrl: URL,
// the article list API with current page number
nextPageUrl: URL, // the article list API with next page number,
which can be null if there are no more articles.
pageNumber: Int // the current page number, starting at 1.
}

Note: The API supports paging. Each page of responses includes a URL to its page, as well as the URL to the next page
of articles.
Article Summary
A summary of an article used in a list of article responses. It shares similar properties to the Article Detail representation, as one
is a superset of the other.
{
id: Id,
// articleId
articleNumber: String,
title: String,
summary: String,
url: URL, // to the Article Detail API
viewCount: Int,
// view count in the interested channel
viewScore: double (in xxx.xxxx precision),
// view score in the interested
channel.
upVoteCount: int, // up vote count in the interested channel.
downVoteCount: int, // down vote count in the interested channel.
lastPublishedDate: Date // last publish date in ISO8601 format
categoryGroups: [ Data Category Group, . ]}

The url property always points to the Article Details resource endpoint. For information on valid channel values, see the channel
parameter description
Data Category Group
An individual data category group, its root category, and a list of selected data categories in the group.
{
groupName: String, // the unique name of the category group
groupLabel: String, // returns the translated version
selectedCategories: [ Data Category Summary, ]
}

Data Category Summary

Provides a summary of data category information. The Summary and Detail responses share common properties.
{
categoryName: String, // the unique name of the category
categoryLabel: String, // returns the translated version, per the API
language specified

156

Reference

Articles List

url:

String // returns the url for the DataCategory REST API.

Note: The outputs of Data Category Group and Data Category Summary in Article List API are different from the Data
Category Groups API.

Example
Input
/services/data/v38.0/support/knowledgeArticles?sort=ViewScore&channel=Pkb&pageSize=3
HTTP Headers:
Content-Type: application/json; charset=UTF-8
Accept: application/json
Accept-Language: en-US

Output
{
"articles" : [ {
"articleNumber" : "000001002",
"categoryGroups" : [ ],
"downVoteCount" : 0,
"id" : "kA0xx000000000BCAQ",
"lastPublishedDate" : "2015-02-25T02:07:18Z",
"summary" : "With this online Chinese input tool, you can type Chinese characters
through your web browser without installing any Chinese input software in your system.
The Chinese online input tool uses the popular Pin Yin input method. It is a fast and
convenient tool to input Chinese on English OS environments.",
"title" : "Long text test",
"upVoteCount" : 0,
"url" : "/services/data/v38.0/support/knowledgeArticles/kA0xx000000000BCAQ",
"viewCount" : 4,
"viewScore" : 100.0
}, {
"articleNumber" : "000001004",
"categoryGroups" : [ ],
"downVoteCount" : 0,
"id" : "kA0xx000000000LCAQ",
"lastPublishedDate" : "2016-06-21T21:11:02Z",
"summary" : "The number of characters required for complete coverage of all these
languages' needs cannot fit in the 256-character code space of 8-bit character encodings,
requiring at least a 16-bit fixed width encoding or multi-byte variable-length encodings.
\r\n\r\nAlthough CJK encodings have common character sets, the encodings often used to
represent them have been developed separately by different East Asian governments and
software companies, and are mutually incompatible. Unicode has attempted, with some
controversy, to unify the character sets in a process known as Han unification.\r\n\r\nCJK
character encodings should consist minimally of Han characters p",
"title" : "Test Images",
"upVoteCount" : 0,
"url" : "/services/data/v38.0/support/knowledgeArticles/kA0xx000000000LCAQ",
"viewCount" : 0,
"viewScore" : 0.0
}, {

157

Reference

Articles Details

"articleNumber" : "000001012",
"categoryGroups" : [ ],
"downVoteCount" : 0,
"id" : "kA0xx000000006GCAQ",
"lastPublishedDate" : "2016-06-21T21:10:48Z",
"summary" : null,
"title" : "Test Draft 2",
"upVoteCount" : 0,
"url" : "/services/data/v38.0/support/knowledgeArticles/kA0xx000000006GCAQ",
"viewCount" : 0,
"viewScore" : 0.0
} ],
"currentPageUrl" :
"/services/data/v38.0/support/knowledgeArticles?channel=Pkb&pageSize=3&sort=ViewScore",
"nextPageUrl" : null,
"pageNumber" : 1
}

Valid channel Values

When using the options string channel, where the matching articles are visible, the following values are valid.
AppVisible in the internal Salesforce Knowledge application
PkbVisible in the public knowledge base
CspVisible in the Customer Portal
PrmVisible in the Partner Portal
If channel isnt specified, the default value is determined by the type of user.
Pkb for a guest user
Csp for a Customer Portal user
Prm for a Partner Portal user
App for any other type of user
If channel is specified, the specified value may be used to retrieve articles.
For guest, Customer Portal, and Partner Portal users, if the specified channel is other than the channel accessible to the user, an
error is returned.
For all users other than guest, Customer Portal, and Partner Portal users, the specified channel value is used.

Articles Details
Get all article fields, accessible to the user.

158

Reference

Articles Details

Syntax
Available since release
38.0
Method
GET
Formats
JSON, XML
Authentication
OAuth accesstoken
Endpoint
[prefix]/support/knowledgeArticles/{articleId}
HTTP headers
Accept: Optional. Can be either application/json or application/xml.
Accept-language: Required. The article must be an active language in the users organization
If the language code isnt valid, an error message is returned: The language code is not valid or not supported by Knowledge.
If the language code is valid, but not supported by Knowledge, then an error message is returned: Invalid language code. Check
that the language is included in your Knowledge language settings."
Input:
string channel: Optional, defaults to users context. For information on channel values, see Valid channel Values.
App: Visible in the internal Salesforce Knowledge application
Pkb: Visible in the public knowledge base
Csp: Visible in the Customer Portal
Prm: Visible in the Partner Portal
boolean updateViewStat: Optional, defaults to true. If true, API updates the view count in the given channel as well as the
total view count.
Output:
The detailed fields of the article, if the article is online and visible to the current user.
Article Detail
Full detail of an article, with complete metadata and layout-driven fields used for display of an article. It includes all the same
properties as an Article Summary representation.
{
"id": Id,
// articleId,
"articleNumber": String,
"title": String,
"summary": String,
"url": URL,
"versionNumber": Int,
"createdDate": Date, // in ISO8601 format
"createdBy": User Summary on page 160,
"lastModifiedDate": Date,
// in ISO8601 format
"lastModifiedBy": User Summary on page 160,
"lastPublishedDate": Date, // in ISO8601 format
"layoutItems": [ Article Field, ... ], // standard and custom fields visible

159

Reference

Articles Details

to the user, sorted based on the layouts of the article type.

"categories": [ Data Category Groups, ... ],
"appUpVoteCount": Int,
"cspUpVoteCount": Int,
"prmUpVoteCount": Int,
"pkbUpVoteCount": Int,
"appDownVoteCount": Int,
"cspDownVoteCount": Int,
"prmDownVoteCount": Int,
"pkbDownVoteCount": Int,
"allViewCount": Int,
"appViewCount": Int,
"cspViewCount": Int,
"prmViewCount": Int,
"pkbViewCount": Int,
"allViewScore": Double,
"appViewScore": Double,
"cspViewScore": Double,
"prmViewScore": Double,
"pkbViewScore": Double
}

User Summary
{
"id": String
"isActive": boolean
// true/false
"userName": String
// login name
"firstName": String
"lastName": String
"email": String
"url": String
// to the chatter user detail url:
/services/data/xx.x/chatter/users/{userId}, for guest user, it will return null.
}

Article Field
An individual field of article information, which is listed in an Article Detail in the order required by the administrators layout.
{
"type": Enum,
"name": String,
"label": String,
"value": String,
}

// see the Notes

// field name
// label

Example
Input
/services/data/v38.0/support/knowledgeArticles/kA0xx000000000LCAQ
HTTP Headers:
Content-Type: application/json; charset=UTF-8

160

Reference

Articles Details

Accept: application/json
Accept-Language: en-US

Output
{
"allViewCount" : 17,
"allViewScore" : 100.0,
"appDownVoteCount" : 0,
"appUpVoteCount" : 0,
"appViewCount" : 17,
"appViewScore" : 100.0,
"articleNumber" : "000001004",
"categoryGroups" : [ ],
"createdBy" : {
"email" : "[email protected]",
"firstName" : "Test",
"id" : "005xx000001SvoMAAS",
"isActive" : true,
"lastName" : "User",
"url" : "/services/data/v38.0/chatter/users/005xx000001SvoMAAS",
"userName" : "[email protected]"
},
"createdDate" : "2016-06-21T21:10:54Z",
"cspDownVoteCount" : 0,
"cspUpVoteCount" : 0,
"cspViewCount" : 0,
"cspViewScore" : 0.0,
"id" : "kA0xx000000000LCAQ",
"lastModifiedBy" : {
"email" : "[email protected]",
"firstName" : "Test",
"id" : "005xx000001SvoMAAS",
"isActive" : true,
"lastName" : "User",
"url" : "/services/data/v38.0/chatter/users/005xx000001SvoMAAS",
"userName" : "[email protected]"
},
"lastModifiedDate" : "2016-06-21T21:11:02Z",
"lastPublishedDate" : "2016-06-21T21:11:02Z",
"layoutItems" : [ {
"label" : "Out of Date",
"name" : "IsOutOfDate",
"type" : "CHECKBOX",
"value" : "false"
}, {
"label" : "sample",
"name" : "sample",
"type" : "PICK_LIST",
"value" : null
}, {
"label" : "Language",
"name" : "Language",
"type" : "PICK_LIST",
"value" : "en_US"

161

Reference

Articles Details

}, {
"label" : "MyNumber",
"name" : "MyNumber",
"type" : "NUMBER",
"value" : null
}, {
"label" : "My File",
"name" : "My_File",
"type" : "FILE",
"value" : null
} ],
"pkbDownVoteCount" : 0,
"pkbUpVoteCount" : 0,
"pkbViewCount" : 0,
"pkbViewScore" : 0.0,
"prmDownVoteCount" : 0,
"prmUpVoteCount" : 0,
"prmViewCount" : 0,
"prmViewScore" : 0.0,
"summary" : "The number of characters required for complete coverage of all these
languages' needs cannot fit in the 256-character code space of 8-bit character encodings,
requiring at least a 16-bit fixed width encoding or multi-byte variable-length encodings.
\r\n\r\nAlthough CJK encodings have common character sets, the encodings often used to
represent them have been developed separately by different East Asian governments and
software companies, and are mutually incompatible. Unicode has attempted, with some
controversy, to unify the character sets in a process known as Han unification.\r\n\r\nCJK
character encodings should consist minimally of Han characters p",
"title" : "Test Images",
"url" : "/services/data/v38.0/support/knowledgeArticles/kA0xx000000000LCAQ",
"versionNumber" : 7
}

Usage
Salesforce Knowledge must be enabled in your organization. This resource can be used in API version 38.0 and later. The Custom File
Field is not supported because it returns a link to a binary stream. Use the language code format used in Which Languages Does Salesforce
Support?.
A lookup custom field is visible to guest users depending on the lookup entity type. For example, User is visible, but Case and Account
are not visible. Following standard fields are not visible to a guest user, even if they are in the layout:
archivedBy
isLatestVersion
translationCompletedDate
translationImportedDate
translationExportedDate
versionNumber
visibleInInternalApp
visibleInPKB
visibleToCustomer
visbileToPartner

162

Reference

Parameterized Search

Valid channel Values

Parameterized Search
Executes a simple RESTful search using parameters instead of a SOSL clause. Indicate parameters in a URL in the GET method. Or, use
POST for more complex JSON searches.

Syntax
URI
/vXX.X/parameterizedSearch/?q=search string

Formats
JSON, XML
HTTP Method
GET, POST
Authentication
Authorization: Bearer token

Required Global Parameters

Name

Description

A search string that is properly URL-encoded.

Note: SOSL clauses arent supported.
Available in version 36.0 and later.

163

Reference

Parameterized Search

Optional Global Parameters

Name

Type

dataCategory string

Supported Description
Methods
GET

Single value. If an organization uses Salesforce Knowledge articles or answers,

dataCategory filters all search results based on one data category.
For example, dataCategory=GlobalCategory__c below
NorthAmerica__c.
When using dataCategories, specify a Salesforce Knowledge article or answer
type with sobject and all the required parameters.
For example:
q=tourism&sobject=KnowledgeArticleVersion&KnowledgeArticleVersion.where=
language='en_US'+and+publishStatus='online'&KnowledgeArticleVersion.fields=
id,title&dataCategory=Location__c+Below+North_America__c

If you require multiple dataCategory filters, use dataCategories with

the POST method.
dataCategories dataCategoriesFilter[] POST

If an organization uses Salesforce Knowledge articles or answers, filters all search

results based on one or more data categories.
When using dataCategories, specify a Salesforce Knowledge article or answer
type with sobjects and the required parameters.
For example:
{
"q":"Acme",
"fields":["id", "title"],
"sobjects":[{"name":"KnowledgeArticleVersion",
"where":"language='en_US' and publishstatus='draft'"}],
"dataCategories":[
{"groupName" : "location__c", "operator":"below",
"categories":["North_America__c"]}
]
}

defaultLimit string

GET,
POST

Single value. The maximum number of results to return for each sobject (GET)
or sobjects (POST) specified.
The maximum defaultLimit is 2000.
At least one sobject must be specified.
GET example:
defaultLimit=10&sobject=Account&sobject=Contact.

When an sobject limit is specified using sobject.limit=value, such

as Account.limit=10, this parameter is ignored for that object.

164

Reference

Parameterized Search

Name

Type

Supported Description
Methods

division

string

GET,
POST

Single value. Filters search results based on the division field.

For example in the GET method, division=global.
Specify a division by its name rather than ID.
All searches within a specific division also include the global division.

fields

string

GET

Comma-separated list of one or more fields to return in the response for each
sobject specified. At least one sobject must be specified at the global level.
For example: fields=id&sobject=Account&sobject=Contact.
The global fields parameter is overridden when sobject are specified using
sobject.fields=field names. For example,
Contact.fields=id,FirstName,LastName would override the global
setting of just returning the id.
If unspecified, then the search results contain the IDs of records matching all fields
for the specified object.
Functions
The following optional functions can be used within the fields parameter.
toLabel: Translates response field value into the users language. For example,
Lead.fields=id,toLabel(Status). This function requires extra
setup.
convertCurrency: Converts response currency fields to the users currency.
For example,
Opportunity.fields=id,convertCurrency(Amount). This
function requires extra setup. Multi-currency must be enabled for your org.
format: Applies localized formatting to standard and custom number, date,
time, and currency fields. For example,
Opportunity.fields=id,format(Amount).
Aliasing is support within fields for toLabel, convertCurrency, and
format. In addition, aliasing is required when the query includes the same field
multiple times. For example,
Opportunity.fields=id,format(Amount) AliasAmount

fields

string[]

POST

Array of one or more fields to return in the response for each sobjects specified.
At least one sobjects must be specified at the global level.
For example:
{
"q":"Acme",
"fields":["Id", "Name", "Phone"],
"sobjects":[{"name": "Account"},
{"name": "Contact", "fields":["Id",
"FirstName", "LastName"]},

165

Reference

Parameterized Search

Name

Type

Supported Description
Methods
{"name": "Lead"}]
}

The global fields parameter is overridden when sobjectsFilter[]

fields are specified. Such as, in the previous example, Id, FirstName, and
LastName is returned for Contact instead of the global fields of Id, Name
and Phone.
If unspecified, then the search results contain the IDs of records matching all fields
for the specified object.
Functions
The following optional functions can be used within the fields parameter.
toLabel: Translates response field value into the users language. This function
requires extra setup. For example:
{
...
"sobjects":[ {"name": "Lead", "fields":["Id",
"toLabel(Status)"]},
...
}

convertCurrency: Converts response currency fields to the users currency.

This function requires extra setup. Multi-currency must be enabled in the org.
For example:
{
...
"sobjects":[ {"name": "Opportunity",
"fields":["Id", "convertCurrency(Amount)"]}]
...
}

format: Applies localized formatting to standard and custom number, date,

time, and currency fields. For example:
{
...
"sobjects":[ {"name": "Opportunity",
"fields":["Id", "format(Amount)"]}]
...
}

Aliasing is supported within fields for toLabel, convertCurrency,

and format. In addition, aliasing is required when the query includes the same
field multiple times. For example:
{
...
"sobjects":[ {"name": "Opportunity", "fields":["Id",

166

Reference

Parameterized Search

Name

Type

Supported Description
Methods
"format(Amount) AliasAmount"]}]
...
}

string

GET,
POST

Scope of fields to search. If you specify one or more scope values, the fields are
returned for all found objects.
Use one of the following values:
ALL
NAME
EMAIL
PHONE
SIDEBAR
This clause doesn't apply to articles, documents, feed comments, feed items, files,
products, and solutions. If any of these objects are specified, the search is not limited
to specific fields; all fields are searched.

metadata

string

GET,
POST

Specifies if metadata should be returned in the response. No metadata is returned

by default. To include metadata in the response, use the LABELS value, which
returns the display label for the fields returned in search results. For example:
?q=Acme&metadata=LABELS

netWorkIds string

GET

Filters search results by a comma-separated list.

A network ID represents the community ID.

netWorkIds string[]

POST

Filters search results by an array.

A network ID represents the community ID.

offset

string

GET,
POST

Single value. The starting row offset into the result set returned.
The maximum offset is 2000.
Only one sobject can be specified when using this parameter.

overallLimit string

GET,
POST

Single value. The maximum number of results to return across all sobject
parameters specified.
The maximum overallLimit is 2000.

pricebookId string

GET,
POST

Single value. Filters product search results by a price book ID for only the Product2
object. The price book ID must be associated with the product that youre searching
for. For example,
?q=laptop&sobject=product2&pricebookId=01sxx0000002MffAAE

snippet

string

GET,
POST

The target length (maximum number of snippet characters) to return in Salesforce

Knowledge article, case, case comment, feed, feed comment, idea, and idea
comment search results. The snippet parameter displays contextual excerpts
and highlights the search term for each article in the search results. Snippet results

167

Reference

Parameterized Search

Name

Type

Supported Description
Methods
are used to differentiate matches to the search term in article search results. The
target length can be from 50 to 1000 characters.
Snippet and highlights are generated from email, text, and text area (long and rich)
fields. Snippets arent displayed for partially matching searches or if the user doesnt
have access to the field that contains the snippet. Snippets are only displayed when
20 or fewer results are returned on a page.
At least one of the following sobject values must be specified.
To search a specific article type, use the article type name with the suffix
__kav.
To search all article types, use KnowledgeArticleVersion.
To search case, case comment, feed, feed comment, idea, and idea comment
types, use Case, CaseComment, FeedItem, FeedComment, Idea,
and IdeaComment.
For example, q=tourism&sobject=Case&snippet=500.

sobject

string

GET

Objects to return in the response. Must be a valid object type.

You can use multiple sobject values, such as
sobject=Account&sobject=Contact.

If unspecified, then the search results contain the IDs of all objects.
sobjects

sobjectsFilter[]

POST

Objects to return in the response. Must contain valid object types. Use with the
required parameters.
For example:
{
"q":"Acme",
"fields":["id", "title"],
"sobjects":[{"name":"Solution__kav",
"where":"language='en_US' and publishstatus='draft'"},
{"name":"FAQ__kav",
"where":"language='en_US' and publishstatus='draft'"}]
}

If unspecified, then the search results contain the IDs of all objects.
updateTracking string

GET,
POST

Specifies a value of true to track keywords that are used in Salesforce Knowledge
article searches only.
If unspecified, the default value of false is applied.

168

Reference

Parameterized Search

Name

Type

Supported Description
Methods

updateViewStat string

GET,
POST

Specifies a value of true to update an articles view statistics. Valid only for
Salesforce Knowledge article searches.
If unspecified, the default value of false is applied.

dataCategoriesFilter[] Parameters

Parameters must be specified in the order presented in the table (groupName, operator, categories).
Name

Type

Description

groupName string

The name of the data category group to filter by.

operator string

Valid values:
ABOVE
ABOVE_OR_BELOW
AT
BELOW

categories string[]

The name of the categories to filter by.

sobjectsFilter[] Parameters (POST Method Only)

Name

Type

Description

fields

string[] Array of one or more fields to return in the response for the sobject.

limit

string

Specify the maximum number of rows that are returned for the sobject.

name

string

Name of the sobject to return in the response.

orderBy

string

Controls the field order of the results using the following syntax "orderBy" : "field
{ASC|DESC} [NULLS_{FIRST|LAST}]"

For example:
{
...
"sobjects":[ {"name": "Account", "fields":["Id", "name"], "orderBy":
"Name DESC Nulls_last"}]
...
}

ASC: ascending. Default.

DESC: descending.
NULLS_FIRST: Null records at the beginning of the results. Default.
NULLS_LAST: Null records at the end of the results.

169

Reference

Parameterized Search

Filter search results for this object by specific field values.

For example, Account.where = conditionExpression. Here the conditionExpression
of the WHERE clause uses the following syntax: fieldExpression [logicalOperator
fieldExpression2 ... ].
Add multiple field expressions to a condition expression by using logical and comparison operators. For
example, KnowledgeArticleVersion.where=publishstatus='online' and
language='en_US'.

Example GET Method

.../v37.0/parameterizedSearch/?q=Acme&sobject=Account&Account.fields=id,name&Account.limit=10

170

Reference

Process Approvals

Example POST Method

{
"q":"Smith",
"fields" : ["id", "firstName", "lastName"],
"sobjects":[{"fields":["id", "NumberOfEmployees"],
"name": "Account",
"limit":20},
{"name": "Contact"}],
"in":"ALL",
"overallLimit":100,
"defaultLimit":10
}

Process Approvals
Returns a list of all approval processes. Can also be used to submit a particular record if that entity supports an approval process and one
has already been defined. Records can be approved and rejected if the current user is an assigned approver. When using a POST request
to do bulk approvals, the requests that succeed are committed and the requests that dont succeed send back an error.

Syntax
URI
To return a list of the approvals, the URI is: /vXX.X/process/approvals/
Available since release
30.0
Formats
JSON, XML
HTTP methods
GET, HEAD, POST
Authentication
Authorization: Bearer token

Request parameters
None required
Request body
The request body contains an array of process requests that contain the following information:
Name

Type

Description

actionType

string

Represents the kind of action to take: Submit, Approve, or Reject.

contextActorId ID

The ID of the submitter whos requesting the approval record.

contextId

The ID of the item that is being acted upon.

comments

string

The comment to add to the history step associated with this request.

171

Reference

Process Rules

Name

Type

Description

nextApproverIds ID[]

If the process requires specification of the next approval, the ID of the user to be
assigned the next request.

processDefinitionNameOrId string

The developer name or ID of the process definition.

skipEntryCriteria boolean

Determines whether to evaluate the entry criteria for the process (true) or not
(false) if the process definition name or ID isnt null. If the process definition name
or ID isnt specified, this argument is ignored, and standard evaluation is followed
based on process order. By default, the entry criteria isnt skipped if its not set
by this request.

Response body
The response contains an array of process results that contain the following information:
Name

Type

Description

actorIds

ID[]

IDs of the users who are currently assigned to this approval step.

entityId

The object being processed.

errors

Error[]

The set of errors returned if the request failed.

instanceId

The ID of the ProcessInstance associated with the object submitted for processing.

instanceStatus string

The status of the current process instance (not an individual object but the entire
process instance). The valid values are Approved, Rejected, Removed, or
Pending.

newWorkItemIds ID[]

Case-insensitive IDs that point to ProcessInstanceWorkitem items (the set of

pending approval requests)

success

boolean

true if processing or approval completed successfully.

Examples
See Get a List of All Approval Processes.
See Submit a Record for Approval.
See Approve a Record.
See Reject a Record.
See Bulk Approvals.

Process Rules
Returns a list of all active workflow rules. If a rule has actions, the actions will be listed under the rule. Can also be used to trigger all
workflow rules that are associated with a specified record. The actions for a rule are only fired if the rules criteria is met. When using a
POST request, if anything fails, the whole transaction is rolled back.
Cross-object workflow rules cannot be invoked using the REST API.

172

Reference

Query

Syntax
URI
To get a list of the workflow rules or to trigger one or more workflow rules, the URI is: /vXX.X/process/rules/
To get the rules for a particular object: /vXX.X/process/rules/SObjectName
To get the metadata for a particular rule: /vXX.X/process/rules/SObjectName/workflowRuleId
Available since release
30.0
Formats
JSON, XML
HTTP methods
HEAD, GET, POST
Authentication
Authorization: Bearer token

Request parameters
None required
Request body
The request body contains an array of context IDs:
Name

Type

Description

contextId

The ID of the item that is being acted upon.

Examples
See Get a List of Process Rules.
See Get a Particular Process Rule.
See Trigger Process Rules.

Query
Executes the specified SOQL query.
If the query results are too large, the response contains the first batch of results and a query identifier in the nextRecordsUrl field
of the response. The identifier can be used in an additional request to retrieve the next batch.
URI
/vXX.X/query/?q=SOQL query

For retrieving query performance feedback without executing the query:

/vXX.X/query/?explain=SOQL query

For retrieving query performance feedback on a report or list view:

/vXX.X/query/?explain=report or list view ID

For retrieving additional query results if the initial results are too large:
/vXX.X/query/query identifier

173

Reference

Query

Formats
JSON, XML
HTTP Method
GET
Authentication
Authorization: Bearer token

Parameters
Parameter

Description

A SOQL query. Note that you will need to replace spaces with + characters in your query string to
create a valid URI. An example query parameter string might look like:
SELECT+Name+FROM+MyObject. If the SOQL query string is invalid, a MALFORMED_QUERY response
is returned.

explain

A SOQL query to get performance feedback on. Use explain instead of q to get a response that
details how Salesforce will process your query. You can use this feedback to further optimize your
queries. You can also use a report or list view ID in place of the query string to get feedback on how
Salesforce will process your report or list view.
The explain parameter is available in API version 30.0 and later.
Note: Using explain with the REST API query resource is a beta feature. There is no support
associated with this beta feature. For more information, contact Salesforce.
If the SOQL query string is invalid, a MALFORMED_QUERY response is returned. If the report or list
view ID is invalid, an INVALID_ID response is returned.

Response body
For a query using the q parameter, the response contains an array of query result records. For a query using the explain parameter,
the response contains one or more query plans that can be used to execute the query, report, or list view. The plans are sorted from
most optimal to least optimal. Each plan has the following information:
Name

Type

Description

cardinality

number

The estimated number of records the query would return, based on index
fields, if any.

fields

string[]

The index fields used for the query, if the leading operation type is Index,
otherwise null.

leadingOperationType

string

The primary operation type that will be used to optimize the query. This can
be one of these values:
IndexThe query will use an index on the query object.
OtherThe query will use optimizations internal to Salesforce.
SharingThe query will use an index based on the users sharing rules.
If there are sharing rules that limit which records are visible to the current
user, those rules can be used to optimize the query.

174

Reference

QueryAll

Name

Type

Description
TableScanThe query will scan all records for the query object, and wont
use an index.

notes

feedback note[] An array of one or more feedback notes. Each note contains:
description A detailed description of an aspect of the optimization.
This could include information on optimizations that could not be used,
with details on why they werent used.
fields An array of one or more fields used for the optimization.
tableEnumOrId The table name for the fields used for the
optimization.
This response field is available in API version 33.0 and later.

relativeCost

number

The cost of this query compared to the SOQL selective query threshold. A
value greater than 1.0 means the query wont be selective. See More Efficient
SOQL Queries in the Apex Code Developers Guide for more information on
selective queries.

sobjectCardinality

number

The approximate count of all records in your organization for the query object.

sobjectType

string

The name of the query object, such as Merchandise__c.

Example
For an example of making a query and retrieving additional query results using the query identifier, see Execute a SOQL Query on
page 62.
For an example using the explain parameter to get feedback on a query and a report, see Get Feedback on Query Performance
on page 65.
For more information on SOQL see the Force.com SOQL and SOSL Reference. For more information on query batch sizes, see Changing
the Batch Size in Queries in the SOAP API Developer's Guide.

QueryAll
Executes the specified SOQL query. Unlike the Query resource, QueryAll will return records that have been deleted because of a merge
or delete. QueryAll will also return information about archived Task and Event records. QueryAll is available in API version 29.0 and later.
If the query results are too large, the response contains the first batch of results and a query identifier in the nextRecordsUrl field
of the response. The identifier can be used in an additional request to retrieve the next batch. Note that even though nextRecordsUrl
has query in the URL, it will still provide remaining results from the initial QueryAll request. The remaining results will include deleted
records that matched the initial query.
URI
/vXX.X/queryAll/?q=SOQL query

For retrieving additional query results if the initial results are too large:
/vXX.X/queryAll/query identifier

Formats
JSON, XML

175

Reference

Quick Actions

HTTP Method
GET
Authentication
Authorization: Bearer token

Parameters
Parameter

Description

A SOQL query. Note that you will need to replace spaces with + characters in your
query string to create a valid URI. An example query parameter string might look like:
SELECT+Name+FROM+MyObject.

Example
For an example of making a query that includes deleted items, see Execute a SOQL Query that Includes Deleted Items on page
64
For an example of a query that retrieves additional results using the query identifier, see Retrieving the Remaining SOQL Query
Results on page 64
For more information on SOQL see the Force.com SOQL and SOSL Reference. For more information on query batch sizes, see Changing
the Batch Size in Queries in the SOAP API Developer's Guide.

Quick Actions
Returns a list of global actions and object-specific actions. This resource is available in REST API version 28.0 and later. When working
with actions, also refer to SObject Quick Actions.
URI
/vXX.X/quickActions/

Formats
JSON, XML
HTTP Method
HEAD, GET, POST
Authentication
Authorization: Bearer token

Parameters
None required
Considerations
Add all required fields to an object before you create a quick action for that object. If you add a required field after creating a quick
action, the field wont appear in the quick actions describe results. Then, when the quick action runs, the field wont be available
and an error occurs for the missing field. If you dont want the required field to appear in the quick actions layout, set a default value
for the field.
Example usage for getting global quick actions
curl https://yourInstance.salesforce.com/services/data/v28.0/quickActions/ -H
"Authorization: Bearer token"

176

Reference

Recent List Views

Example for creating a contact using an action

curl https://yourInstance.salesforce.com/services/data/v28.0/quickActions/CreateContact
-H 'Authorization: Bearer access_token -H "Content-Type: application/json" -d
@newcontact.json'

Example JSON request body newcontact.json file

{
"record" : { "LastName" : "Smith" }
}

Recent List Views

Returns the list of recently used list views for the given sObject type.
This resource is available in REST API version 32.0 and later.
URI
/vXX.X/sobjects/{sobjectType}/listviews/recent

Formats
JSON, XML
HTTP Method
GET
Authentication
Authorization: Bearer token

Parameters
None
Example:
Retrieving recent list views for the Account object
curl
https://yourInstance.salesforce.com/services/data/v32.0/sobjects/Account/listviews/recent
-H "Authorization: Bearer token"

JSON Response body

{
"done" : true,
"listviews" : [ {
"describeUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcCNMA0/describe",
"developerName" : "MyAccounts",
"id" : "00BD0000005WcCNMA0",
"label" : "My Accounts",
"resultsUrl" :
"/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcCNMA0/results",
"soqlCompatible" : true,
"url" : "/services/data/v32.0/sobjects/Account/listviews/00BD0000005WcCNMA0"

177

Reference

Retrieve Knowledge Language Settings

Name

Type

Description

lastUpdatedId

string

A unique code that can be used in subsequent calls to compare the

results for a complete result set with the results in this response list.

newResultSetSinceLastQuery boolean (true If a response was previously requested for the current user, indicates
whether the current response matches the previous response, or the
or false)
one specified by a lastUpdatedId.

Response body
The response contains an array of records for each object returned, including the following information for each record.
Name

Type

Description

apiName

string

The objects unique name, such as Account

key

The first 3 characters of the sObjects ID that indicates the object type.

label

string

The objects plural label, such as Accounts.

lastUpdatedId

string

A unique code that can be used in subsequent calls to compare the

results for the new result set with the current results for this object.

qualifiedApiName

string

A unique external name for the sObject.

recordIds

A comma-separated list of IDs for the matching records.

Example
See View Relevant Items.

Retrieve Knowledge Language Settings

Returns the existing Knowledge language settings, including the default knowledge language and a list of supported Knowledge
language information.

Syntax
URI
/services/data/v31.0/knowledge Management/settings

Available since release

31.0
Formats
JSON, XML
HTTP methods
GET
Authentication
Authorization: Bearer token

180

Reference

Request body
None required
Request parameters
None

Example for Getting KnowledgeSettings

curl
https://https://yourInstance.salesforce.com/services/data/v31.0/knowledgeManagement/settings
-H "Authorization: Bearer token"

Example JSON Response Body

{
"defaultLanguage" : "en_US",
"knowledgeEnabled" : true,
"languages" : [ {
"active" : true,
"name" : "en_US"
}, {
"active" : true,
"name" : "it"
}, {
"active" : true,
"name" : "zh_CN"
}, {
"active" : true,
"name" : "fr"
} ]
}

Usage
Salesforce Knowledge must be enabled in your organization. The user must have the Knowledge User license on their profile. This
resource can be used in API version 31.0 and later. It retrieves the Knowledge language settings, including the default knowledge
language and a list of supported Knowledge language information.

Search
Executes the specified SOSL search. The search string must be URL-encoded.
For more information on SOSL see the Force.com SOQL and SOSL Reference.

Syntax
URI
/vXX.X/search/?q=SOSL search string

181

Reference

Search Scope and Order

Formats
JSON, XML
HTTP Method
GET
Authentication
Authorization: Bearer token

Parameters
Parameter

Description

A SOSL statement that is properly URL-encoded.

Example
See Search for a String on page 66.

Search Scope and Order

Returns an ordered list of objects in the default global search scope of a logged-in user. Global search keeps track of which objects the
user interacts with and how often and arranges the search results accordingly. Objects used most frequently appear at the top of the
list.
The returned list reflects the object order in the users default search scope, including any pinned objects on the users search results
page. This call is useful if you want to implement a custom search results page using the optimized global search scope. The search
string must be URL-encoded.

Syntax
URI
/vXX.X/search/scopeOrder

Formats
JSON, XML
HTTP Method
GET
Authentication
Authorization: Bearer token

Example
See Get the Default Search Scope and Order.

Search Result Layouts

Returns search result layout information for the objects in the query string. For each object, this call returns the list of fields displayed on
the search results page as columns, the number of rows displayed on the first page, and the label used on the search results page.
This call supports bulk fetch for up to 100 objects in a query.

182

Reference

Search Suggested Records

Syntax
URI
/vXX.X/search/layout/?q=Comma delimited object list

Formats
JSON, XML
HTTP Method
GET
Authentication
Authorization: Bearer token

Example
Get Search Result Layouts for Objects

Search Suggested Records

Returns a list of suggested records whose names match the users search string. The suggestions resource provides a shortcut for users
to navigate directly to likely relevant records, before performing a full search.

Syntax
URI
vXX.X/search/suggestions?q=search string&sobject=object types

Available since release

32.0
Formats
JSON, XML
HTTP methods
GET
Authentication
Authorization: Bearer token

Request body
None required

Request parameters
Parameter

Description

fields

Optional. Used for creating lookup queries. Specify multiple fields using a
comma-separated list. Specifies which lookup fields to be returned in the response.

groupId

Optional. Specifies one or more unique identifiers of one or more groups that the
question to return was posted to. Specify multiple groups using a comma-separated
list. This parameter is only applicable when the parameter type equals question.
Dont use with the userId.

ignoreUnsupportedSObjects

Optional. Specifies what to do if unsupported objects are included in the request. If

false and an unsupported object is included, an error is returned. If true and an

183

Reference

Search Suggested Records

Parameter

Description
unsupported object is included, the object is ignored and no error is returned. See the
Unsupported Objects section for reference. The default is false.

limit

Optional. Specifies the maximum number of suggested records to return. If a limit isnt
specified, 5 records are returned by default. If there are more suggested records than
the limit specified, the response bodys hasMoreResults property is true.

networkId

Optional. Specifies one or more unique identifiers for the community(ies) that the
question to return is associated to. Specify multiple communities using a
comma-separated list. This parameter is only applicable when the parameter type
equals question or parameter sobject equals user.

Required. The users search query string, properly URL-encoded. Suggestions are
returned only if the users query string meets the minimum length requirements: one
character for queries in Chinese, Japanese, Korean, and Thai; three characters for all
other languages. Query strings that exceed the maximum length of 255 characters (or
200 consecutive characters without a space break) return an error.

sobject

Required. The objects that the search is scoped to, such as Account or offer__c.
If the sobject value is feedItem, it is required to have the type parameter
with a value of question.
Specify up to 10 objects with a comma-separated list. For example:
sobject=Account,Contact,Lead. To take advantage of this feature, activate
the CrossObjectTypeahead permission.
To specify the specific fields to return by object, use the following syntax with multiple
fields in a comma-separated list. The sobject is lowercase.
sobject=sobject.fields=fields

For example:
&sobject=Account,Contact,Lead&account.fields=Website,Phone
&contact.fields=Phone

topicId

Optional. Specifies the unique identifier of the single topic that the question to return
was tagged as. This parameter is only applicable when the parameter type equals
question.

type

Required when the sobject value is feedItem. Including this parameter for all
other sobject values doesnt affect the query. Specifies that the type of Feed is
questions. Valid value: question.

userId

Optional. Specifies one or more unique identifiers of one or more users who authored
the question to return. Specify multiple users using a comma-separated list. This
parameter is only applicable when the parameter type equals question. Dont use
with the groupId.

where

Optional for single object requests. Not supported when multiple objects are specified
in the request. A filter constraint following the same syntax as the SOQL where clause.
For example: my_field__c LIKE 'foo%' AND RecordType='bar'

184

Reference

Search Suggested Records

Parameter

Description
This expression needs to be properly URL encoded. Cant be used for Question
object.

Usage
The suggestions resource returns records when the records name field includes the exact text in the search string. The last term in the
search string can match the beginning of a word. Records that contain the search string within a word arent considered a match.
Note: If the users search query contains quotation marks or wildcards, those symbols are automatically removed from the query
string in the URI.
Example: The text string national u is treated as national u* and returns National Utility, National Urban Company,
and First National University.

Suggested Records Response

The suggestions resource returns display-ready data about likely relevant records that the user can access.
The order of results is determined by a relevance algorithm.
Each suggested record in the results contains these elements:
Element

Description

Attributes

The records object type and the URL for accessing the record.
Also includes the requested lookup fields values. For example, if you requested
fields=Id,Name, the result would include the ID and name.

Name (or Title)

The records Name field. In the absence of a standard Name field, the Title field is used
for these objects:
Dashboard
Idea
IdeaTheme
Note
Question
In the absence of a standard Name or Title field, the main identifying field is used. For
example, in cases, the Case Number is used.

The records unique identifier.

Example JSON Response Body

[ {
"attributes" : {
"type" : "Account",
"url" : "/services/data/v32.0/sobjects/Account/001xx000003DH6WAAW"

185

Reference

Search Suggested Records

},
"Id" : "001xx000003DH6WAAW"
"Name" : "National Utility Service"
}, {
{
"attributes" : {
"type" : "Account",
"url" : "/services/data/v32.0/sobjects/Account/001xx000003DHJ4AAO"
},
"Id" : "001xx000003DHJ4AAO"
"Name" : "National Utility Service"
}, {
{
"attributes" : {
"type" : "Account",
"url" : "/services/data/v32.0/sobjects/Account/001xx000003DHscAAG"
},
"Id" : "001xx000003DHscAAG"
"Name" : "National Urban Technology Center"
} ]

Example JSON Response Body for a Multiple Object Request

[ {
"attributes" : {
"type" : "Account",
"url" : "/services/data/v38.0/sobjects/Account/001xx000003DMEKAA4"
},
"Id" : "001xx000003DMEKAA4"
"Name" : "Joe Doe Printing"
}, {
{
"attributes" : {
"type" : "Account",
"url" : "/services/data/v38.0/sobjects/Account/001xx000003DLjvAAG"
},
"Id" : "001xx000003DLjvAAGO"
"Name" : "Joe Doe Plumbing"
}, {
{
"attributes" : {
"type" : "Contact",
"url" : "/services/data/v38.0/sobjects/Contact/003xx000004U9Y9AAK"
},
"Id" : "003xx000004U9Y9AAK"
"Name" : "John Doe"
} ]

Example XML Response Body

<?xml version=1.0 encoding=UTF-8?
<suggestions>

186

Reference

Search Suggested Article Title Matches

<autoSuggestResults type="Account"
url="/services/data/v32.0/sobjects/Account/001xx000003DH6WAAW">
<Id>001xx000003DH6WAAW</Id>
<Name>National Utility Service</Name>
</autoSuggestResults>
<autoSuggestResults type="Account"
url="/services/data/v32.0/sobjects/Account/001xx000003DHJ4AAO">
<Id>001xx000003DHJ4AAO</Id>
<Name>National Utility Service</Name>
</autoSuggestResults>
<autoSuggestResults type="Account"
url="/services/data/v32.0/sobjects/Account/001xx000003DHscAAG">
<Id>001xx000003DHscAAG</Id>
<Name>National Urban Technology Center</Name>
</autoSuggestResults>
<hasMoreResults>true</hasMoreResults>
</suggestions>

Unsupported Objects
The suggestions resource supports all searchable objects except the following.
ContentNote
Event
FeedComment
FeedPost
IdeaComment
Pricebook2
Reply
TagDefinition
Task

Search Suggested Article Title Matches

Returns a list of Salesforce Knowledge article titles that match the users search query string. Provides a shortcut to navigate directly to
likely relevant articles before the user performs a search.

Syntax
URI
/vXX.X/search/suggestTitleMatches?q=search string&language=article
language&publishStatus=article publication status

Available since release

30.0
Formats
JSON, XML

187

Reference

Search Suggested Article Title Matches

HTTP methods
GET
Authentication
Authorization: Bearer token

Request body
None required
Request parameters
Parameter

Description

articleTypes

Search Suggested Article Title Matches

Parameter

Description

limit

Optional. Specifies the maximum number of articles to return. If there are more
suggested articles than the limit specified, the response bodys hasMoreResults
property is true.

publishStatus

Required. The articles publication status. Valid values:

DraftArticles arent published in Salesforce Knowledge.
OnlineArticles are published in Salesforce Knowledge.
ArchivedArticles arent published and are available in Archived Articles view.

Required. The users search query string, properly URL-encoded. Suggestions are
returned only if the users query string meets the minimum length requirements: one
character for queries in Chinese, Japanese, and Korean, and three characters for all
other languages. Query strings exceeding the maximum length of 250 characters return
an error.

topics

Optional. The topic of the returned articles. For example:

topics=outlook&topics=email.

validationStatus

Optional. The validation status of returned articles.

Example for getting suggested articles with matching titles

curl https://yourInstance.salesforce.com/services/data/v30.0/search/suggestTitleMatches?
q=orange+banana&language=en_US&publishStatus=Online -H "Authorization: Bearer token"

Example JSON response body

{
"autoSuggestResults" : [ {
"attributes" : {
"type" : "KnowledgeArticleVersion",
"url" : "/services/data/v30.0/sobjects/KnowledgeArticleVersion/ka0D00000004CcQ"
},
"Id" : "ka0D00000004CcQ",
"UrlName" : "orange-banana",
"Title" : "orange banana",
"KnowledgeArticleId" : "kA0D00000004Cfz"
} ],
"hasMoreResults" : false
}

189

Reference

Search Suggested Queries

The Suggest Article Title Matches resource is designed to return display-ready data about likely relevant articles. Articles are suggested
if their titles contain the entire query string, except stopwords, such as a, for, and the.
For example, a search for Backpacking for desert returns the article, Backpacking in the desert.
Note: Articles with titles that include stopwords from the query string, such as Backpacking for desert survival in this example,
appear before matching articles with titles that dont include the stopwords.
Stopwords at the end of the query string are treated as search terms.
A wildcard is automatically appended to the last token in the query string.
Note: If the users search query contains quotation marks or wildcards, those symbols are automatically removed from the query
string in the URI along with any other special characters.
If the number of suggestions returned exceeds the limit specified in the request, the end of the response contains a field called
hasMoreResults. Its value is true if the suggestions returned are only a subset of the suggestions available, and false otherwise.
SEE ALSO:
SObject Suggested Articles

Search Suggested Queries

Returns a list of suggested searches based on the users query string text matching searches that other users have performed in Salesforce
Knowledge. Provides a way to improve search effectiveness, before the user performs a search.

Syntax
URI
vXX.X/search/suggestSearchQueries?q=search string&language=language of query

Available since release

30.0
Formats
JSON, XML
HTTP methods
GET
Authentication
Authorization: Bearer token

Request body
None required
Request parameters
Parameter

Description

channel

Optional. Specifies the Salesforce Knowledge channel where the article can be viewed.
Valid values:
AllChannelsVisible in all channels the user has access to
AppVisible in the internal Salesforce Knowledge application

190

Reference

Search Suggested Queries

Parameter

Description
PkbVisible in the public knowledge base
CspVisible in the Customer Portal
PrmVisible in the Partner Portal
If channel isnt specified, the default value is determined by the type of user.
Pkb for a guest user
Csp for a Customer Portal user
Prm for a Partner Portal user
App for any other type of user
If channel is specified, the specified value may not be the actual value requested,
because of certain requirements.
For guest, Customer Portal, and Partner Portal users, the specified value must match
the default value for each user type. If the values dont match or AllChannels
is specified, then App replaces the specified value.
For all users other than guest, Customer Portal, and Partner Portal users:
If Pkb, Csp, Prm, or App are specified, then the specified value is used.
If AllChannels is specified, then App replaces the specified value.

language

Required. The language of the users query.

limit

Optional. Specifies the maximum number of suggested searches to return. If there are
more suggested queries than the limit specified, the response bodys
hasMoreResults property is true.

Required. The users search query string, properly URL-encoded. Suggestions are
returned only if the users query string meets the minimum length requirements: one
character for queries in Chinese, Japanese, and Korean, and three characters for all
other languages. Query strings exceeding the maximum length of 250 characters return
an error.

Example for getting suggested queries

curl https://yourInstance.salesforce.com/services/data/v30.0/search/suggestSearchQueries?
q=app&language=en_US -H "Authorization: Bearer token"

Example JSON response body

{
"autoSuggestResults" : [ {
"0" : "apple",
"1" : "apple banana",
} ],
"hasMoreResults" : false
}

191

Reference

Tabs

Usage
Salesforce Knowledge must be enabled in your organization.
Queries are suggested if they exactly match the query string text. The text string must be a prefix within the query; its not considered
a match if it appears within a word. For example, the text string app would return suggested queries apple banana and banana apples
but not pineapple.
If the number of suggestions returned exceeds the limit specified in the request, the end of the response contains a field called
hasMoreResults. Its value is true if the suggestions returned are only a subset of the suggestions available, and false otherwise.
If the users search query contains quotation marks or wildcards, those symbols are automatically removed from the query string in the
URI.

Tabs
Returns a list of all tabsincluding Lightning Page tabsavailable to the current user, regardless of whether the user has chosen to
hide tabs via the All Tabs (+) tab customization feature. This resource is available in REST API version 31.0 and later.

Syntax
URI
/vXX.X/tabs/

Formats
JSON, XML
HTTP methods
GET, HEAD
Authentication
Authorization: Bearer token

Request body
None
Request parameters
None

Example
Usage for getting tabs
/services/data/v31.0/tabs

Sample JSON Response body for /vXX.X/tabs/

This is a partial code sample, representing the Accounts tab.
[...,
"colors" : [ {
"color" : "6f7ccb",
"context" : "primary",
"theme" : "theme4"
}, {
"color" : "236FBD",

192

Reference

Themes

"context" : "primary",
"theme" : "theme3"
} ],
"custom" : false,
"iconUrl" : "https://yourInstance.salesforce.com/img/icon/accounts32.png",
"icons" : [ {
"contentType" : "image/png",
"height" : 32,
"theme" : "theme3",
"url" : "https://yourInstance.salesforce.com/img/icon/accounts32.png",
"width" : 32
}, {
"contentType" : "image/png",
"height" : 16,
"theme" : "theme3",
"url" : "https://yourInstance.salesforce.com/img/icon/accounts16.png",
"width" : 16
}, {
"contentType" : "image/svg+xml",
"height" : 0,
"theme" : "theme4",
"url" : "https://yourInstance.salesforce.com/img/icon/t4/standard/account.svg",
"width" : 0
}, {
"contentType" : "image/png",
"height" : 60,
"theme" : "theme4",
"url" : "https://yourInstance.salesforce.com/img/icon/t4/standard/account_60.png",
"width" : 60
}, {
"contentType" : "image/png",
"height" : 120,
"theme" : "theme4",
"url" : "https://yourInstance.salesforce.com/img/icon/t4/standard/account_120.png",
"width" : 120
} ],
"label" : "Accounts",
"miniIconUrl" : "https://yourInstance.salesforce.com/img/icon/accounts16.png",
"name" : "standard-Account",
"sobjectName" : "Account",
"url" : "https://yourInstance.salesforce.com/001/o",
...]

Themes
Gets the list of icons and colors used by themes in the Salesforce application. Theme information is provided for objects in your organization
that use icons and colors in the Salesforce UI.

193

Reference

Themes

The If-Modified-Since header can be used with this resource, with a date format of EEE, dd MMM yyyy HH:mm:ss
z. When this header is used, if the object metadata has not changed since the provided date, a 304 Not Modified status code
is returned, with no response body.

Syntax
URI
/vXX.X/theme

Available since release

29.0
Formats
JSON, XML
HTTP methods
GET
Authentication
Authorization: Bearer token

Request body
None
Request parameters
None
Response data
An array of theme items. Each theme item contains the following fields:
Name

Type

Description

colors

array of theme colors

Array of theme colors.

icons

array of theme icons

Array of theme icons.

name

string

Name of the object that the theme colors and icons are associated with.

Each theme color contains the following fields:

Name

Type

Description

color

string

The color described in Web color RGB format, for example, 00FF00.

context

string

The color context, which determines whether the color is the main color
(primary) for the object, or not.

theme

string

The associated theme. Possible values include:

theme2Theme used prior to Spring 10, called the Salesforce Classic
2005 user interface theme
theme3Theme introduced in Spring 10, called the Salesforce Classic
2010 user interface theme
theme4Theme introduced in Winter 14 for the mobile touchscreen
version of Salesforce, and in Winter 16 for Lightning Experience

194

Reference

Themes

Name

Type

Description
customTheme associated with a custom icon

Each theme icon contains the following fields:

Name

Type

Description

contentType

string

The icons content type, for example, image/png.

height

number

The icons height in pixels. If the icon content type is an SVG type, height and
width values are not used.

theme

string

The associated theme. Possible values include:

url

string

The fully qualified URL for this icon.

width

number

The icons width in pixels. If the icon content type is an SVG type, height and
width values are not used.

Example
The following is an example JSON response using a request of services/data/v29.0/theme:
{
"themeItems" : [
{
"name" : "Merchandise__c",
"icons" : [
{
"contentType" : "image/png",
"width" : 32,
"url" : "https://yourInstance.salesforce.com/img/icon/computer32.png",
"height" : 32,
"theme" : "theme3"
},
{
"contentType" : "image/png",
"width" : 16,
"url" : "https://yourInstance.salesforce.com/img/icon/computer16.png",
"height" : 16,
"theme" : "theme3"
} ],

195

Reference

Composite Resources

"colors" : [
{
"context"
"color" :
"theme" :
},
{
"context"
"color" :
"theme" :
},

: "primary",
"6666CC",
"theme3"

: "primary",
"66895F",
"theme4"

...
}
...
}

Composite Resources
Use REST API composite resources to improve your applications performance by minimizing the number of round-trips between the
client and server.

Batch
Executes up to 25 subrequests in a single request. The response bodies and HTTP statuses of the subrequests in the batch are returned
in a single response body. Each subrequest counts against rate limits.
The requests in a batch are called subrequests. All subrequests are executed in the context of the same user. Subrequests are independent,
and you cant pass information between them. Subrequests execute serially in their order in the request body. When a subrequest
executes successfully, it commits its data. Commits are reflected in the output of later subrequests. If a subrequest fails, commits made
by previous subrequests are not rolled back. If a batch request doesnt complete within 10 minutes, the batch times out and the remaining
subrequests arent executed.
Batching for the following resources and resource groups is available in API version 34.0 and later.
LimitsvXX.X/limits
SObject resourcesvXX.X/sobjects/
QueryvXX.X/query/?q=soql
QueryAllvXX.X/queryAll/?q=soql
SearchvXX.X/search/?q=sosl
Connect resourcesvXX.X/connect/
Chatter resourcesvXX.X/chatter/
Batching for the following resources and resource groups is available in API version 35.0 and later.
ActionsvXX.X/actions
The API version of the resource accessed in each subrequest must be no earlier than 34.0 and no later than the Batch version in the
top-level request. For example, if you post a Batch request to /services/data/v35.0/composite/batch, you can include
subrequests that access version 34.0 or 35.0 resources. But if you post a Batch request to
/services/data/v34.0/composite/batch, you can only include subrequests that access version 34.0 resources.

196

Reference

Batch

URI
/vXX.X/composite/batch

Formats
JSON, XML
HTTP method
POST
Authentication
Authorization: Bearer token

Parameters
None required
Request body
Batch Request Body on page 197
Response body
Batch Response Body on page 199
Examples
For an example of using the Batch resource, see Update a Record and Get Its Field Values in a Single Request on page 88.

Batch Request Body

Describes a collection of subrequests to execute with the Batch resource.

Batch Collection Input

The request body contains a batchRequests collection that includes subrequests to execute.
Properties
Name

Type

Description

Required or
Optional

batchRequests

Subrequest[]

Collection of subrequests to execute.

Required

haltOnError

Boolean

The default is false.

Optional

If the value is false and a subrequest in the batch doesnt

complete, Salesforce attempts to execute the subsequent
subrequests in the batch.
If the value is true and a subrequest in the batch doesnt
complete due to an HTTP response in the 400 or 500 range,
Salesforce halts execution. It returns an HTTP 412 status code
and a BATCH_PROCESSING_HALTED error message for
each subsequent subrequest. The top-level request to
/composite/batch returns HTTP 200, and the
hasErrors property in the response is set to true.

Root XML Tag

<batch>

197

Reference

Batch

JSON example
{
"batchRequests" : [
{
"method" : "PATCH",
"url" : "v34.0/sobjects/account/001D000000K0fXOIAZ",
"richInput" : {"Name" : "NewName"}
},{
"method" : "GET",
"url" : "v34.0/sobjects/account/001D000000K0fXOIAZ?fields=Name,BillingPostalCode"
}]
}

Subrequest
Contains the resource, method, and accompanying information for the subrequest.
Properties
Name

Type

Description

Required or
Optional

binaryPartName

String

The name of the binary part in the multipart request.

Optional

When multiple binary parts are uploaded in one batch request,

this value is used to map a request to its binary part. To prevent
name collisions, use a unique value for each
binaryPartName property in a batch request.
If this value exists, a binaryPartNameAlias value must
also exist.
binaryPartNameAlias String

The name parameter in the Content-Disposition header of the Optional

binary body part. Different resources expect different values. See
Insert or Update Blob Data.
If this value exists, a binaryPartName value must also exist.

method

String

The method to use with the requested resource. For a list of valid Required
methods, refer to the documentation for the requested resource.
The input body for the request.

richInput

Optional

The type depends on the request specified in the url property.

url

String

The resource to request.

The URL can include any query string parameters that the
subrequest supports. The query string must be URL-encoded.
You can use parameters to filter response bodies.
You cannot apply headers at the subrequest level.

198

Required

Reference

Batch

Root XML Tag

JSON example
{
"method" : "GET",
"url" : "v34.0/sobjects/account/001D000000K0fXOIAZ?fields=Name,BillingPostalCode"
}

SEE ALSO:
Batch
Update a Record and Get Its Field Values in a Single Request

Batch Response Body

Describes the result of a Batch request.

Batch Results
Properties
Name

Type

Description

hasErrors

Boolean

true if at least one of the results in the result set is an HTTP status code
in the 400 or 500 range; false otherwise.

results

Subrequest Result[]

Collection of subrequest results.

JSON example
{
"hasErrors" : false,
"results" : [{
"statusCode" : 204,
"result" : null
},{
"statusCode" : 200,
"result": {
"attributes" : {
"type" : "Account",
"url" : "/services/data/v34.0/sobjects/Account/001D000000K0fXOIAZ"
},
"Name" : "NewName",
"BillingPostalCode" : "94105",
"Id" : "001D000000K0fXOIAZ"
}
}]
}

199

Reference

SObject Tree

Subrequest Result
Properties
Name

Type

Description

result

The type depends on the The response body of this subrequest.

response type of the
subrequest.
Important: If the
result is an error,
the type is a
collection
containing the
error message and
error code.

statusCode

Integer

An HTTP status code indicating the status of this subrequest.

JSON example
{
"attributes" : {
"type" : "Account",
"url" : "/services/data/v34.0/sobjects/Account/001D000000K0fXOIAZ"
},
"Name" : "NewName",
"BillingPostalCode" : "94015",
"Id" : "001D000000K0fXOIAZ"
}

SEE ALSO:
Batch
Update a Record and Get Its Field Values in a Single Request

SObject Tree
Creates one or more sObject trees with root records of the specified type. An sObject tree is a collection of nested, parent-child records
with a single root record.
In the request data, you supply the record hierarchies, required and optional field values, each records type, and a reference ID for each
record. Upon success, the response contains the IDs of the created records. If an error occurs while creating a record, the entire request
fails. In this case, the response contains only the reference ID of the record that caused the error and the error information.
The request can contain the following:
Up to a total of 200 records across all trees
Up to five records of different types
SObject trees up to five levels deep
Because an sObject tree can contain a single record, you can use this resource to create up to 200 unrelated records of the same type.

200

Reference

SObject Tree

When the request is processed and records are created, triggers, processes, and workflow rules fire separately for each of the following
groups of records.
Root records across all sObject trees in the request
All second-level records of the same typefor example, second-level Contacts across all sObject trees in the request
All third-level records of the same type
All fourth-level records of the same type
All fifth-level records of the same type
URI
/vXX.X/composite/tree/SObjectName

Formats
JSON, XML
HTTP method
POST
Authentication
Authorization: Bearer token

Parameters
None required
Request body
SObject Tree Request Body on page 201
Response body
SObject Tree Response Body on page 204
Examples
For an example of creating unrelated records of the same type, see Create Multiple Records on page 90.
For an example of creating nested records, see Create Nested Records on page 89.

SObject Tree Request Body

Describes a collection of sObject trees to create with the SObject Tree resource.

SObject Tree Collection Input

The request body contains a records collection that includes sObject trees.
Properties
Name

Type

Description

records

SObject Tree Input[]

Collection of record trees to create. Each trees Required

root record type must correspond to the sObject
specified in the SObject Tree URI.

Root XML Tag

201

Required or
Optional

Reference

SObject Tree

JSON example
{
"records" :[{
"attributes" : {"type" : "Account", "referenceId" : "ref1"},
"name" : "SampleAccount",
"phone" : "1234567890",
"website" : "www.salesforce.com",
"numberOfEmployees" : "100",
"industry" : "Banking",
"Contacts" : {
"records" : [{
"attributes" : {"type" : "Contact", "referenceId" : "ref2"},
"lastname" : "Smith",
"title" : "President",
"email" : "[email protected]"
},{
"attributes" : {"type" : "Contact", "referenceId" : "ref3"},
"lastname" : "Evans",
"title" : "Vice President",
"email" : "[email protected]"
}]
}
},{
"attributes" : {"type" : "Account", "referenceId" : "ref4"},
"name" : "SampleAccount2",
"phone" : "1234567890",
"website" : "www.salesforce2.com",
"numberOfEmployees" : "100",
"industry" : "Banking"
}]
}

XML example
<SObjectTreeRequest>
<records type="Account" referenceId="ref1">
<name>SampleAccount</name>
<phone>1234567890</phone>
<website>www.salesforce.com</website>
<numberOfEmployees>100</numberOfEmployees>
<industry>Banking</industry>
<Contacts>
<records type="Contact" referenceId="ref2">
<lastname>Smith</lastname>
<title>President</title>
<email>[email protected]</email>
</records>
<records type="Contact" referenceId="ref3">
<lastname>Evans</lastname>
<title>Vice President</title>
<email>[email protected]</email>
</records>
</Contacts>
</records>

202

Reference

SObject Tree

<records type="Account" referenceId="ref4">

<name>SampleAccount2</name>
<phone>1234567890</phone>
<website>www.salesforce2.com</website>
<numberOfEmployees>100</numberOfEmployees>
<industry>Banking</industry>
</records>
</SObjectTreeRequest>

SObject Tree Input

An sObject tree is a recursive data structure that contains a root record, its data, and its child records represented as other sObject trees.
Properties
Name

Type

Description

Required or
Optional

attributes

Collection

Attributes for this record. The attributes property contains Required

two subproperties:
type (required)This records type.
referenceId (required)Reference ID for this record.
Must be unique in the context of the request and start with
an alphanumeric character.
In XML, include attributes inside the records element.

Required object fields

Depends on
field

Required fields and field values for this record.

Required

Optional object fields

Depends on
field

Optional fields and field values for this record.

Optional

Child relationships

SObject Tree
Collection
Input

This records child relationships, such as an accounts child

contacts. Child relationships are either master-detail or lookup
relationships. To view an objects valid child relationships, use
the SObject Describe resource or Schema Builder. The value of
this property is an SObject Tree Collection Input that contains
child sObject trees.

Optional

Root XML Tag

JSON example
{
"attributes" : {"type" : "Account", "referenceId" : "ref1"},
"name" : "SampleAccount",
"phone" : "1234567890",
"website" : "www.salesforce.com",
"NumberOfEmployees" : "100",
"industry" : "Banking",
"Contacts" : {

203

Reference

SObject Tree

"records" : [{
"attributes" : {"type" : "Contact", "referenceId" : "ref2"},
"lastname" : "Smith",
"title" : "President",
"email" : "[email protected]"
},{
"attributes" : {"type" : "Contact", "referenceId" : "ref3"},
"lastname" : "Evans",
"title" : "Vice President",
"email" : "[email protected]"
}]
}
}

XML example
<records type="Account" referenceId="ref1">
<name>SampleAccount</name>
<phone>1234567890</phone>
<website>www.salesforce.com</website>
<numberOfEmployees>100</numberOfEmployees>
<industry>Banking</industry>
<Contacts>
<records type="Contact" referenceId="ref2">
<lastname>Smith</lastname>
<title>President</title>
<email>[email protected]</email>
</records>
<records type="Contact" referenceId="ref3">
<lastname>Evans</lastname>
<title>Vice President</title>
<email>[email protected]</email>
</records>
</Contacts>
</records>

SEE ALSO:
SObject Tree
Create Multiple Records
Create Nested Records

SObject Tree Response Body

Describes the result of an SObject Tree request.
Properties
Name

Type

Description

hasErrors

Boolean

true if an error occurred while creating a record; false otherwise.

results

Collection

Upon success, results contains the reference ID of each requested

record and its new record ID. Upon failure, it contains only the reference

204

Reference

SObject Tree

Name

Type

Description
ID of the record that caused the error, error status code, error message,
and fields related to the error. In the case of duplicate reference IDs,
results contains one item for each instance of the duplicate ID.

JSON example upon success

XML example upon success

<?xml version="1.0" encoding="UTF-8"?>
<SObjectTreeResponse>
<hasErrors>false</hasErrors>
<results>
<id>001D000000K0fXOIAZ</id>
<referenceId>ref1</referenceId>
</results>
<results>
<id>001D000000K0fXPIAZ</id>
<referenceId>ref4</referenceId>
</results>
<results>
<id>003D000000QV9n2IAD</id>
<referenceId>ref2</referenceId>
</results>
<results>
<id>003D000000QV9n3IAD</id>
<referenceId>ref3</referenceId>
</results>
</SObjectTreeResponse>

JSON example upon failure

{
"hasErrors" : true,
"results" : [{
"referenceId" : "ref2",

205

Reference

Headers

"errors" : [{
"statusCode" : "INVALID_EMAIL_ADDRESS",
"message" : "Email: invalid email address: 123",
"fields" : [ "Email" ]
}]
}]
}

XML example upon failure

<SObjectTreeResponse>
<hasErrors>true</hasErrors>
<results>
<errors>
<fields>Email</fields>
<message>Email: invalid email address: 123</message>
<statusCode>INVALID_EMAIL_ADDRESS</statusCode>
</errors>
<referenceId>ref2</referenceId>
</results>
</SObjectTreeResponse>

SEE ALSO:
SObject Tree
Create Multiple Records
Create Nested Records

Headers
This section lists custom HTTP request and response headers used for REST API.
IN THIS SECTION:
Assignment Rule Header
The Assignment Rule header is a request header applied when creating or updating Cases or Leads. If enabled, the active assignment
rules are used. If disabled, the active assignment rules are not applied. If a valid AssignmentRule ID is provided, the AssignmentRule
is applied. If the header is not provided with a request, REST API defaults to using the active assignment rules.
Call Options Header
Specifies the client-specific options when accessing REST API resources. For example, you can write client code that ignores namespace
prefixes by specifying the prefix in the call options header.
Limit Info Header
This response header is returned in each request to the REST API. You can use the information to monitor API limits.
Package Version Header
Specifies the version of each package referenced by a client. A package version is a number that identifies the set of components
and behavior contained in a package. This header can also be used to specify a package version when making calls to an Apex REST
web service.
Query Options Header
Specifies options used in a query, such as the query results batch size. Use this request header with the Query resource.

206

Reference

Assignment Rule Header

The Assignment Rule header is a request header applied when creating or updating Cases or Leads. If enabled, the active assignment
rules are used. If disabled, the active assignment rules are not applied. If a valid AssignmentRule ID is provided, the AssignmentRule is
applied. If the header is not provided with a request, REST API defaults to using the active assignment rules.

Header Field Name and Values

Field name
Sforce-Auto-Assign

Field values
TRUE. Active assignment rules are applied for created or updated Cases or Leads.
FALSE. Active assignment rules are not applied for created or updated Cases or Leads.
Valid AssignmentRule ID. The given AssignmentRule is applied for created Cases or Leads.
TRUE and FALSE are not case-sensitive.

If the header is not provided in the request, the default value is TRUE.
Example
Sforce-Auto-Assign: FALSE

Call Options Header

Specifies the client-specific options when accessing REST API resources. For example, you can write client code that ignores namespace
prefixes by specifying the prefix in the call options header.
The Call Options header can be used with SObject Basic Information, SObject Rows, Query, QueryAll, Search, and SObject Rows by External
ID.

Header Field Name and Values

Field name
Sforce-Call-Options

Field values
clientA string that identifies a client.
defaultNamespaceA string that identifies a developer namespace prefix. Resolve field names in managed packages
without having to specify the namespace everywhere.
Example
If the developer namespace prefix is battle, and you have a custom field called botId in a package, set the default namespace
with the call options header:
Sforce-Call-Options: client=SampleCaseSensitiveToken/100, defaultNamespace=battle

Then queries such as the following succeed:

/vXX.X/query/?q=SELECT+Id+botID__c+FROM+Account

In this case the actual field queried is the battlebotIdc field.

207

Reference

Limit Info Header

Using this header allows you to write client code without having to specify the namespace prefix. In the previous example, without
the header you must write battle__botId__c.
If this field is set, and the query also specifies the namespace, the response doesnt include the prefix. For example, if you set this
header to battle, and issue a query like SELECT+Id+battle__botID__c+FROM+Account, the response uses a
botId__c element, not a battle_botId__c element.
The defaultNamespace field is ignored when retrieving describe information, which avoids ambiguity between namespace
prefixes and customer fields of the same name.

Limit Info Header

This response header is returned in each request to the REST API. You can use the information to monitor API limits.

Header Field Name and Values

Field name
Sforce-Limit-Info

Field values
api-usageSpecifies the API usage for the organization against which the call was made in the format nn/nnnn. The first
number is the number of API calls used, and the second number is the API limit for the organization.
per-app-api-usageSpecifies the limit quota information for the currently connected app. API limit app quotas are
currently available through a pilot program. For information on enabling this feature for your organization, contact Salesforce.
This example includes the limit quota for a sample-connected-app connected app. If there is no limit quota information,
this field isnt returned.
Sforce-Limit-Info: api-usage=25/5000;
per-app-api-usage=17/250(appName=sample-connected-app)

Example
Response to a REST request for a Merchandise record, including the limit information in line three:
HTTP/1.1 200 OK
Date: Mon, 20 May 2013 22:21:46 GMT
Sforce-Limit-Info: api-usage=18/5000
Last-Modified: Mon, 20 May 2013 20:49:32 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
{
"attributes" : {
"type" : "Merchandise__c",
"url" : "/services/data/v38.0/sobjects/Merchandise__c/a00D0000008pQSNIA2"
},
"Id" : "a00D0000008pQSNIA2",
"OwnerId" : "005D0000001QX8WIAW",
"IsDeleted" : false,
"Name" : "Phone Case - iPhone 4/4S",
"CreatedDate" : "2013-05-20T20:49:32.000+0000",
"CreatedById" : "005D0000001QX8WIAW",
"LastModifiedDate" : "2013-05-20T20:49:32.000+0000",
"LastModifiedById" : "005D0000001QX8WIAW",

208

Reference

Package Version Header

"SystemModstamp" : "2013-05-20T20:49:32.000+0000",
"LastActivityDate" : null,
"LastViewedDate" : "2013-05-20T22:19:56.000+0000",
"LastReferencedDate" : "2013-05-20T22:19:56.000+0000",
"Description__c" : "Phone Case for iPhone 4/4S",
"Price__c" : 16.99,
"Stock_Price__c" : 12.99,
"Total_Inventory__c" : 108.0
}

Package Version Header

Specifies the version of each package referenced by a client. A package version is a number that identifies the set of components and
behavior contained in a package. This header can also be used to specify a package version when making calls to an Apex REST web
service.
The Package Version header can be used with the following resources: Describe Global, SObject Describe, SObject Basic Information,
SObject Rows, Describe Layouts, Query, QueryAll, Search, and SObject Rows by External ID.

Header Field Name and Values

Field name and value
x-sfdc-packageversion-[namespace]: xx.x, where [namespace] is the unique namespace of the managed
package and xx.x is the package version.

Example
x-sfdc-packageversion-clientPackage: 1.0

Query Options Header

Specifies options used in a query, such as the query results batch size. Use this request header with the Query resource.

Header Field Name and Values

Field name
Sforce-Query-Options

Field values
batchSizeA numeric value that specifies the number of records returned for a query request. Child objects count toward
the number of records for the batch size. For example, in relationship queries, multiple child objects are returned per parent row
returned.
The default is 2,000; the minimum is 200, and the maximum is 2,000. There is no guarantee that the requested batch size is the
actual batch size. Changes are made as necessary to maximize performance.
Example
Sforce-Query-Options: batchSize=1000

209

Reference

Status Codes and Error Responses

Either when an error occurs or when a response is successful, the response header contains an HTTP code, and the response body usually
contains:
The HTTP response code
The message accompanying the HTTP response code
The field or object where the error occurred (if the response returns information about an error)
HTTP response
code

Description

200

OK success code, for GET or HEAD request.

201

Created success code, for POST request.

204

No Content success code, for DELETE request.

300

The value returned when an external ID exists in more than one record. The response body contains the list
of matching records.

304

The request content has not changed since a specified date and time. The date and time is provided in a
If-Modified-Since header. See Get Object Metadata Changes for an example.

400

The request couldnt be understood, usually because the JSON or XML body contains an error.

401

The session ID or OAuth token used has expired or is invalid. The response body contains the message and
errorCode.

403

The request has been refused. Verify that the logged-in user has appropriate permissions.

404

The requested resource couldnt be found. Check the URI for errors, and verify that there are no sharing issues.

405

The method specified in the Request-Line isnt allowed for the resource specified in the URI.

415

The entity in the request is in a format thats not supported by the specified method.

500

An error has occurred within Force.com, so the request couldnt be completed. Contact Salesforce Customer
Support.

Incorrect ID example
Using a non-existent ID in a request using JSON or XML (request_body.json or request_body.xml)
{
"fields" : [ "Id" ],
"message" : "Account ID: id value of incorrect type: 001900K0001pPuOAAU",
"errorCode" : "MALFORMED_ID"
}

Resource does not exist

Requesting a resource that doesnt exist, for example, if you try to create a record using a misspelled object name
{
"message" : "The requested resource does not exist",

210

Reference

Status Codes and Error Responses

"errorCode" : "NOT_FOUND"
}

211

INDEX
A

Describe Global 3839, 99

AppMenu 120
ApprovalLayouts 106
Approvals 171
Assignment Rule Header 207
Authentication
Additional resources 19
OAuth 56, 12, 15, 17
OAuth endpoints 6
Remote access applications 6

B
base URI 2
base64 content 56
Batch 88, 196
Batch Request Body 197
Batch Response Body 199
Blob
insert blob data 57
update blob data 57
Bulk approval 80

C
Call Options Header 207
Compact Layouts for Multiple Objects 124
CompactLayouts 107
Composite 196, 200
Composite Resources 196
Compression
deflate 3
gzip 3
Conditional Requests
ETag 4
If-Match 4
If-Modified-Since 4
If-None-Match 4
If-Unmodified-Since 4
CORS 20
Create 43, 8990
cURL 5, 2122, 26
Custom Invocable Actions 133

D
date-time 2
Delete record 45

Error responses 210

F
Field values
retrieving from a standard object 45
retrieving from an external object 46
FlexiPage 126

G
Get
base64 field content 56

H
Headers
Assignment Rule 207
Call Options 207
If-Modified-Since 39, 42
Limit Info 208
Package Version 209
Query Options 209

I
If-Modified-Since Header 39, 42
Insert
blob data 57
Invocable Actions 129
Invocable Actions Custom 133
Invocable Actions Standard 131

J
JavaScript 20
JSON 2, 2122

L
Layouts
Named layouts 103
Limit Info Header 208
Limits 35, 98
List REST resources 37
List View Describe 135
List View Results 138
List Views 147

212

Index

N
Named layouts 103

O
OAuth
access token 21
Additional resources 19
OAuth 2.0 2
Refresh token 17
User-agent OAuth flow 12
Username-password OAuth flow 15
Web server OAuth flow 6
Object metadata retrieval 40
Organization 22

P
Package Version Header 209
Password management 76, 119
PATCH
creating records with 43
PlatformAction 114
POST
creating multiple records with 90
creating nested records with 89
Process 171172
Process approvals 7879
Process rule metadata 82
Process rules 8182

Q
Query
explain parameter 65
Query Options Header 209
Query that includes deleted items 64
QueryAll 64, 175
Quick Actions
Layouts 112
QuickActions 115, 176
quickstart
prerequisites 22
Quickstart
access token 22
Developer Edition 22
OAuth 22

Recent List Views 177

Reject approval 79
Relationship fields 51, 116
Relevant Items
View relevant records 72
Request bodies
Batch Request Body 197
SObject Tree Request Body 201
Resource list by version 98
Resources
SObject upsert 105
upsert 47
Response bodies
Batch Response Body 199
SObject Tree Response Body 204
REST
architecture 2
cache 2
Examples for approval processes and process rules 77
Examples for getting object metadata 39
Examples for getting organization information 34
Examples for managing user passwords 75
Examples for searching and queries 62
Examples for using composite resources 87
Examples for using event log files 32, 83
Examples for working with recently viewed information 74
Examples for working with records 42
Examples of using resources 33
gateway 2
proxy server 2
resources 2
stateless 2
REST API 1
REST resources
Describe Global Resource 21, 26
Discovery Resource 21, 26
list of REST resources 93
PATCH 21, 26
Query 21, 26
SObject Basic Information 21, 26
SObject Describe 21, 26
SObject Row 21, 26
Versions 21, 26
REST resources list 37
Retrieve object metadata 40
Retrieving field values 4546
Retrieving records using external IDs 47

Recent Items
Mark recently viewed records 75
View recently viewed records 74

213

Index

S
Salesforce Knowledge
knowledgeManagement/settings 180
Search
Layouts 70
suggestedSearchQueries 190
suggestions 183
suggestTitleMatches 187
SObject
ApprovalLayouts 106
CompactLayouts 107
QuickActions 112, 115
relationships 116
SuggestedArticles 117
SObject Basic Information 100
SObject Blob Retrieve 105
SObject Describe 40, 42, 85, 100
SObject Get Deleted 60, 8587, 101
SObject Get Updated 61, 102
SObject Row 44, 104
SObject Tree 200
SObject Tree Request Body 201
SObject Tree Response Body 204
SObject upsert 105
SObject user
password 119
Standard Invocable Actions 131

Status codes 210

Suggested Article Titles 187
Suggested Articles
during case creation 117
Suggested Queries 190
Suggested Records 183

T
Tabs 192
Themes 193

U
Update
blob data 57
Upsert 47
Upsert, sObject 105
URI
base URI 2122, 26

V
Versions 34, 97

W
Workflow rules 172

X
XML 2

214

PHP 8 in Nutshell
No ratings yet
PHP 8 in Nutshell
6 pages
EDOCS DM 5.3.0 Installation Guide
100% (1)
EDOCS DM 5.3.0 Installation Guide
200 pages
STL Free
No ratings yet
STL Free
181 pages
Cooling Load Check Figure: (Based On The AIRAH Handbook 3rd Edition)
No ratings yet
Cooling Load Check Figure: (Based On The AIRAH Handbook 3rd Edition)
5 pages
REST API Developer Guide: Version 48.0, Spring '20
No ratings yet
REST API Developer Guide: Version 48.0, Spring '20
281 pages
The 30 Best VSCode Extensions You Need To Use in 2023
No ratings yet
The 30 Best VSCode Extensions You Need To Use in 2023
34 pages
CRUD REST API With Node - JS, Express, and PostgreS
No ratings yet
CRUD REST API With Node - JS, Express, and PostgreS
4 pages
1.1 Introduction To Data Science 1
No ratings yet
1.1 Introduction To Data Science 1
17 pages
Oops in C++: Ms. Niti Gupta
No ratings yet
Oops in C++: Ms. Niti Gupta
30 pages
Import Users in IBM Security Access Manager Using IBM Security Directory Integrator
No ratings yet
Import Users in IBM Security Access Manager Using IBM Security Directory Integrator
9 pages
Datastage Parellel Jobs PDF
No ratings yet
Datastage Parellel Jobs PDF
719 pages
PHP and MYSQL Interview Questions and Answers PART 1
No ratings yet
PHP and MYSQL Interview Questions and Answers PART 1
25 pages
Data Science in Spark With Sparklyr::: Cheat Sheet
No ratings yet
Data Science in Spark With Sparklyr::: Cheat Sheet
2 pages
MySQL Replication Tutorial
100% (6)
MySQL Replication Tutorial
114 pages
Acceleo User Guide
No ratings yet
Acceleo User Guide
56 pages
Opps Task
No ratings yet
Opps Task
2 pages
Full download Problem Solving with Algorithms and Data Structures Using Python SECOND EDITION Bradley N. Miller pdf docx
100% (1)
Full download Problem Solving with Algorithms and Data Structures Using Python SECOND EDITION Bradley N. Miller pdf docx
61 pages
Writing Mysql Scripts With PHP and Pdo: Paul Dubois
No ratings yet
Writing Mysql Scripts With PHP and Pdo: Paul Dubois
11 pages
Similar PHP Interview Questions
No ratings yet
Similar PHP Interview Questions
36 pages
Advance Python Sheet 1696337837
No ratings yet
Advance Python Sheet 1696337837
237 pages
Introduction To SQL Light
No ratings yet
Introduction To SQL Light
191 pages
Laravel Development Using Phpstorm: Prerequisites (Plugin Installation and Configuration)
No ratings yet
Laravel Development Using Phpstorm: Prerequisites (Plugin Installation and Configuration)
18 pages
PHP: Hypertext Preprocessing: Matt Murphy & Dublas Portillo
No ratings yet
PHP: Hypertext Preprocessing: Matt Murphy & Dublas Portillo
17 pages
Introduction To Python Programming: Dr. R. Rajeswara Rao Professor & Head Dept. of CSE Jntuk-Ucev Vizianagaram
No ratings yet
Introduction To Python Programming: Dr. R. Rajeswara Rao Professor & Head Dept. of CSE Jntuk-Ucev Vizianagaram
27 pages
SQL Case Study
No ratings yet
SQL Case Study
3 pages
C-Api in Python
No ratings yet
C-Api in Python
162 pages
Top 100 Python Interview Questions & Answers For 2021 - Edureka
No ratings yet
Top 100 Python Interview Questions & Answers For 2021 - Edureka
24 pages
Advance Python
No ratings yet
Advance Python
202 pages
Learning MySQL Language Structure
No ratings yet
Learning MySQL Language Structure
30 pages
Sencha Ext Js 5 Bootcamp in A Book Paperback
No ratings yet
Sencha Ext Js 5 Bootcamp in A Book Paperback
3 pages
File IO and Streams in Java
No ratings yet
File IO and Streams in Java
5 pages
Rust
No ratings yet
Rust
1 page
A Python Book - Beginning Python, Advanced Python, & Python Exercises PDF
No ratings yet
A Python Book - Beginning Python, Advanced Python, & Python Exercises PDF
227 pages
Instant download The New And Improved Flask Mega-Tutorial Miguel Grinberg pdf all chapter
100% (2)
Instant download The New And Improved Flask Mega-Tutorial Miguel Grinberg pdf all chapter
55 pages
Flask Docs
100% (1)
Flask Docs
300 pages
Revision Point - Series
No ratings yet
Revision Point - Series
5 pages
Lec #5 - Jquery Ajax
No ratings yet
Lec #5 - Jquery Ajax
5 pages
(eBook PDF) Murach's PHP and MySQL (3rd Edition) by Joel Murachinstant download
100% (5)
(eBook PDF) Murach's PHP and MySQL (3rd Edition) by Joel Murachinstant download
45 pages
PDF Software Architecture For Developerspdf
No ratings yet
PDF Software Architecture For Developerspdf
280 pages
Full Speed Python PDF
No ratings yet
Full Speed Python PDF
39 pages
Factory Method Design Pattern
No ratings yet
Factory Method Design Pattern
15 pages
Nodejs in Action PDF
0% (1)
Nodejs in Action PDF
198 pages
Kaushal
No ratings yet
Kaushal
77 pages
Let Us C Y Kanitkar 01 - First Few Pages
No ratings yet
Let Us C Y Kanitkar 01 - First Few Pages
7 pages
Yousef Udacity Deep Learning Part1 Introdution + Part 2 NN
No ratings yet
Yousef Udacity Deep Learning Part1 Introdution + Part 2 NN
437 pages
Introduction To Computer Programming Using Python Comp 111
No ratings yet
Introduction To Computer Programming Using Python Comp 111
227 pages
Programing With Java - Course 1
No ratings yet
Programing With Java - Course 1
152 pages
Flask
No ratings yet
Flask
302 pages
Pytest PDF
No ratings yet
Pytest PDF
193 pages
Pascal Notes
No ratings yet
Pascal Notes
118 pages
jsp3 Toc
No ratings yet
jsp3 Toc
11 pages
Golang For DevOps and Cloud Engineers-1
No ratings yet
Golang For DevOps and Cloud Engineers-1
57 pages
Learn GIT Using GITHUB in 5 Minutes
No ratings yet
Learn GIT Using GITHUB in 5 Minutes
33 pages
ColdFusion Interview Questions, Answers, and Explanations: ColdFusion Certification Review
From Everand
ColdFusion Interview Questions, Answers, and Explanations: ColdFusion Certification Review
equitypress
No ratings yet
Instant Razor View Engine How-to
From Everand
Instant Razor View Engine How-to
Abhimanyu Kumar Vatsa
No ratings yet
Alfresco 3 Cookbook
From Everand
Alfresco 3 Cookbook
Snig Bhaumik
No ratings yet
Laravel 5.x Cookbook
From Everand
Laravel 5.x Cookbook
Alfred Nutile
No ratings yet
Modern C++ Programming: Including the recent standards C++11, C++17, C++20, C++23
From Everand
Modern C++ Programming: Including the recent standards C++11, C++17, C++20, C++23
Orhan Gazi
No ratings yet
Prezi Cookbook
From Everand
Prezi Cookbook
Charlotte Olsson
No ratings yet
50 Python Concepts Every Developer Should Know
From Everand
50 Python Concepts Every Developer Should Know
Hernando Abella
No ratings yet
Advanced GitLab CI/CD Pipelines: An In-Depth Guide for Continuous Integration and Deployment
From Everand
Advanced GitLab CI/CD Pipelines: An In-Depth Guide for Continuous Integration and Deployment
Adam Jones
No ratings yet
Java servlet Second Edition
From Everand
Java servlet Second Edition
Gerardus Blokdyk
No ratings yet
USB Audio Interface: Owner'S Manual
No ratings yet
USB Audio Interface: Owner'S Manual
35 pages
Nightstick XPR 5542gmx
No ratings yet
Nightstick XPR 5542gmx
2 pages
Pt. Mercury Tekindo Internusa: Item No. QTY Description
No ratings yet
Pt. Mercury Tekindo Internusa: Item No. QTY Description
1 page
Rule Based Syntax Analyser For Telugu Poems
No ratings yet
Rule Based Syntax Analyser For Telugu Poems
6 pages
Wuxi Driveshafts Co., LTD.: Universal Joint Shafts For Industrial Applications
No ratings yet
Wuxi Driveshafts Co., LTD.: Universal Joint Shafts For Industrial Applications
32 pages
Soel Yacths
No ratings yet
Soel Yacths
24 pages
Fuels and Combustion
No ratings yet
Fuels and Combustion
6 pages
Husseys News Release 2 Final
No ratings yet
Husseys News Release 2 Final
3 pages
Icho1986-1994p Technical and Physical
No ratings yet
Icho1986-1994p Technical and Physical
38 pages
EMS Application Guide PDF
No ratings yet
EMS Application Guide PDF
71 pages
Promix 400 Homogenizing Agent For Tire Innerliner
100% (1)
Promix 400 Homogenizing Agent For Tire Innerliner
23 pages
Review of DC-DC boost converter derived topologies for renewable energy applications
100% (1)
Review of DC-DC boost converter derived topologies for renewable energy applications
11 pages
Specification of MEFG Portable Type
No ratings yet
Specification of MEFG Portable Type
6 pages
ECx Ethernet Control 80096
No ratings yet
ECx Ethernet Control 80096
17 pages
H25K5A
No ratings yet
H25K5A
2 pages
Cost Estimation - Fence
No ratings yet
Cost Estimation - Fence
168 pages
ALternador Delco Remy
100% (1)
ALternador Delco Remy
21 pages
Machine Design
No ratings yet
Machine Design
19 pages
Garcia, Bray - Discrete Element Analysis of Earthquake Fault Rupture-Soil-Foundation Interaction-2019
No ratings yet
Garcia, Bray - Discrete Element Analysis of Earthquake Fault Rupture-Soil-Foundation Interaction-2019
12 pages
Navod k Pouziti Ts Ft003 005
No ratings yet
Navod k Pouziti Ts Ft003 005
20 pages
Introduction of Forging
No ratings yet
Introduction of Forging
5 pages
Asphalt Laying Process
No ratings yet
Asphalt Laying Process
3 pages
Ahmed Sha'alan Resume 2017 April
No ratings yet
Ahmed Sha'alan Resume 2017 April
1 page
Chapter 21-Theory of Metal Machining
No ratings yet
Chapter 21-Theory of Metal Machining
50 pages
Contactor Safety Combination 3TK2803, 3TK2804 3TK2907, 3TK29.3
No ratings yet
Contactor Safety Combination 3TK2803, 3TK2804 3TK2907, 3TK29.3
3 pages
Constitutive Relations
No ratings yet
Constitutive Relations
32 pages
Saic M 1049
No ratings yet
Saic M 1049
3 pages
kgp913 e PDF
No ratings yet
kgp913 e PDF
2 pages