REST API Developer Guide

Version 61.0, Summer ’24

Last updated: August 23, 2024

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

CONTENTS

Chapter 1: Introduction to REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

About REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Supported Editions and Required Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

REST Resources and Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

REST API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Authorization Through Connected Apps and OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Assignment Rule Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Call Options Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Compression Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Conditional Request Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Duplicate Rule Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Limit Info Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

MRU Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Package Version Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Query Options Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Warning Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Send REST Requests with cURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Valid Date and DateTime Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Status Codes and Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

API End-of-Life Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 2: Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Using cURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Step One: Sign up for Salesforce Developer Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Step Two: Set Up Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Step Three: Walk Through the Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Using Other Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 3: Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Getting Information About My Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

List Available REST API Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

List Org Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

List Available REST Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Get a List of Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Get a List of Objects If Metadata Has Changed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Working with Object Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Get Metadata for an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Get Field and Other Metadata for an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Get Object Metadata Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Working with Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Create a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Update a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Delete a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Get Field Values from a Standard Object Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Get Field Values from an External Object Record by Using the Salesforce ID . . . . . . . . . . 48

Get Field Values from an External Object Record by Using the External ID Standard

Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Get a Record Using an External ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

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

Traverse Relationships with Friendly URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Get a List of Deleted Records Within a Given Timeframe . . . . . . . . . . . . . . . . . . . . . . . 59

Get a List of Updated Records Within a Given Timeframe . . . . . . . . . . . . . . . . . . . . . . . 60

Delete Lightning Experience Event Series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 (Beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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

Get an Image from a Rich Text Area Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Insert or Update Blob Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Get Blob Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Working with Recently Viewed Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

View Recently Viewed Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Mark Records as Recently Viewed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Managing User Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Manage User Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Working with Approval Processes and Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Get a List of All Approval Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Submit a Record for Approval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Approve a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Reject a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Bulk Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Get a List of Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Get a Particular Process Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Trigger Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Using Event Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Describe Event Monitoring Using REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Query Event Monitoring Data with REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Contents

Get Event Monitoring Content from a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Download Large Event Log Files Using cURL with REST . . . . . . . . . . . . . . . . . . . . . . . . . 94

Delete Event Monitoring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Query or View Hourly Event Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Using Composite Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Execute Dependent Requests in a Single API Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Update an Account, Create a Contact, and Link Them with a Junction Object . . . . . . . . . 101

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

Upsert an Account and Create a Contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Create Nested Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Create Multiple Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Using Composite Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Using a Composite Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

allOrNone Parameters in Composite and Collections Requests . . . . . . . . . . . . . . . . . . 117

Chapter 4: Generating an OpenAPI 3.0 Document for sObjects REST API (Beta) . . . . . 122

Chapter 5: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Resources by Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Describe Global . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

sObject Basic Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Get Object Metadata Using sObject Basic Information . . . . . . . . . . . . . . . . . . . . . . . . 143

Create Records Using sObject Basic Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

sObject Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

sObject Get Deleted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

sObject Get Updated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

sObject Named Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

sObject Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Get Records Using sObject Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Update Records Using sObject Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Delete Records Using sObject Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

sObject Rows by External ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Get Records Using sObject Rows by External ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Create Records Using sObject Rows by External ID . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Upsert Records Using sObject Rows by External ID . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Delete Records Using sObject Rows by External ID . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Return Headers Using sObject Rows by External ID . . . . . . . . . . . . . . . . . . . . . . . . . . 158

sObject Blob Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

sObject ApprovalLayouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Get Approval Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Return Headers for Approval Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

sObject Single Approval Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Contents

Get a Layout for a Single Approval Process on a Specified Object . . . . . . . . . . . . . . . . 162

Return Headers for a Single Approval Process on a Specified Object . . . . . . . . . . . . . . 163

sObject CompactLayouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Get Compact Layouts Using sObject CompactLayouts . . . . . . . . . . . . . . . . . . . . . . . . 163

Return Headers Using sObject CompactLayouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

sObject Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Get Layouts and Descriptions for a Specified Object . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Return Layout Headers for a Specified Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

sObject Layouts for an Object With Multiple Record Types . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Get Layouts and Descriptions for an Object With Multiple Record Types . . . . . . . . . . . . . 171

Return Layout Headers for an Object With Multiple Record Types . . . . . . . . . . . . . . . . . 173

sObject Global Publisher Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Get Global Publisher Layouts and Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Return Headers for All Global Publisher Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

sObject PlatformAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

sObject Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Get sObject Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Return Headers Using sObject Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

sObject Specific Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Get Specific sObject Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Create Records Using Specific sObject Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . 179

Return Headers Using Specific sObject Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . 180

sObject Quick Action Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Get sObject Quick Action Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Return Headers Using sObject Quick Action Details . . . . . . . . . . . . . . . . . . . . . . . . . . 181

sObject Quick Action Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Get sObject Quick Action Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Return Headers Using sObject Quick Action Default Values . . . . . . . . . . . . . . . . . . . . 183

sObject Quick Action Default Values by ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Get sObject Quick Action Default Values by ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Return Headers Using sObject Quick Action Default Values by ID . . . . . . . . . . . . . . . . . 184

sObject Rich Text Image Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

sObject Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Get Records Using sObject Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Update Records Using sObject Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Delete Records Using sObject Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

sObjects Suggested Articles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

sObjects Suggested Articles by ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

sObject User Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Get User Password Expiration Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Set User Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Reset User Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Return Headers Using sObject User Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

sObject Self-Service User Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Contents

Get Self-Service User Password Expiration Status . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Set Self-Service User Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Reset Self-Service User Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Return Headers Using sObject Self-Service User Password . . . . . . . . . . . . . . . . . . . . . 199

Platform Event Schema by Event Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Platform Event Schema by Schema ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Get AppMenu Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

AppMenu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Get AppMenu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Return Headers of App Menu Item Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

AppMenu Mobile Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Get AppMenu Mobile Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Return Headers of AppMenu Mobile Item Requests . . . . . . . . . . . . . . . . . . . . . . . . . 215

Compact Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Consent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Compile Consent Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Compile Multiple Types of Consent Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Use the Consent API with Data Cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Consent Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Embedded Service Configuration Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Get Embedded Service Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Return Headers for Embedded Service Configuration . . . . . . . . . . . . . . . . . . . . . . . . 238

Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Get Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Return HTTP Headers for Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Invocable Actions Custom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Get Custom Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Return HTTP Headers for Custom Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . 243

Invocable Actions Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Get Standard Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Return HTTP Headers for Standard Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . 246

List View Basic Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

List View Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

List View Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

List Views for an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Support Knowledge with REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Data Category Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Data Category Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Articles List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Articles Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Parameterized Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Search with Parameters in the URI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Search with Parameters in the Request Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Portability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Contents

Compile Data for a Portability Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Get the Status of Your Portability Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Process Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Get Process Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Submit, Approve, or Reject Process Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Return HTTP Headers for Process Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Get Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Trigger Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Return HTTP Headers for Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Process Rule for an sObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Get a Process Rule for an sObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Trigger a Process Rule for an sObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Return HTTP Headers for a Process Rule of an sObject . . . . . . . . . . . . . . . . . . . . . . . 296

Process Rule List for an sObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Get Process Rules for an sObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Return HTTP Headers for Process Rules of an sObject . . . . . . . . . . . . . . . . . . . . . . . . 298

Product Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Get Product Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Create Product Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Delete Product Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Data Cloud Query Profile Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Query More Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

QueryAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

QueryAll More Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Query Performance Feedback (Beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Get Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Create Records Using Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Return Headers of Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Recent List Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Recently Viewed Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Record Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Record Count Response Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

sObject Relevant Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

Get Knowledge Language Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

Search Scope and Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Search Result Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Lightning Toggle Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Lightning Usage by App Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Lightning Usage by Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Lightning Usage by Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Contents

Lightning Usage by FlexiPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Lightning Exit by Page Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Salesforce Scheduler Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Get Appointment Slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Get Appointment Candidates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Request Bodies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

Response Bodies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Search for Records Suggested by Autocomplete and Instant Results . . . . . . . . . . . . . . . . . . 339

Search Suggested Article Title Matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Search Suggested Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Salesforce Surveys Translation Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

Add or Change the Translation of a Survey Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

Add or Update the Translated Value of Multiple Survey Fields in One or More

Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

Delete the Translated Value of a Survey Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Delete the Translated Value of Multiple Survey Fields in One or More Languages . . . . . 354

Get Translated Value of a Survey Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Get the Translated Values of Multiple Survey Fields in One or More Languages . . . . . . . 356

Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Get Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Return Headers Using Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Composite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

Send Multiple Requests Using Composite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

Get a List of Composite Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

Composite Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

Composite Subrequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

Composite Graph Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Composite Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

Batch Request Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

Batch Response Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

sObject Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390

sObject Tree Request Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

sObject Tree Response Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

sObject Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Create Records Using sObject Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Get Records Using sObject Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

Get Records With a Request Body Using sObject Collections . . . . . . . . . . . . . . . . . . . 400

Update Records Using sObject Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

Upsert Records Using sObject Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

Delete Records Using sObject Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

Contents

CHAPTER 1 Introduction to REST API

REST API provides you with programmatic access to your data in Salesforce. The flexibility and scalability

of REST API make it an excellent choice for integrating Salesforce into your applications and for performing

complex operations on a large scale.

In this chapter ...

• About REST API

• REST API Release

Notes

Use this guide to set up your deployment environment and learn about advanced details regarding data

access. However, understanding and using REST API requires basic familiarity with software development,

web services, and the Salesforce user interface.

• Supported Editions

and Required

Permissions

If you want to get right to the action, the Quick Start guide covers the basics to get you up and running.

If you’re looking for more context about Salesforce APIs, check out the list of links.

• REST Resources and

Requests

Tip: Salesforce REST API is designed to work with Salesforce objects. See the Object Reference for

the Salesforce Platform for an introduction and more information about Salesforce objects.

• REST API Architecture

• Authorization

Through Connected

Apps and OAuth 2.0

SEE ALSO:

Trailhead: Lightning Platform API Basics

• Headers

• Send REST Requests

with cURL

• Valid Date and

DateTime Formats

• Status Codes and

Error Responses

• API End-of-Life Policy

About REST API

REST API is one of several web interfaces that you can use to access your Salesforce data without using the Salesforce user interface.

With API access, you can perform operations and integrate Salesforce into your applications as you like.

You can use REST API tools to create, manipulate, and search data in Salesforce by sending HTTP requests to endpoints in Salesforce.

Depending on where you send requests, you access and operate on different pieces of information, called resources. Resources include

records, query results, metadata, and more.

REST API uses RESTful architecture to provide a straightforward and consistent interface. A primary benefit of REST API is that it doesn’t

require much tooling to access your data. It’s simpler to use than SOAP API but still provides plenty of functionality.

Although REST API is great for accessing and querying records, other Salesforce APIs, such as Bulk 2.0 API, Metadata API, and Connect

REST API, offer additional functionality for specific tasks.

SEE ALSO:

REST Resources and Requests

REST API Architecture

REST API Release Notes

Use the Salesforce Release Notes to learn about the most recent updates and changes to REST API.

For updates and changes that impact the Salesforce Platform, including REST API, see the API Release Notes.

For new, changed, and deprecated calls and other changes specific to REST API, see REST API in the Salesforce Release Notes.

Supported Editions and Required Permissions

To access your Salesforce org and data using the Salesforce API, you need both an org and a user with API access enabled. There’s more

than one Salesforce Edition that supports API access and multiple ways to grant API permission to a user.

Supported Editions for API Access

API access is enabled by default in Enterprise, Performance, Unlimited, and Developer Edition orgs. Professional Edition orgs can add

API access as an add-on. For more information, visit Salesforce Help: Add Products and Licenses with the Your Account App or contact

a Salesforce account executive.

If you send an API request to an org without API access, Salesforce returns a API_DISABLED_FOR_ORG error.

To protect the configuration and live data in your production org, we recommend using an isolated environment for active development

and testing, such as aDeveloper Edition org, sandbox, or scratch org. When ready, you can move successful changes into your production

org.

API User Permissions

To make any API call, a user must have the API Enabled permission turned on in the user profile they’re assigned. This permission is

enabled by default on some profiles, including many profiles available in Developer Edition orgs. In supported editions, you can also use

About REST APIIntroduction to REST API

the Salesforce Integration user license to grant system-to-system integration users full org access while limiting them to API-only

operations. For more information, see Salesforce Help: Give Integration Users API Only Access

SEE ALSO:

Get your very own Developer Edition

Scratch Orgs

Sandboxes

Salesforce DX Developer Guide

REST Resources and Requests

REST API is based on the usage of resources—pieces of data in Salesforce, such as records, collections of records, query results, metadata,

or API information. Each resource is exposed by a uniform resource identifier (URI) and is accessed by sending HTTP requests to the

corresponding URI.

Depending on which resource you want to access and how you construct an HTTP request, you can perform several types of operations,

including:

•

Determine available API versions

•

Access limits for your Salesforce org

•

Retrieve object metadata

•

Create, read, update, and delete records

•

Query and search for data

You can send HTTP requests using a variety of software tools, which means that the exact appearance of a request can look different

from the cURL examples in this guide. However, no matter how you submit requests, the elements don’t change. A typical request

consists of these elements.

•

URI

•

HTTP method

•

Headers

•

Request body (not required for GET requests)

URIs

The URI is the path to a resource in Salesforce. Although the URI changes from resource to resource, the basic structure remains the

same.

https://MyDomainName.my.salesforce.com/services/data/vXX.X/resource/

Use https:// to securely access resources.

Replace MyDomainName with the subdomain of your Salesforce org. Salesforce runs on multiple server instances, so the examples

in this guide use MyDomainName in place of a specific instance.

Replace XX.X with the version of the API that you want to use. You can find a list of available versions by accessing the Versions on

page 136 resource.

Replace resource with the rest of the path to the resource. Depending on the resource, the path can contain parameters, such as

IDs to identify a specific record. You can find the URIs for different resources in the Reference section of this guide.

REST Resources and RequestsIntroduction to REST API

sObject resources access standard and custom objects in Salesforce. For information about objects, see Object Reference for the Salesforce

Platform.

Note: Some parts of URIs are case-sensitive, such as IDs. Other parts of URIs aren't case-sensitive, such as object and field names.

If your requests aren't successful, check that your URI has the right letter cases by comparing the URI to the examples in this guide.

HTTP Methods

REST API supports standard HTTP request methods (HEAD, GET, POST, PATCH, PUT, and DELETE), which follow the specifications at

https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html.

The purpose of each method varies depending on the resource. For information on how and when to use each method, check the page

for that resource in the Reference section of this guide.

Headers

Use headers to pass parameters and customize options for HTTP requests. REST API supports several standard HTTP headers, as well as

custom headers that are specific to Salesforce.

Common headers used in the examples include:

•

HTTP Accept—Indicates the format that your client accepts for the response body. Possible values are application/json

and application/xml. If the value is missing or malformed, then application/json is used by default.

•

HTTP Content-type—Indicates the format of the request body that you attach to the request. Possible values are

application/json and application/xml.

•

HTTP Authorization—Provides the OAuth 2.0 access token to authorize your client. REST API supports the Bearer authentication

type.

•

Compression header—Compresses the request or the response. For more information, see Compression Headers on page 9.

•

Conditional request header—Validates the records that you access against a precondition. For more information, see Conditional

Request Headers on page 10.

Request Bodies

A request body is a rich input that can be included in the request to provide additional information, such as field values for creating or

updating records. A request body can be in JSON or XML format.

Note: Resources accessed with the GET method don’t require you to attach a request body.

Use the HTTP Content-type header to indicate the file format of the request body. If you use cURL to send the request, attach the JSON

or XML file to the request using the —data-binary or -d option.

SEE ALSO:

Send REST Requests with cURL

Setting Up Your Java Developer Environment

REST API Architecture

REST API follows the standard RESTful principles and characteristics.

REST API ArchitectureIntroduction to REST API

Client-server

Client applications are independent from Salesforce REST API, meaning each is managed and updated independently.

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 URIs, 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 HTTPS.

Named resources

All resources are named using a base URI that follows your Lightning Platform endpoint. See REST Resources and Requests for details

and examples.

Layered components

Intermediaries, such as proxy servers and gateways, are allowed between the client and the resources.

In addition to the standard RESTful principles, REST API includes other key characteristics in its architecture that are important to understand

and consider as you develop your applications.

Authentication

REST API supports OAuth 2.0 (an open protocol to allow secure API authorization). See Authorize Apps with OAuth in Salesforce Help

for more details.

Support for JSON and XML

JSON requests are supported in UTF-8 and are the default. XML requests are supported in UTF-8 and UTF-16. XML responses are

provided in UTF-8. Use the HTTP ACCEPT header to specify either JSON or XML.

In versions 57.0 and earlier, it’s possible to append json or xml to the URI. For example,

/Account/001D000000INjVe.json. We recommend using the HTTP ACCEPT header to specify JSON or XML instead.

In versions 58.0 and later, appending JSON or XML to the URI isn’t supported.

Compression

Compression reduces bandwidth loads by compressing the messages sent between REST API and your client. REST API supports

compression with gzip and deflate, as defined by the HTTP 1.1 specification. See Compression Headers.

Conditional Requests

Response caching is supported by conditional request headers that follow the standards defined by the HTTP 1.1 specification, with

a few exceptions. See Conditional Request Headers.

Cross-Origin Resource Sharing

Cross-Origin Resource Sharing (CORS) enables web browsers to request resources from origins other than their own. For example,

using CORS, JavaScript code at https://www.example.com could request a resource from https://www.salesforce.com. To access

supported Salesforce APIs, Apex REST resources, and Lightning Out from JavaScript code in a web browser, add the origin serving

the code to a Salesforce CORS allowlist. See Perform Cross-Origin Requests from Web Browsers.

Salesforce ID Length

Salesforce IDs in response bodies are always 18-character IDs. In request bodies, you can use either 15 character IDs or 18 character

IDs.

REST API ArchitectureIntroduction to REST API

Method Overriding

To override an HTTP method if you use an HTTP library that doesn’t allow overriding or setting an arbitrary HTTP method name, use

the request parameter _HttpMethod.

POST https://instance_name/services/data/v61.0/chatter/

/chatter/users/me/conversations/03MD0000000008KMAQ

?_HttpMethod=PATCH&read=true

Note: The _HttpMethod parameter is case-sensitive. Use the correct case for all values.

HTTPS

All communication between client and server is over HTTPS.

Authorization Through Connected Apps and OAuth 2.0

For a client application to access REST API resources, it must be authorized as a safe visitor. To implement this authorization, use a

connected app and an OAuth 2.0 authorization flow.

Configure a Connected App

A connected app requests access to REST API resources on behalf of the client application. For a connected app to request access, it

must be integrated with your org’s REST API using the OAuth 2.0 protocol. OAuth 2.0 is an open protocol that authorizes secure data

sharing between applications through the exchange of tokens.

For instructions to configure a connected app, see Create a Connected App in Salesforce Help. Specifically, follow the steps in Enable

OAuth Settings for API Integration.

Apply an OAuth Authorization Flow

OAuth authorization flows grant a client app restricted access to REST API resources on a resource server. Each OAuth flow offers a

different process for approving access to a client app, but in general the flows consist of three main steps.

1. To initiate an authorization flow, a connected app on behalf of a client app requests access to a REST API resource.

2. In response, an authorizing server grants access tokens to the connected app.

3. A resource server validates these access tokens and approves access to the protected REST API resource.

After reviewing and selecting an OAuth authorization flow, apply it to your connected app. For details about each supported flow, see

OAuth Authorization Flows in Salesforce Help.

More Resources

Salesforce offers the following resources to help you navigate connected apps and OAuth:

•

Salesforce Help: Connected Apps

•

Salesforce Help: Authorize Apps with OAuth

•

Salesforce Help: OpenID Connect Token Introspection

•

Trailhead: Build Integrations Using Connected Apps

Authorization Through Connected Apps and OAuth 2.0Introduction to REST API

Headers

REST API supports several standard and custom HTTP headers, including both request headers and response headers.

IN THIS SECTION:

Assignment Rule Header

The Assignment Rule header is a request header applied when creating or updating Accounts, 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 options for the client you’re using to access REST API resources. For example, you can provide a default namespace prefix

so that you don’t need to specify the prefix in your code.

Compression Headers

Use a compression header to compress a REST API request or response. Compression reduces the bandwidth required for a request,

although it requires more processing power at your client. In most cases, this tradeoff benefits the overall performance of your

application.

Conditional Request Headers

Use a conditional request header to validate resources before accessing them. By setting a precondition in the header, you ensure

that your request succeeds only if that precondition is met. This functionality helps you prevent mistakes and reject outdated requests

when updating Salesforce data. You can implement a variety of techniques with conditional request headers, such as response

caching.

Duplicate Rule Header

Configure options for duplicate rules. Salesforce uses duplicate rules to see if the record that is being created, updated, or upserted

is a duplicate of an existing record. Duplicate rules are part of Duplicate Management.

Limit Info Header

This response header is returned in each request to REST API (except for calls to the Versions URI, /, which do not count towards

your org’s limit). You can use the information to monitor API limits.

MRU Header

Defines if the record that is created, updated, upserted, or retrieved updates the list of most recently used (MRU) items. MRU items

are shown in the Recent Items section of the sidebar in the Salesforce user interface. This header is available in API version 60.0 and

later.

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.

Warning Header

This header is returned if there are warnings, such as the use of a deprecated version of the API.

HeadersIntroduction to REST API

Assignment Rule Header

The Assignment Rule header is a request header applied when creating or updating Accounts, 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.

Note: This header also gets applied when making REST API calls that indirectly result in creating or updating Accounts, Cases, or

Leads. For example, if you use this header with a call that updates a record, and the update executes an Apex trigger that updates

a Case, the assignment rules would be applied.

Header Field Name and Values

Field name

Sforce-Auto-Assign

Field values

•

TRUE. Active assignment rules are applied for created or updated Accounts, Cases, or Leads.

•

FALSE. Active assignment rules are not applied for created or updated Accounts, Cases, or Leads.

•

Valid AssignmentRule ID. The given AssignmentRule is applied for created Accounts, 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 options for the client you’re using to access REST API resources. For example, you can provide a default namespace prefix so

that you don’t need to specify the prefix in your code.

The Call Options header can be used with sObject Basic Information, sObject Rows, sObject Rows by External ID, Query, QueryAll, and

Search. It is also supported in Bulk API and Bulk API 2.0.

Header Field Name and Values

Field name

Sforce-Call-Options

Field values

•

client—A string used as an identifier for the client sending the request. This string appears in log files, helping you keep

track of which client sent a request.

•

defaultNamespace—A developer namespace prefix used as the default namespace for the request. With this header field,

the request resolves field names in managed packages without specified namespaces. (Not supported in Bulk API.)

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=caseSensitiveToken; defaultNamespace=battle

Assignment Rule HeaderIntroduction to REST API

Then queries such as the following succeed:

/services/data/vXX.X/query/?q=SELECT+Id+botID__c+FROM+Account

In this case, the actual field queried is the battle__botId__c field.

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 doesn’t 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.

Compression Headers

Use a compression header to compress a REST API request or response. Compression reduces the bandwidth required for a request,

although it requires more processing power at your client. In most cases, this tradeoff benefits the overall performance of your application.

REST API supports the gzip and deflate compression algorithms, as defined by the HTTP 1.1 specification. If you’re unsure about which

one to use, gzip is more common than deflate.

Tip: For better performance, we suggest that clients accept and support compression as defined by the HTTP 1.1 specification.

Request Compression

Include a Content-Encoding: gzip or Content-Encoding: deflate header to compress a request. REST API

decompresses any requests before processing.

This example request is compressed with gzip.

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/ -H

"Authorization: Bearer access-token" -H "Content-Type: application/json" -H

"Content-Encoding: gzip" —data-binary @new-account.json -X POST

Response Compression

Salesforce compresses a response only if the request contains an Accept-Encoding: gzip or Accept-Encoding:

deflate header. REST API isn’t required to compress the response even if you’ve specified Accept-Encoding, but it normally does. If

compressed, the response contains a Content-Encoding header with the compression algorithm so that your client knows to decompress

it.

This example request asks for a compressed response.

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/0015e000009sS0DAAU

-H "Authorization: Bearer access-token" -H "Content-Type: application/json" -H

"Accept-Encoding: gzip" -X GET

Compression HeadersIntroduction to REST API

Conditional Request Headers

Use a conditional request header to validate resources before accessing them. By setting a precondition in the header, you ensure that

your request succeeds only if that precondition is met. This functionality helps you prevent mistakes and reject outdated requests when

updating Salesforce data. You can implement a variety of techniques with conditional request headers, such as response caching.

Two types of validation are available with conditional request headers: strong and weak. Strong validation checks whether the precondition

exactly matches the resource in Salesforce. Strong validation headers include If-Match and If-None-Match, which use entity

tags (ETags) to compare the precondition to the record in Salesforce.

Weak validation checks a precondition against the resource in Salesforce, but it doesn’t guarantee that the two are identical. Weak

validation headers include If-Modified-Since or If-Unmodified-Since, which compare the precondition to the last

modified date of the record in Salesforce.

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 or

POST request, a 400 Bad Request status code is returned.

•

The If-Range header isn’t supported.

•

DELETE requests aren’t supported

ETag

The ETag header is a response header that’s returned when you access the sObject Rows resource. It’s a hash of the content that’s

used by the If-Match and If-None-Match request headers in subsequent requests to determine if the content has changed.

This header is supported by sObject Rows (Account records only) resources.

This example shows an ETag returned by REST API.

ETag: "U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"

You can find the HTTP 1.1 specification for the ETag header at www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19 .

If-Match

The If-Match header is a request header for sObject Rows that includes a list of ETags. If the ETag of the record that you’re requesting

matches an ETag specified as a precondition in the header, the request is processed. Otherwise, a 412 Precondition Failed status code

is returned, and the request isn’t processed.

This header supports sObject Rows (Account records only) resources.

In this example an, If-Match header is included with a request.

If-Match: "Jbjuzw7dbhaEG3fd90kJbx6A0ow=-gzip", "U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"

You can find the HTTP 1.1 specification for the If-Match header at www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.24 .

If-None-Match

The If-None-Match header is a request header for sObject Rows that’s the inverse of If-Match. If the ETag of the record that

you’re requesting matches an ETag specified in the header, the request isn’t 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.

This header supports sObject Rows (Account records only) resources.

Conditional Request HeadersIntroduction to REST API

In this example, an If-None-Match header is included with a request.

If-None-Match: "Jbjuzw7dbhaEG3fd90kJbx6A0ow=-gzip", "U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"

You can find the HTTP 1.1 specification for the If-None-Match header at www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26

If-Modified-Since

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 isn’t processed.

This header supports sObject Rows, sObject Describe, Describe Global, and Invocable Actions resources.

In this example an If-Modified-Since header is included with a request.

If-Modified-Since: Tue, 10 Aug 2015 00:00:00 GMT

You can find the HTTP 1.1 specification for the If-Modified-Since header at

www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25 .

If-Unmodified-Since

The If-Unmodified-Since header is a request header that’s the inverse of If-Modified-Since. If you make a request

and include the If-Unmodified-Since header, REST API processes the request only if the data hasn’t changed since the specified date.

Otherwise, a 412 Precondition Failed status code is returned, and the request isn’t processed.

This header supports sObject Rows, sObject Describe, Describe Global, and Invocable Actions resources.

In this example, an If-Unmodified-Since header is included in a request.

If-Unmodified-Since: Tue, 10 Aug 2015 00:00:00 GMT

You can find the HTTP 1.1 specification for the If-Unmodified-Since header at

www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.28 .

Duplicate Rule Header

Configure options for duplicate rules. Salesforce uses duplicate rules to see if the record that is being created, updated, or upserted is a

duplicate of an existing record. Duplicate rules are part of Duplicate Management.

This header is available in API version 52.0 and later.

Header Field Name and Values

The default value for all fields is false.

Field name

allowSave

Field values

•

true—allow the user to acknowledge the alert and save the duplicate record. Applicable if an alert is enabled for the action.

•

false—don't allow the user to acknowledge the alert or save the duplicate record. Applicable if an alert is enabled for the

action.

Duplicate Rule HeaderIntroduction to REST API

Field name

includeRecordDetails

Field values

•

true—return all fields in the duplicate record.

•

false—return the duplicate record ID, but not the fields.

Field name

runAsCurrentUser

Field values

•

true—when the duplicate rule is run, use the current user's sharing rules.

•

false—when the duplicate rule is run, use the system sharing rules, not the current user's sharing rules.

Example

Allow the user to acknowledge the alert and save the duplicate record. Indicate that the duplicate field's records are returned, and that

the current user's sharing rules are enforced. These duplicate management configuration options are now applied when records are

created, updated, and upserted.

Sforce-Duplicate-Rule-Header: allowSave=true; includeRecordDetails=true;

runAsCurrentUser=true

Limit Info Header

This response header is returned in each request to REST API (except for calls to the Versions URI, /, which do not count towards your

org’s limit). You can use the information to monitor API limits.

Header Field Name and Values

Field name

Sforce-Limit-Info

Field values

•

api-usage—Specifies the daily API usage for the organization against which the call was made. The first number is the

number of API calls used, and the second number is the API limit for the organization.

The values returned in the header represent standard REST API limits and usage, except when calls are made using Salesforce

Functions. Calls made using Salesforce Functions draw from a Functions-specific allocation.

Example

Sforce-Limit-Info: api-usage=10018/100000

SEE ALSO:

Salesforce Functions Guide: Functions Limits

MRU Header

Defines if the record that is created, updated, upserted, or retrieved updates the list of most recently used (MRU) items. MRU items are

shown in the Recent Items section of the sidebar in the Salesforce user interface. This header is available in API version 60.0 and later.

Limit Info HeaderIntroduction to REST API

Note: REST APIs that create, update, upsert, or retrieve records support this header. For examples of these APIs, see sObject Rows

and sObject Rows by External ID in the See Also section. REST APIs used to query records via SOQL never update the MRU, so the

header field has no impact on the MRU and is always set to false.

Header Field Name and Values

The default value for all fields is true, except for with REST APIs that query records via SOQL. The default value is subject to change.

For integration users who make only API calls, Salesforce recommends setting this field to false to improve performance. MRU isn’t

relevant for integration users using solely APIs because they don’t use the Salesforce user interface.

Field name

updateMru

Field values

•

true—Update MRU with related records if the No MRU Updates field isn’t enabled for the user on the Users page in Setup.

For more information on how to enable this field, see the Edit Users page in the See Also section.

•

false—Don’t update MRU with related records.

Example

Indicates that the record updates the MRU.

Sforce-Mru: updateMru=true

SEE ALSO:

sObject Rows

sObject Rows by External ID

Salesforce Help: Edit Users

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, sObject 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.

Package Version HeaderIntroduction to REST API

Header Field Name and Values

Field name

Sforce-Query-Options

Field values

•

batchSize—A 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

Warning Header

This header is returned if there are warnings, such as the use of a deprecated version of the API.

Header Field Name and Values

Field name

Warning

Field Values

warningCode warningMessage

For warnings about deprecated API versions, the warningCode is 299.

Example

Warning: 299 - "This API is deprecated and will be removed by Summer '22. Please see

https://help.salesforce.com/articleView?id=000351312 for details."

Send REST Requests with cURL

The examples in this guide use the cURL tool to send HTTP requests that access, create, and manipulate resources in Salesforce. If you

use a different tool to send requests, you can use the same elements from the cURL examples to send requests.

cURL is pre-installed on many Linux and macOS 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 isn’t supported by Salesforce.

Attaching Request Bodies

Many examples include request bodies—JSON or XML files that contain data for the request. When using cURL, save these files to your

local system and attach them to the request using the —data-binary or -d option.

Warning HeaderIntroduction to REST API

This example attaches the new-account.json file.

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/ -H

"Authorization: Bearer access-token" -H “Content-Type: application/json” —data-binary

@new-account.json -X POST

Handling Exclamation Marks in Access Tokens

When you run cURL examples, you can get an error on macOS and Linux systems due to the presence of the exclamation mark (!) special

character in OAuth access tokens. To avoid getting this error, either escape the exclamation mark or use single quotes.

To escape the exclamation mark in the access token, insert a backslash before it (\!) when the access token is enclosed within double

quotes. For example, the access token string in this cURL command has the exclamation mark (!) escaped.

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

00D50000000IehZ\!AQcAQH0dMHZfz972Szmpkb58urFRkgeBGsxL_QJWwYMfAbUeeG7c1E6LYUfiDUkWe6H34r1AAwOR8B8fLEz6n04NPGRrq0FM"

Or, you can enclose the access token within single quotes.

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/ -H 'Authorization: Bearer

00D50000000IehZ!AQcAQH0dMHZfz972Szmpkb58urFRkgeBGsxL_QJWwYMfAbUeeG7c1E6LYUfiDUkWe6H34r1AAwOR8B8fLEz6n04NPGRrq0FM'

SEE ALSO:

Setting Up Your Java Developer Environment

Valid Date and DateTime Formats

Specify the right format for dateTime and date fields.

dateTime

Use the yyyy-MM-ddTHH:mm:ss.SSS+/-HH:mm or yyyy-MM-ddTHH:mm:ss.SSSZ formats to specify dateTime

fields.

•

yyyy is the four-digit year

•

MM is the two-digit month (01-12)

•

dd is the two-digit day (01-31)

•

'T' is a separator indicating that time-of-day follows

•

HH is the two-digit hour (00-23)

•

mm is the two-digit minute (00-59)

•

ss is the two-digit seconds (00-59)

•

SSS is the optional three-digit milliseconds (000-999)

•

+/-HH:mm is the Zulu (UTC) time zone offset

•

'Z' is the reference UTC timezone

When a timezone is added to a UTC dateTime, the result is the date and time in that timezone. For example, 2002-10-10T12:00:00+05:00

is 2002-10-10T07:00:00Z and 2002-10-10T00:00:00+05:00 is 2002-10-09T19:00:00Z. See W3C XML Schema Part 2: DateTime Datatype.

Valid Date and DateTime FormatsIntroduction to REST API

date

Use the yyyy-MM-dd format to specify date fields.

Note: Specifying an offset for date is not supported.

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)

DescriptionHTTP response

code

“OK” success code, for GET, HEAD, and some PATCH requests.200

“Created” success code, for POST requests and some PATCH requests.201

“No Content” success code, for DELETE requests and some PATCH requests.204

The value returned when an external ID exists in more than one record. The response body contains the list

of matching records.

300

The request content hasn’t changed since a specified date and time. The date and time is provided in a

If-Modified-Since header. See Get Object Metatdata Changes for an example.

304

The request couldn’t be understood, usually because the JSON or XML body contains an error.400

The session ID or OAuth token used has expired or is invalid. The response body contains the message and

errorCode.

401

The request has been refused. Verify that the logged-in user has appropriate permissions. If the error code is

REQUEST_LIMIT_EXCEEDED, you’ve exceeded API request limits in your org.

403

The requested resource couldn’t be found. Check the URI for errors, and verify that there are no sharing issues.404

The method specified in the Request-Line isn’t allowed for the resource specified in the URI.405

The request couldn’t be completed due to a conflict with the current state of the resource. Check that the API

version is compatible with the resource you’re requesting.

409

The requested resource has been retired or removed. Delete or update any references to the resource.410

The request wasn’t executed because one or more of the preconditions that the client specified in the request

headers wasn’t satisfied. For example, the request includes an If-Unmodified-Since header, but the

data was modified after the specified date.

412

The length of the URI exceeds the 16,384-byte limit.414

The entity in the request is in a format that’s not supported by the specified method.415

Status Codes and Error ResponsesIntroduction to REST API

DescriptionHTTP response

code

Salesforce Edge doesn’t have routing information available for this request host. Contact Salesforce Customer

Support.

420

The request wasn’t executed because it wasn’t conditional. Add one of the Conditional Request Headers, such

as If-Match, to the request and resubmit it.

428

The combined length of the URI and headers exceeds the 16,384-byte limit.431

An error has occurred within Lightning Platform, so the request couldn’t be completed. Contact Salesforce

Customer Support.

500

Salesforce Edge wasn’t able to communicate successfully with the Salesforce instance.502

The server is unavailable to handle the request. Typically this issue occurs if the server is down for maintenance

or is overloaded.

503

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 doesn’t exist

Requesting a resource that doesn’t exist, for example, you try to create a record using a misspelled object name

[

{

"message" : "The requested resource does not exist",

"errorCode" : "NOT_FOUND"

}

]

API End-of-Life Policy

See which REST API versions are supported, unsupported, or unavailable.

Salesforce is committed to supporting each API version for a minimum of 3 years from the date of first release. To improve the quality

and performance of the API, versions that are over 3 years old sometimes are no longer supported.

Salesforce notifies customers who use an API version scheduled for deprecation at least 1 year before support for the version ends.

Version Retirement InfoVersion Support StatusSalesforce API Versions

Supported.Versions 31.0 through 61.0

API End-of-Life PolicyIntroduction to REST API

Version Retirement InfoVersion Support StatusSalesforce API Versions

Salesforce Platform API Versions 21.0 through 30.0

Retirement

As of Summer ’22, these versions have been

deprecated and no longer supported by

Salesforce.

Starting Summer ’25, these versions will be

retired and unavailable.

Versions 21.0 through 30.0

Salesforce Platform API Versions 7.0 through 20.0

Retirement

As of Summer ’22, these versions are retired

and unavailable.

Versions 7.0 through 20.0

If you request any resource or use an operation from a retired API version, REST API returns the 410:GONE error code.

To identify requests made from old or unsupported API versions, use the API Total Usage event type.

API End-of-Life PolicyIntroduction to REST API

CHAPTER 2 Quick Start

To set up and run REST API, send a few basic requests to Salesforce. This Quick Start explains setting up

a basic environment and updating a record using REST API. You can set up and use REST API in many

ways, and the examples show how to use the free Developer Edition and cURL.

In this chapter ...

• Using cURL

• Step One: Sign up for

Salesforce Developer

Edition

• Step Two: Set Up

Authentication

• Step Three: Walk

Through the Sample

Code

• Using Other Tools

Using cURL

Get to know the formatting that you can use with cURL to make requests to Salesforce. This Quick Start uses cURL examples, but you

can use any tool or development environment that can make REST requests.

Familiarize yourself with cURL enough to be able to understand the examples in this guide and translate them into the tool that you’re

using. To attach files containing the body of the request, you must properly format the access token. Use these tips to help you use cURL

while working through the Quick Start. For more information about cURL, see curl.se.

Attach Request Bodies

Many examples include request bodies—JSON or XML files that contain data for the request. When using cURL, save these files to your

local system and attach them to the request using the —data-binary or -d option.

This example attaches the new-account.json file.

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/ -H

"Authorization: Bearer

00DE0X0A0M0PeLE!AQcAQH0dMHEXAMPLEzmpkb58urFRkgeBGsxL_QJWwYMfAbUeeG7c1EXAMPLEDUkWe6H34r1AAwOR8B8fLEz6nEXAMPLE"

-H "Content-Type: application/json" —d @new-account.json -X POST

Handle Exclamation Marks in Access Tokens

When you run cURL examples, you can get an error on macOS and Linux systems due to the presence of the exclamation mark (!) in

OAuth access tokens. To avoid getting this error, either escape the exclamation mark or use single quotes. To escape the exclamation

mark in the access token, insert a backslash before it when the access token is enclosed in double quotes.

For example, the access token string in this cURL command has the exclamation mark (!) escaped.

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

00DE0X0A0M0PeLE\!AQcAQH0dMHEXAMPLEzmpkb58urFRkgeBGsxL_QJWwYMfAbUeeG7c1EXAMPLEDUkWe6H34r1AAwOR8B8fLEz6nEXAMPLE"

Or, you can enclose the access token within single quotes to not escape the exclamation mark.

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

00DE0X0A0M0PeLE!AQcAQH0dMHEXAMPLEzmpkb58urFRkgeBGsxL_QJWwYMfAbUeeG7c1EXAMPLEDUkWe6H34r1AAwOR8B8fLEz6nEXAMPLE"

Important: All quotes, whether single or double, must be straight quotes, not curly quotes.

Step One: Sign up for Salesforce Developer Edition

Developer Edition provides a free and easy solution so that you can use Salesforce for testing and development.

To sign up for a Developer Edition account, go to developer.salesforce.com/signup.

Note: The Developer Edition data storage maximum is 5 MB. This limit doesn’t prevent you from working with these examples.

If you have a development sandbox, you can use it with these examples.

Using cURLQuick Start

Before you begin, verify that your user profile has the API Enabled permission by following the instructions in User Permissions in Salesforce

Help.

SEE ALSO:

Salesforce Help: User Permissions

Knowledge Article: Salesforce editions with API access

Step Two: Set Up Authentication

To successfully send requests, REST API requires an access token obtained by authentication. Although you can create and authenticate

against your own connected app, these Quick Start examples use Salesforce CLI for convenience. Salesforce CLI is a connected app that

you can authenticate, and it requires no work to configure.

Get an Access Token with Salesforce CLI

Use the access token (also known as a “bearer token”) that you get from Salesforce CLI to authenticate cURL requests.

1. Install or update Salesforce CLI. .

a. If you already have Salesforce CLI installed, update it using the instructions in Update Salesforce CLI.

b. If you need to Install Salesforce CLI, install the latest version for your operating system.

c. Verify Your Installation.

2. Log in to your Developer org with Salesforce CLI.

sf org login web

A browser opens to https://login.salesforce.com.

3. In the browser, log in to your Developer org with your user’s credentials.

4. In the browser, click Allow to allow access.

At the command line, you see a similar confirmation message.

Successfully authorized [email protected] with org ID

00D5fORGIDEXAMPLE

5. At the command line, get the access token by viewing authentication information about your org.

sf org display --target-org <username>

For example:

sf org display --target-org [email protected]

Example command output:

=== Org Description

KEY VALUE

───────────────

────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Step Two: Set Up AuthenticationQuick Start

Access Token

00DE0X0A0M0PeLE!AQcAQH0dMHEXAMPLEzmpkb58urFRkgeBGsxL_QJWwYMfAbUeeG7c1EXAMPLEDUkWe6H34r1AAwOR8B8fLEz6nEXAMPLE

Api Version 59.0

Client Id PlatformCLI

Created By [email protected]

Created Date 2023-11-16T20:35:21.000+0000

Dev Hub Id [email protected]

Edition Developer

Expiration Date 2023-11-23

Id 00D5fORGIDEXAMPLE

Instance Url https://MyDomainName.my.salesforce.com

Org Name Dreamhouse

Signup Username [email protected]

Status Active

Username [email protected]

In the command output, make note of the long Access Token string and the Instance Url string. You need both to make cURL requests.

Note: To get a new token after your access token expires, repeat this step of viewing your authentication information.

Optional Salesforce CLI Shortcuts

After you’ve authenticated successfully, try out these optional shortcuts in your cURL workflow to streamline future authentication with

the Salesforce CLI.

List My Orgs

sf org list

Lists all the orgs that you’ve created or authenticated to.

Open My Org

sf org open --target-org <username>

Opens the specified org (identified by username or alias) in your browser. Because you’ve successfully authenticated with this org

previously using the org login web Salesforce CLI command, it’s not required to provide your credentials again.

Display the Access Token for My Org

sf org display --target-org <username>

Output includes your access token, client ID, connected status, org ID, instance URL, username, and alias, if applicable.

Set an Alias for My Username

For convenience, create an alias for your username so that you don’t have to enter the entire Salesforce string. For example, instead of

[email protected]

Create an alias like

dev

Step Two: Set Up AuthenticationQuick Start

To set the alias in this example, run

sf alias set dev [email protected]

Use These Commands in a Script

Use the CLI’s JSON output by invoking the --json flag. Requesting JSON output provides a consistent output format, which is ideal

for running scripts. Without the --json flag, the CLI can change the output format.

SEE ALSO:

Salesforce Help: Authorize Apps with OAuth

Step Three: Walk Through the Sample Code

To access different types of resources in Salesforce, make a series of REST requests. Before you try these examples, make sure to complete

the prerequisites and obtain an access token in Step 1 of this Quick Start.

You can copy and paste these examples to send them with cURL. But first replace MyDomainName in the base URI with your Salesforce

domain. For information on the anatomy of a REST request, see REST Resources and Requests on page 3.

Get the Salesforce Version

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

authentication.

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

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

Content-Length: 88

Content-Type: application/json;

charset=UTF-8 Server:

[

{

"label":"Spring '11",

"url":"/services/data/v21.0",

"version":"21.0"

}

...

]

Get a List of Resources

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

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

access_token"

Step Three: Walk Through the Sample CodeQuick Start

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

{

"sobjects" : "/services/data/v61.0/sobjects",

"search" : "/services/data/v61.0/search",

"query" : "/services/data/v61.0/query",

"recent" : "/services/data/v61.0/recent"

}

Get a List of Available Objects

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

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/ -H "Authorization:

Bearer access_token"

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

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/v61.0/sobjects/Account",

"describe" : "/services/data/v61.0/sobjects/Account/describe",

"rowTemplate" : "/services/data/v61.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 },

...

Step Three: Walk Through the Sample CodeQuick Start

Get Basic Object Information

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

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/ -H

"Authorization: Bearer access_token"

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

accounts.

{

"objectDescribe" :

{

"name" : "Account",

"updateable" : true,

"label" : "Account",

"keyPrefix" : "001",

...

"replicateable" : true,

"retrieveable" : true,

"undeletable" : true,

"triggerable" : true

"recentItems" :

[

{

"attributes" :

{

"type" : "Account",

"url" : "/services/data/v61.0/sobjects/Account/001D000000INjVeIAL"

"Id" : "001D000000INjVeIAL",

"Name" : "asdasdasd"

...

]

}

Get a List of Fields

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

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/describe/

-H "Authorization: Bearer access_token"

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

{

"name" : "Account",

"fields" :

[

Step Three: Walk Through the Sample CodeQuick Start

{

"length" : 18,

"name" : "Id",

"type" : "id",

"defaultValue" : { "value" : null },

"updateable" : false,

"label" : "Account ID",

...

"updateable" : true,

"label" : "Account",

...

"urls" :

{

"uiEditTemplate" : "https://MyDomainName.my.salesforce.com/{ID}/e",

"sobject" : "/services/data/v61.0/sobjects/Account",

"uiDetailTemplate" : "https://MyDomainName.my.salesforce.com/{ID}",

"describe" : "/services/data/v61.0/sobjects/Account/describe",

"rowTemplate" : "/services/data/v61.0/sobjects/Account/{ID}",

"uiNewRecord" : "https://MyDomainName.my.salesforce.com/001/e"

"childRelationships" :

[

{

"field" : "ParentId",

"deprecatedAndHidden" : false,

...

"createable" : true,

"customSetting" : false,

...

}

Execute a SOQL Query

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

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/query?q=SELECT+name+from+Account

-H "Authorization: Bearer access_token"

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

{

"done" : true,

"totalSize" : 14,

"records" :

[

{

Step Three: Walk Through the Sample CodeQuick Start

"attributes" :

{

"type" : "Account",

"url" : "/services/data/v61.0/sobjects/Account/001D000000IRFmaIAH"

"Name" : "Test 1"

{

"attributes" :

{

"type" : "Account",

"url" : "/services/data/v61.0/sobjects/Account/001D000000IomazIAB"

"Name" : "Test 2"

...

]

}

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

Update a Field on a Record

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

patchaccount.json containing the new billing city information.

{

"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 to update a REST resource. This cURL command retrieves the specified Account object

using its ID field and updates its billing city.

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/001D000000IroHJ

-H "Authorization: Bearer access_token" -H "Content-Type: application/json" --data-binary

@patchaccount.json -X PATCH

No response body is returned, just the headers.

HTTP/1.1 204 No Content

Server:

Content-Length: 0

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

Using Other Tools

Other tools are available to obtain data from your Salesforce org.

If you don’t want to use CURL, you can use other tools to exercise the API. Possible choices include:

Using Other ToolsQuick Start

•

Salesforce CLI.

•

Postman (a third-party tool). For more information, see the Postman API Client Trailhead module.

These tools provide functionality that simplifies the process of creating and sending many API requests.

Using Other ToolsQuick Start

CHAPTER 3 Examples

This section provides examples of using REST API resources to do a variety of different tasks, including

working with objects, organization information, and queries.

In this chapter ...

• Getting Information

About My

Organization

For complete reference information on REST API resources, see Reference on page 127.

• Working with Object

Metadata

• Working with

Records

• Delete Lightning

Experience Event

Series

• Working with

Searches and

Queries

• Get an Image from a

Rich Text Area Field

• Insert or Update Blob

Data

• Get Blob Data

• Working with

SEE ALSO:

Versions

List Org Limits

Use the Limits resource to list your org limits.

•

Max is the limit for the org.

•

Remaining is the number of calls or events left for the org.

Example usage

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/limits/ -H

"Authorization: Bearer token" -H "X-PrettyPrint:1"

Example request body

none required

List Org LimitsExamples

Example response body

{

"ActiveScratchOrgs": {

"Max": 3,

"Remaining": 3

"AnalyticsExternalDataSizeMB": {

"Max": 40960,

"Remaining": 40960

"ConcurrentAsyncGetReportInstances": {

"Max": 200,

"Remaining": 200

"ConcurrentEinsteinDataInsightsStoryCreation": {

"Max": 5,

"Remaining": 5

"ConcurrentEinsteinDiscoveryStoryCreation": {

"Max": 2,

"Remaining": 2

"ConcurrentSyncReportRuns": {

"Max": 20,

"Remaining": 20

"DailyAnalyticsDataflowJobExecutions": {

"Max": 60,

"Remaining": 60

"DailyAnalyticsUploadedFilesSizeMB": {

"Max": 51200,

"Remaining": 51200

"DailyFunctionsApiCallLimit" : {

"Max" : 235000,

"Remaining" : 235000

"DailyApiRequests": {

"Max": 5000,

"Remaining": 4937

"DailyAsyncApexExecutions": {

"Max": 250000,

"Remaining": 250000

"DailyAsyncApexTests": {

"Max": 500,

"Remaining": 500

"DailyBulkApiBatches": {

"Max": 15000,

"Remaining": 15000

List Org LimitsExamples

"DailyBulkV2QueryFileStorageMB": {

"Max": 976562,

"Remaining": 976562

"DailyBulkV2QueryJobs": {

"Max": 10000,

"Remaining": 10000

"DailyDeliveredPlatformEvents" : {

"Max" : 10000,

"Remaining" : 10000

"DailyDurableGenericStreamingApiEvents": {

"Max": 10000,

"Remaining": 10000

"DailyDurableStreamingApiEvents": {

"Max": 10000,

"Remaining": 10000

"DailyEinsteinDataInsightsStoryCreation": {

"Max": 1000,

"Remaining": 1000

"DailyEinsteinDiscoveryPredictAPICalls": {

"Max": 50000,

"Remaining": 50000

"DailyEinsteinDiscoveryPredictionsByCDC": {

"Max": 5000000,

"Remaining": 5000000

"DailyEinsteinDiscoveryStoryCreation": {

"Max": 100,

"Remaining": 100

"DailyGenericStreamingApiEvents": {

"Max": 10000,

"Remaining": 10000

"DailyScratchOrgs": {

"Max": 6,

"Remaining": 6

"DailyStandardVolumePlatformEvents": {

"Max": 10000,

"Remaining": 10000

"DailyStreamingApiEvents": {

"Max": 10000,

"Remaining": 10000

"DailyWorkflowEmails": {

List Org LimitsExamples

"Max": 100000,

"Remaining": 100000

"DataStorageMB": {

"Max": 1024,

"Remaining": 1024

"DurableStreamingApiConcurrentClients": {

"Max": 20,

"Remaining": 20

"FileStorageMB": {

"Max": 1024,

"Remaining": 1024

"HourlyAsyncReportRuns": {

"Max": 1200,

"Remaining": 1200

"HourlyDashboardRefreshes": {

"Max": 200,

"Remaining": 200

"HourlyDashboardResults": {

"Max": 5000,

"Remaining": 5000

"HourlyDashboardStatuses": {

"Max": 999999999,

"Remaining": 999999999

"HourlyLongTermIdMapping": {

"Max": 100000,

"Remaining": 100000

"HourlyManagedContentPublicRequests": {

"Max": 50000,

"Remaining": 50000

"HourlyODataCallout": {

"Max": 20000,

"Remaining": 20000

"HourlyPublishedPlatformEvents": {

"Max": 50000,

"Remaining": 50000

"HourlyPublishedStandardVolumePlatformEvents": {

"Max": 1000,

"Remaining": 1000

"HourlyShortTermIdMapping": {

"Max": 100000,

"Remaining": 100000

List Org LimitsExamples

"HourlySyncReportRuns": {

"Max": 500,

"Remaining": 500

"HourlyTimeBasedWorkflow": {

"Max": 1000,

"Remaining": 1000

"MassEmail": {

"Max": 5000,

"Remaining": 5000

"MonthlyEinsteinDiscoveryStoryCreation": {

"Max": 500,

"Remaining": 500

"Package2VersionCreates": {

"Max": 6,

"Remaining": 6

"Package2VersionCreatesWithoutValidation": {

"Max": 500,

"Remaining": 500

"PermissionSets": {

"Max": 1500,

"Remaining": 1499,

"CreateCustom": {

"Max": 1000,

"Remaining": 999

}

"PrivateConnectOutboundCalloutHourlyLimitMB": {

"Max": 0,

"Remaining": 0

"SingleEmail": {

"Max": 5000,

"Remaining": 5000

"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.

List Available REST ResourcesExamples

Example

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/ -H "Authorization:

Bearer token"

Example request body

none required

Example JSON response body

{

"tooling" : "/services/data/v61.0/tooling",

"metadata" : "/services/data/v61.0/metadata",

"eclair" : "/services/data/v61.0/eclair",

"folders" : "/services/data/v61.0/folders",

"prechatForms" : "/services/data/v61.0/prechatForms",

"contact-tracing" : "/services/data/v61.0/contact-tracing",

"jsonxform" : "/services/data/v61.0/jsonxform",

"chatter" : "/services/data/v61.0/chatter",

"payments" : "/services/data/v61.0/payments",

"tabs" : "/services/data/v61.0/tabs",

"appMenu" : "/services/data/v61.0/appMenu",

"quickActions" : "/services/data/v61.0/quickActions",

"queryAll" : "/services/data/v61.0/queryAll",

"commerce" : "/services/data/v61.0/commerce",

"wave" : "/services/data/v61.0/wave",

"iot" : "/services/data/v61.0/iot",

"analytics" : "/services/data/v61.0/analytics",

"search" : "/services/data/v61.0/search",

"smartdatadiscovery" : "/services/data/v61.0/smartdatadiscovery",

"identity" : "https://MyDomainName.my.salesforce.com/id/

00DRO0000008aXd2AI/005RO000000HfnkYAC",

"composite" : "/services/data/v61.0/composite",

"parameterizedSearch" : "/services/data/v61.0/parameterizedSearch",

"fingerprint" : "/services/data/v61.0/fingerprint",

"theme" : "/services/data/v61.0/theme",

"nouns" : "/services/data/v61.0/nouns",

"domino" : "/services/data/v61.0/domino",

"event" : "/services/data/v61.0/event",

"serviceTemplates" : "/services/data/v61.0/serviceTemplates",

"recent" : "/services/data/v61.0/recent",

"connect" : "/services/data/v61.0/connect",

"licensing" : "/services/data/v61.0/licensing",

"limits" : "/services/data/v61.0/limits",

"process" : "/services/data/v61.0/process",

"dedupe" : "/services/data/v61.0/dedupe",

"async-queries" : "/services/data/v61.0/async-queries",

"query" : "/services/data/v61.0/query",

"jobs" : "/services/data/v61.0/jobs",

"localizedvalue" : "/services/data/v61.0/localizedvalue",

"mobile" : "/services/data/v61.0/mobile",

"emailConnect" : "/services/data/v61.0/emailConnect",

"consent" : "/services/data/v61.0/consent",

"tokenizer" : "/services/data/v61.0/tokenizer",

"compactLayouts" : "/services/data/v61.0/compactLayouts",

List Available REST ResourcesExamples

"async" : "/services/data/v61.0/async",

"sobjects" : "/services/data/v61.0/sobjects",

"actions" : "/services/data/v61.0/actions",

"support" : "/services/data/v61.0/support"

}

Example XML response body

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

<urls>

<tooling>/services/data/v61.0/tooling</tooling>

<metadata>/services/data/v61.0/metadata</metadata>

<eclair>/services/data/v61.0/eclair</eclair>

<folders>/services/data/v61.0/folders</folders>

<prechatForms>/services/data/v61.0/prechatForms</prechatForms>

<contact-tracing>/services/data/v61.0/contact-tracing</contact-tracing>

<jsonxform>/services/data/v61.0/jsonxform</jsonxform>

<chatter>/services/data/v61.0/chatter</chatter>

<payments>/services/data/v61.0/payments</payments>

<tabs>/services/data/v61.0/tabs</tabs>

<appMenu>/services/data/v61.0/appMenu</appMenu>

<quickActions>/services/data/v61.0/quickActions</quickActions>

<queryAll>/services/data/v61.0/queryAll</queryAll>

<commerce>/services/data/v61.0/commerce</commerce>

<wave>/services/data/v61.0/wave</wave>

<iot>/services/data/v61.0/iot</iot>

<analytics>/services/data/v61.0/analytics</analytics>

<search>/services/data/v61.0/search</search>

<smartdatadiscovery>/services/data/v61.0/smartdatadiscovery</smartdatadiscovery>

<identity>https://MyDomainName.my.salesforce.com/id/

00DRO0000008aXd2BI/005RO000000HfnkYAB</identity>

<composite>/services/data/v61.0/composite</composite>

<parameterizedSearch>/services/data/v61.0/parameterizedSearch</parameterizedSearch>

<fingerprint>/services/data/v61.0/fingerprint</fingerprint>

<theme>/services/data/v61.0/theme</theme>

<nouns>/services/data/v61.0/nouns</nouns>

<domino>/services/data/v61.0/domino</domino>

<event>/services/data/v61.0/event</event>

<serviceTemplates>/services/data/v61.0/serviceTemplates</serviceTemplates>

<recent>/services/data/v61.0/recent</recent>

<connect>/services/data/v61.0/connect</connect>

<licensing>/services/data/v61.0/licensing</licensing>

<limits>/services/data/v61.0/limits</limits>

<process>/services/data/v61.0/process</process>

<dedupe>/services/data/v61.0/dedupe</dedupe>

<async-queries>/services/data/v61.0/async-queries</async-queries>

<query>/services/data/v61.0/query</query>

<jobs>/services/data/v61.0/jobs</jobs>

<localizedvalue>/services/data/v61.0/localizedvalue</localizedvalue>

<mobile>/services/data/v61.0/mobile</mobile>

<emailConnect>/services/data/v61.0/emailConnect</emailConnect>

<consent>/services/data/v61.0/consent</consent>

<tokenizer>/services/data/v61.0/tokenizer</tokenizer>

<compactLayouts>/services/data/v61.0/compactLayouts</compactLayouts>

<async>/services/data/v61.0/sobjects</async>

List Available REST ResourcesExamples

<sobjects>/services/data/v61.0/sobjects</sobjects>

<actions>/services/data/v61.0/actions</actions>

<support>/services/data/v61.0/support</support>

</urls>

Further Information

For information about the identity resource, see Identity URLs.

For the other resources, see Reference .

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://MyDomainName.my.salesforce.com/services/data/v61.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" : {

"sobject" : "/services/data/v61.0/sobjects/Account",

"describe" : "/services/data/v61.0/sobjects/Account/describe",

"rowTemplate" : "/services/data/v61.0/sobjects/Account/{ID}"

Get a List of ObjectsExamples

...

]

}

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 object’s 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 Describe Global resource. If you do, response metadata is returned only if an available object’s metadata has changed since the

provided date. If no metadata has 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 have been made to objects after March 23, 2015.

Example Describe Global request

/services/data/v61.0/sobjects

Example If-Modified-Since header used with request

If-Modified-Since: Tue, 23 Mar 2015 00:00:00 GMT

Example response body

No response body returned

Example response status code

HTTP/1.1 304 Not Modified

Date: Wed, 25 Jul 2015 00:05:46 GMT

If changes to an object were made after March 23, 2015, the response body contains metadata for all available objects. For an example,

see Get a List of Objects.

Working with Object Metadata

The examples in this section use REST API resources to retrieve object metadata information. For modifying or creating object metadata

information, see the Metadata API Developer Guide.

IN THIS SECTION:

Get Metadata for an Object

Use the sObject Basic Information resource to get metadata for an object.

Get Field and Other Metadata for an Object

Use the sObject Describe resource to retrieve all the metadata for an object, including information about each field, URLs, and child

relationships.

Get Object Metadata Changes

Use the sObject Describe resource and the If-Modified-Since HTTP header to determine if object metadata has changed.

Get a List of Objects If Metadata Has ChangedExamples

Get Metadata for an Object

Use the sObject Basic Information resource to get metadata for an object.

Example for getting Account metadata

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/ -H

"Authorization: Bearer token"

Example request body for getting Account metadata

none required

Example response body for getting Account metadata

{

"objectDescribe" :

{

"name" : "Account",

"updateable" : true,

"label" : "Account",

"keyPrefix" : "001",

...

"replicateable" : true,

"retrieveable" : true,

"undeletable" : true,

"triggerable" : true

"recentItems" :

[

{

"attributes" :

{

"type" : "Account",

"url" : "/services/data/v61.0/sobjects/Account/001D000000INjVeIAL"

"Id" : "001D000000INjVeIAL",

"Name" : "asdasdasd"

...

]

}

To get a complete description of an object, including field names and their metadata, see Get a List of Objects.

Get Field and Other Metadata for an Object

Use the sObject Describe resource to retrieve all the metadata for an object, including information about each field, URLs, and child

relationships.

Get Metadata for an ObjectExamples

Example

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/describe/

-H "Authorization: Bearer token"

Example request body

none required

Example response body

{

"name" : "Account",

"fields" :

[

{

"length" : 18,

"name" : "Id",

"type" : "id",

"defaultValue" : { "value" : null },

"updateable" : false,

"label" : "Account ID",

...

"updateable" : true,

"label" : "Account",

"keyPrefix" : "001",

"custom" : false,

...

"urls" :

{

"uiEditTemplate" : "https://MyDomainName.my.salesforce.com/{ID}/e",

"sobject" : "/services/data/v61.0/sobjects/Account",

"uiDetailTemplate" : "https://MyDomainName.my.salesforce.com/{ID}",

...

"childRelationships" :

[

{

"field" : "ParentId",

"deprecatedAndHidden" : false,

...

....

Get Field and Other Metadata for an ObjectExamples

"createable" : true,

"customSetting" : false,

...

}

For more information about the items in the request body, see DescribesObjectResult in the SOAP API Developers Guide.

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

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Merchandise__c/describe

-H "Authorization: Bearer token" -H "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 send

the request using the POST HTTP method. The response body contains the ID of the new 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.

Get Object Metadata ChangesExamples

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.

Get Field Values from a Standard Object Record

You use the GET method of the sObject Rows resource to retrieve field values from a record.

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.

Get a Record Using an External ID

You can use the GET method of the sObject Rows by External ID resource to get 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 standard and custom objects by constructing friendly URLs using the sObject Relationship

resource. This approach allows you to directly access records associated by relationships. Using friendly URLs is an easier alternative

to accessing records by obtaining object IDs from relationship fields and then inspecting the associated object ID record.

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 send the

request using the POST HTTP method. The response body contains the ID of the new record if the call is successful.

The following example request creates a new Account record, with the field values for the new record provided in newaccount.json.

Only the name field is specified in this example, but you could also provide values for other Account fields.

Example for creating a new Account

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/ -H

"Authorization: Bearer token" -H "Content-Type: application/json" -d "@newaccount.json"

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

{

"Name" : "Express Logistics and Transport"

}

Create a RecordExamples

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://MyDomainName.my.salesforce.com/services/data/v61.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 16.

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),

"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) {

Update a RecordExamples

// 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;

}

If you use an HTTP library that doesn't allow overriding or setting an arbitrary HTTP method name, you can send a POST request and

provide an override to the HTTP method via the query string parameter _HttpMethod. In the PATCH example, you can replace the

PostMethod line with one that doesn't use override:

PostMethod m = new PostMethod(url + "?_HttpMethod=PATCH");

SEE ALSO:

sObject Rows

Conditional Request Headers

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.

Example for deleting an Account record

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/001D000000INjVe

-H "Authorization: Bearer token" -X DELETE

Example request body

None needed

Example response body

None returned

Get Field Values from a Standard Object Record

You use the GET method of the sObject Rows resource to retrieve field values from a record.

You can specify the fields you want to retrieve with the optional fields parameter. If you specify fields that don’t exist or are inaccessible

to you by field-level security, a 400 error response is returned.

If you don’t use the fields parameter, the request retrieves all standard and custom fields from the record. These retrieved fields are

the same as the fields returned by an sObject Describe request for the object. Fields that are inaccessible to you by field-level security

are not returned in the response body.

In the following example, the Account Number and Billing Postal Code are retrieved from an Account.

Delete a RecordExamples

Example for retrieving values from fields on an Account object

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/001D000000INjVe

?fields=AccountNumber,BillingPostalCode -H "Authorization: Bearer token"

Example request body

None required

Example response body

{

"AccountNumber" : "CD656092",

"BillingPostalCode" : "27215",

}

Get Field Values from an External Object Record by Using the Salesforce

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.

In the following example, the Country__c custom field is retrieved from an external object that’s associated with a

non-high-data-volume external data source.

Example for retrieving values from fields on the Customer external object

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Customer__x/x01D0000000002RIAQ?fields=Country__c

-H "Authorization: Bearer token"

Example request body

None required

Example response body

{

"attributes" : {

"type" : "Customer__x",

"url" : "/services/data/v61.0/sobjects/Customer__x/x01D0000000002RIAQ"

"Country__c" : "Argentina",

"Id" : "x01D0000000002RIAQ"

}

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.

In the following example, the Country__c custom field is retrieved from an external object. Notice that the id (CACTU) isn’t a

Salesforce ID. Instead, it’s the External ID standard field of the external object.

Get Field Values from an External Object Record by Using the

Salesforce ID

Examples

Example for retrieving values from fields on the Customer external object

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Customer__x/CACTU?fields=Country__c

-H "Authorization: Bearer token"

Example request body

None required

Example response body

{

"attributes" : {

"type" : "Customer__x",

"url" : "/services/data/v61.0/sobjects/Customer__x/CACTU"

"Country__c" : "Argentina",

"ExternalId" : "CACTU"

}

Get a Record Using an External ID

You can use the GET method of the sObject Rows by External ID resource to get 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://MyDomainName.my.salesforce.com/services/data/v61.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/v61.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,

Get a Record Using an External IDExamples

"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.

Important: Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain

terms to avoid any effect on customer implementations.

•

If the external ID isn’t matched, then a new record is created according to the request body. To prevent a new record from being

created, use the updateOnly parameter.

•

If the external ID is matched one time, then the record is updated according to the request body.

•

If the external ID is matched multiple times, then a 300 error is reported, and the record isn’t created or updated.

The following sections show you how to work with the external ID resource to retrieve records by external ID and upsert records.

Note: In REST API, upsert uses external ids, not record ids. In Apex, however, upsert can be used with both external ids and record

ids. Be aware of the difference if you use both REST API and Apex.

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 doesn’t exist.

Example for upserting a record that doesn’t yet exist

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/customExtIdField__c/11999

-H "Authorization: Bearer token" -H "Content-Type: application/json" -d @newrecord.json

-X PATCH

If you want to update a record but not create it if it doesn't exist, add the updateOnly parameter to the URL. For example:

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/customExtIdField__c/11999?updateOnly=true

Example JSON request body newrecord.json file

{

"Name" : "California Wheat Corporation",

"Type" : "New Customer"

}

Example JSON response

The successful response is:

{

"id" : "00190000001pPvHAAU",

"errors" : [ ],

"success" : true,

"created": true

}

The HTTP status code is 201 (Created).

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

Note: The created parameter is present in the response in API version 46.0 and later. It doesn't appear in earlier versions.

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 16.

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, it’s omitted from the request. This pattern is useful when you’re writing code to upsert multiple records by different

external IDs and you don’t want to request a separate resource. POST using Id is available in API version 37.0 and later.

Example of inserting a record that doesn’t yet exist

curl https://MyDomainName.my.salesforce.com/services/data/v61.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"

}

Example JSON response

The successful response is:

{

"id" : "001D000000Kv3g5IAB",

"success" : true,

"errors" : [ ],

"created": true

}

The HTTP status code is 201 (Created).

Note: The created parameter is present in the response in API version 46.0 and later. It doesn't appear in earlier versions.

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://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/customExtIdField__c/11999

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

-H "Authorization: Bearer token" -H "Content-Type: application/json" -d @updates.json

-X PATCH

Example JSON request body updates.json file

{

"BillingCity" : "San Francisco"

}

Example JSON response

In API version 46.0 and later, the HTTP status code is 200 (OK) and the successful response is:

{

"id" : "001D000000Kv3g5IAB",

"success" : true,

"errors" : [ ],

"created": false

}

In API version 45.0 and earlier, the HTTP status code is 204 (No Content) and there isn’t a response body.

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 16.

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

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 record gets created and related to the

Merchandise__c record.

Example of upserting a record and referencing a related object

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Line_Item__c/LineItemExtID__c/456

-H "Authorization: Bearer token" -H "Content-Type: application/json" -d @new.json -X

PATCH

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

Example JSON request body new.json file

Notice that the related Merchandise__c record is referenced using the Merchandise__c’s external ID field.

{

"Name" : "LineItemCreatedViaExtID",

"Merchandise__r" :

{

"MerchandiseExtID__c" : 123

}

Example JSON response

The successful response is:

{

"id" : "a02D0000006YUHrIAO",

"errors" : [ ],

"success" : true,

"created": true

}

The HTTP status code is 201 (Created).

Note: The created parameter is present in the response in API version 46.0 and later. It doesn't appear in earlier versions.

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 16.

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"

}

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://MyDomainName.my.salesforce.com/services/data/v61.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

}

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

Example JSON response

In API version 46.0 and later, the HTTP status code is 200 (OK) and the successful response is:

{

"id" : "001D000000Kv3g5IAB",

"success" : true,

"errors" : [ ],

"created": false

}

In API version 45.0 and earlier, the HTTP status code is 204 (No Content) and there isn’t a response body.

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.

SEE ALSO:

sObject Rows by External ID

Traverse Relationships with Friendly URLs

You can traverse relationship fields in standard and custom objects by constructing friendly URLs using the sObject Relationship resource.

This approach allows you to directly access records associated by relationships. Using friendly URLs is an easier alternative to accessing

records by obtaining object IDs from relationship fields and then inspecting the associated object ID record.

Important: Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain

terms to avoid any effect on customer implementations.

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 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 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://MyDomainName.my.salesforce.com/services/data/v61.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://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/ParentOfChild__c/record

id/Child__r

Traverse Relationships with Friendly URLsExamples

Traversing Standard Objects

The standard object Contact contains a relationship field to the Account standard object. The following example retrieves the Account

record related to a Contact record.

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Contact/0035e00000PiemmAAB/Account

-H "Authorization: Bearer token"

Example request body for traversing a standard object relationship

none required

Example response body for traversing a standard object simple relationship

{

"attributes": {

"type": "Account",

"url": "/services/data/v61.0/sobjects/Account/0015e00000TwULCAA3"

"Id": "0015e00000TwULCAA3",

"IsDeleted": false,

"Name": "relationshipAccountName",

"PhotoUrl": "/services/images/photo/0015e00000TwULCAA3",

"OwnerId": "0055e000003E8ooAAC",

"CreatedDate": "2021-11-06T17:38:40.000+0000",

"CreatedById": "0055e000003E8ooAAC",

"LastModifiedDate": "2021-11-06T17:38:40.000+0000",

"LastModifiedById": "0055e000003E8ooAAC",

"SystemModstamp": "2021-11-06T17:38:40.000+0000",

"LastActivityDate": null,

"LastViewedDate": "2021-11-06T17:40:50.000+0000",

"LastReferencedDate": "2021-11-06T17:40:50.000+0000"

}

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://MyDomainName.my.salesforce.com/services/data/v61.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/v61.0/sobjects/Distributor__c/a03D0000003DUhcIAG"

"Id" : "a03D0000003DUhcIAG",

"OwnerId" : "005D0000001KyEIIA0",

"IsDeleted" : false,

"Name" : "Distributor1",

Traverse Relationships with Friendly URLsExamples

"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 can’t 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 don’t 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://MyDomainName.my.salesforce.com/services/data/v61.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://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Merchandise__c/a01D000000INjVe/Distributor__r

-H "Authorization: Bearer token" -d @update_info.json -X PATCH

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://MyDomainName.my.salesforce.com/services/data/v61.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.

Traverse Relationships with Friendly URLsExamples

Example traversing a relationship with multiple records

If we have a custom object named Merchandise__c that contains a master—detail 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://MyDomainName.my.salesforce.com/services/data/v61.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/v61.0/sobjects/Line_Item__c/a02D0000006YL7XIAW"

"Id" : "a02D0000006YL7XIAW",

"IsDeleted" : false,

"Name" : "LineItem1",

"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/v61.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,

Traverse Relationships with Friendly URLsExamples

"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 302 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/v61.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 don’t include any parameters. The final batch of records doesn’t

have a nextRecordsUrl field.

Example usage for retrieving the remaining results

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/query/01gD0000002HU6KIAW-2000

-H "Authorization: Bearer token"

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://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Merchandise__c/a01D000000INjVe/Distributor__r?fields=Location__c

-H "Authorization: Bearer token"

The JSON response data would look like the following:

{

"attributes" :

{

Traverse Relationships with Friendly URLsExamples

"type" : "Distributor__c",

"url" : "/services/data/v61.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://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Merchandise__c/a01D000000INjVe/Line_Items__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/v61.0/sobjects/Line_Item__c/a02D0000006YL7XIAW"

"Name" : "LineItem1",

"Units_Sold__c" : 10.0

{

"attributes" :

{

"type" : "Line_Item__c",

"url" : "/services/data/v61.0/sobjects/Line_Item__c/a02D0000006YL7YIAW"

"Name" : "LineItem2",

"Units_Sold__c" : 8.0

}

]

}

If any field listed in the fields parameter set isn’t 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 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 Deleted Records Within a Given TimeframeExamples

Example usage for getting a list of Merchandise__c records that were deleted between May 5th, 2013 and May 10th, 2013

curl https://MyDomainName.my/services/data/v61.0/sobjects/Merchandise__c/deleted/

?start=2013-05-05T00%3A00%3A00%2B00%3A00&end=2013-05-10T00%3A00%3A00%2B00%3A00 -H

"Authorization: Bearer token"

Example request body

None required

JSON example response body

{

"deletedRecords" :

[

{

"id" : "a00D0000008pQRAIA2",

"deletedDate" : "2013-05-07T22:07:19.000+0000"

}

"earliestDateAvailable" : "2013-05-03T15:57:00.000+0000",

"latestDateCovered" : "2013-05-08T21:20:00.000+0000"

}

XML example response body

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

<Merchandise__c>

<id>a00D0000008pQRAIA2</id>

</deletedRecords>

</Merchandise__c>

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.

Example usage for getting a list of Merchandise__c records that were updated between May 6th, 2013 and May 10th, 2013

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Merchandise__c/updated/

?start=2013-05-06T00%3A00%3A00%2B00%3A00&end=2013-05-10T00%3A00%3A00%2B00%3A00 -H

"Authorization: Bearer token"

Example request body

None required

JSON example response body

{

"ids" :

[

"a00D0000008pQR5IAM",

Get a List of Updated Records Within a Given TimeframeExamples

"a00D0000008pQRGIA2",

"a00D0000008pQRFIA2"

"latestDateCovered" : "2013-05-08T21:20:00.000+0000"

}

XML example response body

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

<Merchandise__c>

<ids>a00D0000008pQRGIA2</ids>

<ids>a00D0000008pQRFIA2</ids>

</Merchandise__c>

Delete Lightning Experience Event Series

Use the HTTP DELETE method to remove one or more IsRecurrence2 events in a series. You can remove a single event, all events following

and including a specific event, or an entire event series.

Delete a Single Event in a Series

Use the sObject Rows on page 149 resource to delete event records. To delete a single occurrence in a series, specify the event ID and

use the DELETE method on page 47 of the resource to delete a record.

Delete Multiple Events or All Events from a Series

To delete all events in a series from a specific occurrence and onwards, specify the event ID and use the DELETE method of the resource

to delete a record. When calling this method, IsRecurrence2 must be true and IsRecurrence2Exclusion must be false.

To delete an entire event series, specify the event ID of the first occurrence in the series and use the DELETE method of the resource to

delete a record.

Example for deleting multiple events or all events from a series

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Event/00Uxx0000000000/fromThisEventOnwards

-H "Authorization: Bearer token" -X DELETE

Example request body

None needed

Example response body after successfully deleting events

{

success: We’re deleting the selected events from the series. Wait for all events to be

removed.

}

Delete Lightning Experience Event SeriesExamples

Considerations

Deleting from an event onwards doesn’t support calls from events that:

•

Occurred before the original value of Recurrence2PatternStartDate.

•

Are defined as child events.

If the event series originated outside of Salesforce and the event ID of the first occurrence is unavailable, you can’t delete all events in a

series. Instead, delete events from a specific occurrence onwards.

Working with Searches and Queries

The examples in this section use REST API resources to search and query records using Salesforce Object Search Language (SOSL) and

Salesforce Object Query Language (SOQL), and other search APIs. For more information on SOSL and SOQL see the SOQL and SOSL

Reference.

IN THIS SECTION:

Execute a SOQL Query

Use the Query resource to execute a SOQL query that returns all the results in a single response, or if needed, returns part of the

results and a locator used to retrieve the remaining results.

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.

Get Feedback on Query Performance (Beta)

To get feedback on how Salesforce executes your query, report, or list view, use the Query resource along with the explain

parameter. Salesforce analyzes each query to find the optimal approach to obtain the query results. Depending on the query and

query filters, Salesforce uses an index or internal optimization. To return details on how Salesforce optimizes your query, without

actually running the query, use the explain parameter. Based on the response, decide whether to fine-tune the performance of

your query, like adding filters to make the query more selective.

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.

Get the Default Search Scope and Order

Use the Search Scope and Order resource to retrieve the default global search scope and order for the logged-in user, including any

pinned objects in the user’s search results page.

Get Search Result Layouts for Objects

Use the Search Result Layouts resource to retrieve the search result layout configuration for each object specified in the query string.

View Relevant Items

Use the Relevant Items resource to get a list of relevant records.

Execute a SOQL Query

Use the Query resource to execute a SOQL query that returns all the results in a single response, or if needed, returns part of the results

and a locator used to retrieve the remaining results.

Working with Searches and QueriesExamples

The following query requests the value from name fields from all Account records.

Example usage for executing a query

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/query/?q=SELECT+name,id+from+Account

-H "Authorization: Bearer token"

Example request body for executing a query

none required

Example response body for executing a query

{

"done" : true,

"totalSize" : 14,

"records" :

[

{

"attributes" :

{

"type" : "Account",

"url" : "/services/data/v61.0/sobjects/Account/001D000000IRFmaIAH"

"Name" : "Test 1"

{

"attributes" :

{

"type" : "Account",

"url" : "/services/data/v61.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 contains a field called nextRecordsUrl:

"nextRecordsUrl" : "/services/data/v61.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 don't include any parameters.

Example usage for retrieving the remaining query results

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/query/01gD0000002HU6KIAW-2000

-H "Authorization: Bearer token"

Example request body for retrieving the remaining query results

none required

Execute a SOQL QueryExamples

Example response body for retrieving the remaining query results

{

"done" : true,

"totalSize" : 3214,

"records" : [...]

}

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

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/queryAll/?q=SELECT+Name+from+Merchandise__c+WHERE+isDeleted+=+TRUE

-H "Authorization: Bearer token"

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/v61.0/sobjects/Merchandise__c/a00D0000008pQRAIX2"

"Name" : "Merchandise 1"

]

}

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/v61.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.

Execute a SOQL Query that Includes Deleted ItemsExamples

Although the nextRecordsUrl has query in the URL, it still provides the remaining results from the initial QueryAll request. The

remaining results include deleted records that matched the initial query.

Example usage for retrieving the remaining results

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/query/01gD0000002HU6KIAW-2000

-H "Authorization: Bearer token"

Example request body for retrieving the remaining results

none required

Example response body for retrieving the remaining results

{

"done" : true,

"totalSize" : 3214,

"records" : [...]

}

Get Feedback on Query Performance (Beta)

To get feedback on how Salesforce executes your query, report, or list view, use the Query resource along with the explain parameter.

Salesforce analyzes each query to find the optimal approach to obtain the query results. Depending on the query and query filters,

Salesforce uses an index or internal optimization. To return details on how Salesforce optimizes your query, without actually running

the query, use the explain parameter. Based on the response, decide whether to fine-tune the performance of your query, like adding

filters to make the query more selective.

Note: This feature is a Beta Service. Customer may opt to try such Beta Service in its sole discretion. Any use of the Beta Service

is subject to the applicable Beta Services Terms provided at Agreements and Terms.

The response contains one or more query execution plans, sorted from most optimal to least optimal. The most optimal plan is the plan

that’s used when the query, report, or list view is executed.

For more details on the fields returned when using explain, see the explain parameter in Query Options Headers. For more

information on making queries more selective, see Working with Very Large SOQL Queries in the Apex Developer Guide.

Example: Feedback on Query Performance

The following performance feedback query uses Merchandise__c:

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/query/?explain=

SELECT+Name+FROM+Merchandise__c+WHERE+CreatedDate+=+TODAY+AND+Price__c+>+10.0

The response body for a performance feedback query looks like this:

{

"plans" : [ {

"cardinality" : 1,

"fields" : [ "CreatedDate" ],

"leadingOperationType" : "Index",

"notes" : [ {

"description" : "Not considering filter for optimization because unindexed",

"fields" : [ "IsDeleted" ],

"tableEnumOrId" : "Merchandise__c"

Get Feedback on Query Performance (Beta)Examples

} ],

"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"

} ],

"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. If the query is executed, the first

plan is used. Both plans note that there’s no secondary optimization for filtering out records marked as deleted because the IsDeleted

field isn’t 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://MyDomainName.my.salesforce.com/services/data/v61.0/search/?q=FIND+%7BAcme%7D

-H "Authorization: Bearer token"

Example request body

None required

Example response body

{

"searchRecords" : [ {

"attributes" : {

"type" : "Account",

"url" : "/services/data/v61.0/sobjects/Account/001D000000IqhSLIAZ"

"Id" : "001D000000IqhSLIAZ",

}, {

"attributes" : {

"type" : "Account",

"url" : "/services/data/v61.0/sobjects/Account/001D000000IomazIAB"

Search for a StringExamples

"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://MyDomainName.my.salesforce.com/services/data/v61.0/parameterizedSearch/?q=Acme

-H "Authorization: Bearer token"

Account search for results containing Acme, returning the id and name fields

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/parameterizedSearch/?q=Acme&sobject=Account&Account.fields=id,name&Account.limit=10

-H "Authorization: Bearer token"

Example request body

None required

Example response body

{

"searchRecords" : [ {

"attributes" : {

"type" : "Account",

"url" : "/services/data/v61.0/sobjects/Account/001D000000IqhSLIAZ"

"Id" : "001D000000IqhSLIAZ"

}, {

"attributes" : {

"type" : "Account",

"url" : "/services/data/v61.0/sobjects/Account/001D000000IomazIAB"

"Id" : "001D000000IomazIAB"

} ]

}

Example response body with metadata parameter

Note: The metadata parameter is only returned if the request specified metadata=LABELS.

{

"searchRecords" : [ {

"attributes" : {

"type" : "Account",

"url" : "/services/data/v61.0/sobjects/Account/001D000000IqhSLIAZ"

"Id" : "001D000000IqhSLIAZ",

}, {

"attributes" : {

Search for a StringExamples

"type" : "Account",

"url" : "/services/data/v61.0/sobjects/Account/001D000000IomazIAB"

"Id" : "001D000000IomazIAB",

} ],

"metadata" : {

"entityetadata" : [ {

"entityName" : "Account",

"fieldMetadata" : [ {

"name" : "Name",

"label" : "Account Name"

} ]

}

Example Parameterized Search Using the POST Method

Execute a parameterized search using the POST method to access all search features available.

Example usage

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/parameterizedSearch

"Authorization: Bearer token" -H "Content-Type: application/json” -d "@search.json”

Example request body

None required

Example JSON file

{

"q":"Smith",

"fields" : ["id", "firstName", "lastName"],

"sobjects":[{"fields":["id", "NumberOfEmployees"],

"name": "Account",

"limit":20},

{"name": "Contact"}],

"in":"ALL",

"overallLimit":100,

"defaultLimit":10

}

Example response body

{

"searchRecords" : [ {

"attributes" : {

"type" : "Contact",

"url" : "/services/data/v61.0/sobjects/Contact/003xx000004TraiAAC"

"Id" : "003xx000004TraiAAC",

"FirstName" : "Smith",

"LastName" : "Johnson"

}, {

Search for a StringExamples

"attributes" : {

"type" : "Account",

"url" : "/services/data/v61.0/sobjects/Account/001xx000003DHXnAAO"

"Id" : "001xx000003DHXnAAO",

"NumberOfEmployees" : 100

} ]

}

SEE ALSO:

Parameterized Search

Get the Default Search Scope and Order

Use the Search Scope and Order resource to retrieve the default global search scope and order for the logged-in user, including any

pinned objects in the user’s search results page.

In the following example, the default global search scope of the logged-in user consists of the site, idea, case, opportunity, account, and

user objects, in the order in which they are returned in the response body.

Example usage

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/search/scopeOrder -H

"Authorization: Bearer token"

Example request body

none required

Example response body

[

{

"type":"Site",

"url":"/services/data/v61.0/sobjects/Site/describe"

{

"type":"Idea",

"url":"/services/data/v61.0/sobjects/Idea/describe"

{

"type":"Case",

"url":"/services/data/v61.0/sobjects/Case/describe"

{

"type":"Opportunity",

"url":"/services/data/v61.0/sobjects/Opportunity/describe"

{

"type":"Account",

"url":"/services/data/v61.0/sobjects/Account/describe"

{

"type":"User",

Get the Default Search Scope and OrderExamples

"url":"/services/data/v61.0/sobjects/User/describe"

}

]

Get Search Result Layouts for Objects

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://MyDomainName.my.salesforce.com/services/data/v61.0/search/layout/?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,

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

"format" : null,

"label" : "Name",

"name" : "Name"

{ "field" : "Account.Name",

"format" : null,

"label" : "Account Name",

"name" : "Account.Name"

Get Search Result Layouts for ObjectsExamples

{ "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"

{ "field" : "Lead.Email",

"format" : null,

"label" : "Email",

"name" : "Email"

{ "field" : "Lead.Status",

"format" : null,

"label" : "Lead Status",

"name" : "toLabel(Status)"

Get Search Result Layouts for ObjectsExamples

{ "field" : "Name.Alias",

"format" : null,

"label" : "Owner Alias",

"name" : "Owner.Alias"

}

]

View Relevant Items

Use the Relevant Items resource to get a list of relevant records.

Example usage for getting a list of the current user’s most relevant records

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/relevantItems

-H "Authorization: Bearer token"

Example request body

None required

Example response body

[ {

"apiName" : "Contact",

"key" : "003",

"label" : "Contacts",

"lastUpdatedId" : "135866748",

"recordIds" : [ "003xx000004TxBA" ]

}, { "apiName" : "Account",

"key" : "001",

"label" : "Accounts",

"lastUpdatedId" : "193640553",

"recordIds" : [ "001xx000003DWsT" ]

}, {

"apiName" : "User",

"key" : "005",

"label" : "Users",

"lastUpdatedId" : "-199920321",

"recordIds" : [ "005xx000001Svqw", "005xx000001SvwK", "005xx000001SvwA" ]

}, { "apiName" : "Case",

"key" : "069",

"label" : "Cases",

"lastUpdatedId" : "1033471693",

"recordIds" : [ "069xx0000000006", "069xx0000000001", "069xx0000000002" ]

} ]

Example usage for filtering the response to certain objects

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/relevantItems?sobjects=Account,User

-H "Authorization: Bearer token"

Example request body

None required

View Relevant ItemsExamples

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 user’s current list of relevant records to a previous version

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/relevantItems?lastUpdatedId=102959935

-H "Authorization: Bearer token"

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 user’s current list of relevant records to a previous version for a particular object

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/relevantItems?mode=MRU&sobjects=Account,Contact&Account.lastUpdatedId=102959935

-H "Authorization: Bearer token"

View Relevant ItemsExamples

Example request body

None required

Example response body

[ {

"apiName" : "Account",

"key" : "001",

"label" : "Accounts",

"lastUpdatedId" : "193640553",

"recordIds" : [ "001xx000003DWsT" ]

} ]

SEE ALSO:

sObject Relevant Items

Get an Image from a Rich Text Area Field

Use the sObject Rich Text Image Get resource to retrieve an image from a rich text area field. In this example, we retrieve an image from

a custom rich text field of a Lead record called LeadPhotoRichText__c. We assume that an image has already been uploaded

to this field.

Obtain the Image Reference ID

Before you can retrieve the image with a request, you must first obtain the refid from the rich text field. Use the sObject Rows on

page 149 resource to retrieve the field information for the Lead record.

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Lead/00Q112222233333

-H "Authorization: Bearer token"

Here’s an example of abridged output from the request.

{

"attributes": {

"type": "Lead",

"url": "/services/data/v51.0/sobjects/Lead/00Q112222233333"

"Id": "00Q112222233333",

"IsDeleted": false,

"MasterRecordId": null,

"LastName": "Smith",

"FirstName": "John",

...

"LeadPhotoRichText__c": "<img alt=\"johnSmithPhoto\"

src=\"https://MyDomainName.documentforce.com/servlet/rtaImage?eid=a005e000007Dksm&feoid=00N5e00000djU6Y&refid=0EM5e000000B9LQ\"></img>"

}

You can see from the LeadPhotoRichText__c field that the refid of the image is 0EM5e000000B9LQ. Use this value in the next

step to retrieve the image.

Get an Image from a Rich Text Area FieldExamples

Retrieve the Image

Use the Lead record ID, rich text field name, and image refid to retrieve the image. The response returns the image as encoded data

with the same file type as it was uploaded with. Save the returned data as an image file with the appropriate file type using the --output

filename parameter.

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Lead/00Q112222233333/richTextImageFields/LeadPhotoRichText__c/0EMR00000000A8V

-H "Authorization: Bearer token" --output "LeadPhoto.jpeg"

Insert or Update Blob Data

You can use the sObject Basic Information on page 143, sObject Rows on page 149, or sObject Collections on page 396 resources to insert

or update binary large objects (blobs) in Salesforce, such as images or PDFs. You can upload files or binary data of any type to any standard

object that contains a blob field.

To insert and update blob data, create a multipart request body. The first part of the request body contains non-binary field data, such

as the description or name of the new record. The second part contains the binary data of the file you’re uploading. The request body

must conform to the MIME multipart content-type standard. For more information, see the W3C Standard for multipart content types.

If you use the sObject Basic Information or sObject Rows resources, the maximum file size for uploads is 2 GB for ContentVersion objects

and 500 MB for all other eligible standard objects. If you use the sObject Collections resource, the maximum total size of all files in a

single request is 500 MB.

Note: You can insert or update blob data using a non-multipart message, but you are limited to 50 MB of text data or 37.5 MB

of base64–encoded data.

These sections provide examples of how to insert or update blob data using a multipart content-type request. The request bodies for

these examples use JSON formatting.

Inserting a Document with Blob Data

This example request and request body creates a Document record that contains the binary data of a PDF file. In addition to the binary

data of the file itself, the request body also specifies other field data, including the FolderId, which is required for the Document

object.

If you don’t have a Folder record for the new Document record in Salesforce, you must create one using the sObject Basic Information

resource before you can follow this example. Make sure the Type field of the Folder record is Document.

Tip: After you successfully send the request, you can view the new Document in Salesforce Classic. Salesforce Lightning doesn’t

display Documents in the user interface.

Example request for creating a Document

curl https://MyDomainName.my.salesforce.com/services/data/v61.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 Document

This request body represents the contents of NewDocument.json. The binary data for the PDF content has been omitted for

brevity and replaced with “Binary data goes here.” An actual request contains the full binary content.

--boundary_string

Content-Disposition: form-data; name="entity_document";

Insert or Update Blob DataExamples

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.

--boundary_string--

Example response body

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 with Blob Data

This example updates an existing Document record. Depending on the contents of the request body, you can update the fields of the

record, the binary data associated with it, or both.

If you want to update only the record fields, the request body doesn’t require the multipart content type.

Example request for updating binary data in a Document object

curl

https://MyDomainName.my.salesforce.com/services/data/v61.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 binary data in a Document object

This request body represents the contents of UpdateDocument.json. This example updates the binary data of the record, as

well as the Name and Keywords fields. If you want to update only the binary data, you can remove the lines of code with the

Name and Keywords fields.

Insert or Update Blob DataExamples

The binary data for the PDF content has been omitted for brevity and replaced with “Updated document binary goes here.” An actual

request contains 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

Error responses

See Status Codes and Error Responses.

Inserting a ContentVersion

This example inserts a new ContentVersion. In addition to the binary data of the file itself, this code also provides values for other fields,

such as the ReasonForChange and PathOnClient. This message contains the ContentDocumentId because a

ContentVersion is always associated with a ContentDocument.

Tip: The ContentVersion object doesn’t support updates. Therefore, you can’t update a ContentVersion. You can only insert a new

ContentVersion. You can see the results of your changes on the Content tab.

Example usage for inserting a ContentVersion

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/ContentVersion

-H "Authorization: Bearer token" -H "Content-Type: multipart/form-data;

boundary=\"boundary_string\"" --data-binary @NewContentVersion.json

Example request body for inserting a ContentVersion

This request body represents the contents of the file NewContentVersion.json. The binary data for the PDF content has

been omitted for brevity and replaced with “Binary data goes here.” An actual request contains the full binary content.

--boundary_string

Content-Disposition: form-data; name="entity_content";

Content-Type: application/json

{

"ContentDocumentId" : "069D00000000so2",

"ReasonForChange" : "Marketing materials updated",

"PathOnClient" : "Q1 Sales Brochure.pdf"

}

--boundary_string

Insert or Update Blob DataExamples

Content-Type: application/octet-stream

Content-Disposition: form-data; name="VersionData"; filename="Q1 Sales Brochure.pdf"

Binary data goes here.

--boundary_string--

Example response body for inserting a ContentVersion

{

"id" : "068D00000000pgOIAQ",

"errors" : [ ],

"success" : true

}

Error responses for inserting a ContentVersion

See Status Codes and Error Responses.

Using sObject Collections to Insert a Collection of Blob Records

This example inserts a collection of new Documents. In addition to the binary data of the files themselves, this code also specifies other

field data, such as the Description and Name for each record in the collection.

Tip: After you successfully send the request, you can view the new Document in Salesforce Classic. Salesforce Lightning doesn’t

display Documents in the user interface.

Attributes

If you’re using sObject Collections with blob data, you must specify certain attribute values in addition to type in the request

body’s attributes map.

DescriptionParameter

Required for blob data. A unique identifier for the binary part.binaryPartName

Required for blob data. The name of the field in which the binary data is inserted or

updated.

binaryPartNameAlias

Example for creating Documents

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/composite/sobjects/ -H

"Authorization: Bearer token" -H "Content-Type: multipart/form-data;

boundary=\"boundary_string\"" --data-binary @newdocuments.json

Example request body for creating Documents

This code is the contents of newdocuments.json. The binary data for the PDF content has been omitted for brevity and replaced

with “Binary data goes here.” An actual request contains the full binary content.

--boundary_string

Content-Disposition: form-data; name="collection"

Content-Type: application/json

{

"allOrNone" : false,

"records" :

[

Insert or Update Blob DataExamples

{

"attributes" :

{

"type" : "Document",

"binaryPartName": "binaryPart1",

"binaryPartNameAlias": "Body"

"Description" : "Marketing Brochure",

"FolderId" : "005xx000001Svs4AAC",

"Name" : "Brochure",

"Type" : "pdf"

{

"attributes" :

{

"type" : "Document",

"binaryPartName": "binaryPart2",

"binaryPartNameAlias": "Body"

"Description" : "Pricing Overview",

"FolderId" : "005xx000001Svs4AAC",

"Name" : "Pricing",

"Type" : "pdf"

}

]

}

--boundary_string

Content-Disposition: form-data; name="binaryPart1"; filename="Brochure.pdf"

Content-Type: application/pdf

Binary data goes here.

--boundary_string

Content-Disposition: form-data; name="binaryPart2"; filename="Pricing.pdf"

Content-Type: application/pdf

Binary data goes here.

--boundary_string--

Example response body for creating Documents

On success, the IDs of the new Documents are returned.

[

{

"id": "015xx00000013QjAAI",

"errors": [],

"success": true

{

"id": "015xx00000013QkAAI",

"errors": [],

"success": true

}

Insert or Update Blob DataExamples

]

For more information, see sObject Collections.

Multipart Message Considerations

Following are some considerations for the format of a multipart message when you insert or update blob data.

Boundary String

•

Separates the various parts of a multipart request body.

•

Must be specified in the Content-Type header of multipart request.

•

Can be up to 70 characters.

•

Can’t be a string value that appears anywhere in any part of the request body.

•

Includes a two hyphen (--) prefix for the first boundary string.

•

Includes a two hyphen (--) suffix for the last boundary string.

Content-Disposition Header

•

Required in each part of the request body.

•

Must have form-data as a value and a name attribute.

–

In the non-binary part of the request body, use any value for the name attribute.

–

For single documents, in the binary part of the request body, use the name attribute to specify the name of the blob data

field for the object. For example, the name of the blob data field for the Document object is Body.

–

For documents inserted or updated using sObject Collections, use the name attribute in each binary part of the request

body to specify a unique identifier for that part. These identifiers are referenced by the non-binary part of the request body.

•

Must contain a filename attribute for the binary part that represents the name of the local file.

Content-Type Header

•

Required in each part of the multipart request body.

•

Supports the application/json and application/xml content types for the non-binary part of the multipart

request body.

•

Supports any content type for the binary part of the multipart request body.

New Line

A new line must be added between the header and the data for each part of the multipart request body. As you can see in the

examples, a new line separates the Content-Type and Content-Disposition headers from the JSON or binary data.

SEE ALSO:

sObject Basic Information

sObject Rows

sObject Collections

Get Blob Data

Insert or Update Blob DataExamples

Get Blob Data

Use the sObject Blob Get resource to get blob data for a given record. To get blob data, a record with blob data must exist in Salesforce.

Only certain standard objects have blob fields, such as Attachment, ContentNote, ContentVersion, Document, Folder, and Note.

Note: The sObject Blob Get resource isn’t compatible with Composite API requests, because it returns binary data instead of data

in JSON or XML formats. Instead, make individual sObject Blob Get requests to retrieve blob data.

The following example gets the blob data for the Document record that was created in Insert or Update Blob Data on page 75.

Example for retrieving blob data from a Document record

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Document/015D0000000N3ZZIA0/body

-H "Authorization: Bearer token"

Example request body

none required

Example response body

Document body content is returned in binary form. The response content type isn’t JSON or XML since the returned data is binary.

You can save the returned binary data to a file to store and access it.

SEE ALSO:

Insert or Update Blob Data

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

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/recent/?limit=2 -H

"Authorization: Bearer token"

Get Blob DataExamples

Example request body

none required

Example response body

{

"attributes" :

{

"type" : "Account",

"url" : "/services/data/v61.0/sobjects/Account/a06U000000CelH0IAJ"

"Id" : "a06U000000CelH0IAJ",

"Name" : "Acme"

{

"attributes" :

{

"type" : "Opportunity",

"url" : "/services/data/v61.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 SOQL and SOSL Reference.

Example usage for executing a query that marks one Account record as recently viewed

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/query/?q=SELECT+Name+FROM+Account+LIMIT+1+FOR+VIEW

-H "Authorization: Bearer token"

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/v61.0/sobjects/Account/001D000000IRFmaIAH"

Mark Records as Recently ViewedExamples

"Name" : "Acme"

]

}

SEE ALSO:

Query

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.

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://MyDomainName.my.salesforce.com/services/data/v61.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

<isExpired>false</isExpired>

</Password>

Managing User PasswordsExamples

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://MyDomainName.my.salesforce.com/services/data/v61.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.

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://MyDomainName.my.salesforce.com/services/data/v61.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

<NewPassword>2sv0xHAuM</NewPassword>

</Result>

SEE ALSO:

sObject User Password

Manage User PasswordsExamples

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.

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://MyDomainName.my.salesforce.com/services/data/v61.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",

Working with Approval Processes and Process RulesExamples

"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://MyDomainName.my.salesforce.com/services/data/v61.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",

"processDefinitionNameOrId" : "PTO_Request_Process",

"skipEntryCriteria": "true"}]

}

Example JSON response body

[ {

"actorIds" : [ "005D00000015rY9IAI" ],

"entityId" : "001D000000I8mImIAJ",

"errors" : null,

"instanceId" : "04gD0000000Cvm5IAC",

"instanceStatus" : "Pending",

"newWorkitemIds" : [ "04iD0000000Cw6SIAS" ],

"success" : true } ]

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.

Example usage

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/process/approvals/ -H

"Authorization: Bearer token" -H "Content-Type: application/json" -d @approve.json"

Submit a Record for ApprovalExamples

Example request body approve.json file

{

"requests" : [{

"actionType" : "Approve",

"contextId" : "04iD0000000Cw6SIAS",

"nextApproverIds" : ["005D00000015rY9"],

"comments" : "this record is approved"}]

}

Example JSON response body

[ {

"actorIds" : null,

"entityId" : "001D000000I8mImIAJ",

"errors" : null,

"instanceId" : "04gD0000000CvmAIAS",

"instanceStatus" : "Approved",

"newWorkitemIds" : [ ],

"success" : true

} ]

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.

Example usage

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/process/approvals/ -H

"Authorization: Bearer token" -H "Content-Type: application/json" -d @reject.json"

Example request body reject.json file

{

"requests" : [{

"actionType" : "Reject",

"contextId" : "04iD0000000Cw6cIAC",

"comments" : "This record is rejected."}]

}

Example JSON response body

[ {

"actorIds" : null,

"entityId" : "001D000000I8mImIAJ",

"errors" : null,

"instanceId" : "04gD0000000CvmFIAS",

"instanceStatus" : "Rejected",

"newWorkitemIds" : [ ],

"success" : true

} ]

Reject a RecordExamples

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.

Example usage

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/process/approvals/ -H

"Authorization: Bearer token" -H "Content-Type: application/json" -d @bulk.json"

Example request body bulk.json file

{

"requests" :

[{

"actionType" : "Approve",

"contextId" : "04iD0000000Cw6r",

"comments" : "approving an account"

},{

"actionType" : "Submit",

"contextId" : "001D000000JRWBd",

"nextApproverIds" : ["005D00000015rY9"],

"comments" : "submitting an account"

},{

"actionType" : "Submit",

"contextId" : "003D000000QBZ08",

"comments" : "submitting a contact"

}]

}

Example JSON response body

[ {

"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" ],

Bulk ApprovalsExamples

"success" : true

} ]

Get a List of Process Rules

Use the Process Rules resource to get information about process rules.

Example usage

curl https://MyDomainName.my.salesforce.com/services/data/v61.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"

} ],

"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://MyDomainName.my.salesforce.com/services/data/v61.0/process/rules/Account/01QD0000000APli

-H "Authorization: Bearer token"

Example request body

none required

Example JSON response body

{

"actions" : [ {

"id" : "01VD0000000D2w7",

Get a List of Process RulesExamples

"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://MyDomainName.my.salesforce.com/services/data/v61.0/process/rules/ -H

"Authorization: Bearer token" -H "Content-Type: application/json" -d @rules.json"

Example request body rules.json file

{

"contextIds" : [

"001D000000JRWBd",

"001D000000I8mIm",

"001D000000I8aaf"]

}

Example JSON response body

{

"errors" : null,

"success" : true

}

Using Event Monitoring

These examples use REST API event monitoring data that contains information useful for assessing org usage trends and user behavior.

Event monitoring is accessed through the Lightning Platform SOAP API and REST API by way of the EventLogFile object. Therefore, you

can integrate log data with your own back-end storage and data marts to correlate data from multiple orgs and across disparate systems.

Note: For the supported event types that you can use with event monitoring, see Object Reference for Salesforce and Lightning

Platform: EventLogFile Object.

•

In the unlikely case where no log files are generated for 24 hours, contact Salesforce Customer Support.

•

Log data is read only. You can’t insert, update, or delete log data.

•

To determine which files were generated for your org, use the EventType field.

•

An event generates log data in real time. However, daily log files are generated during nonpeak hours the day after an event takes

place. Therefore, daily log file data is unavailable for at least 1 day after an event. For hourly log files, depending on event delivery

Trigger Process RulesExamples

and final processing time, expect an event to take place 3–6 hours from the time of the event to be available in the log file. However,

it can take longer.

•

Log files are generated only when at least one event of a type, represented by the EventType field, occurs for the day or hour.

If no events took place, the file isn’t generated.

•

Log files are available for 30 days after their CreatedDatein orgs with Event Monitoring licenses, after which they’re automatically

deleted. In all Developer Edition orgs, log files are available for 1 day.

•

All event monitoring logs are exposed to the API through the EventLogFile object. However, there’s no access through the user

interface, except through the Event Monitoring Analytics app.

•

Log files don’t count towards your org’s data or file storage allocations.

•

Event Monitoring log files aren’t a system of record for user activity. They’re a source of truth, but they aren’t durable. During Salesforce

site switches, instance refreshes, or unplanned system outages, data loss can occur. For example, if Salesforce moves your production

org instance, your event log files can have a gap in data. Salesforce makes commercially reasonable efforts to preserve event log file

data integrity and avoid data loss. When Salesforce performs a site switch or instance refresh, it uses an automated process to replicate

event logs.

•

Hourly event log files are provided for you to review events in your orgs on an accelerated basis. However, it’s possible that you don’t

get all event log data in hourly event log files, especially during site switches, instance refreshes, or unplanned system outages. For

complete data, use the daily log files.

•

If event transmission failures take too long to recover from, log files are retransmitted to ensure that they’re delivered at least one

time. As a result, latent log files can sometimes contain duplicate event data. When your application consumes latent log files, make

sure that your application handles duplicate event delivery.

•

When a daily incremental log file is delivered, a new file replaces the original file with the full set of available logs for that date. To

ensure that you’re looking at the most recent log file, check the CreatedDate field.

•

We recommend that you always query the EventLogFile object for new log files to ensure that you also include latent ones. To

identify newly created log files, use the EventLogFile CreatedDate field. Hourly and daily incremental logs are delivered differently.

For details, see Differences Between Hourly and 24-Hour Event Logs.

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 Get object

Delete Event Monitoring Data

You can delete event log files that contain a user’s log data. Deleting log files helps you comply with data protection and privacy

regulations and controls the information that others can access. You can’t delete individual rows from event logs. Instead, you must

delete the entire log file that contains the user activity.

Using Event MonitoringExamples

Query or View Hourly Event Log Files

To review events in your org on an accelerated basis, get event log files in hourly increments for recent activity. Hourly event log

files can give you quicker visibility into security anomalies and custom code performance issues.

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 REST API to describe event log files. Use a GET request like this:

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/EventLogFile/describe

-H "Authorization: Bearer token"

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 REST API to query event monitoring data. To retrieve event monitoring records based on LogDate and EventType,

use a GET request like this:

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/query?q=SELECT+Id+,+EventType+,+LogFile+

,+LogDate+,+LogFileLength+FROM+EventLogFile+WHERE+

LogDate+>+Yesterday+AND+EventType+=+'API' -H "Authorization: Bearer token"

Describe Event Monitoring Using RESTExamples

Example raw response

{

"totalSize" : 4,

"done" : true,

"records" : [ {

"attributes" : {

"type" : "EventLogFile",

"url" : "/services/data/v61.0/sobjects/EventLogFile/0ATD000000001bROAQ" }

"Id" : "0ATD000000001bROAQ",

"EventType" : "API",

"LogFile" : "/services/data/v61.0/sobjects/EventLogFile/0ATD000000001bROAQ/LogFile",

"LogDate" : "2014-03-14T00:00:00.000+0000",

"LogFileLength" : 2692.0

}, {

"attributes" : {

"type" : "EventLogFile",

"url" : "/services/data/v61.0/sobjects/EventLogFile/0ATD000000001SdOAI" },

"Id" : "0ATD000000001SdOAI",

"EventType" : "API",

"LogFile" :

"/services/data/v61.0/sobjects/EventLogFile/0ATD000000001SdOAI/LogFile",

"LogDate" : "2014-03-13T00:00:00.000+0000",

"LogFileLength" : 1345.0

}, {

"attributes" : {

"type" : "EventLogFile",

"url" : "/services/data/v61.0/sobjects/EventLogFile/0ATD000000003p1OAA" },

"Id" : "0ATD000000003p1OAA",

"EventType" : "API",

"LogFile" :

"/services/data/v61.0/sobjects/EventLogFile/0ATD000000003p1OAA/LogFile",

"LogDate" : "2014-06-21T00:00:00.000+0000",

"LogFileLength" : 605.0 },

{ "attributes" : {

"type" : "EventLogFile",

"url" : "/services/data/v61.0/sobjects/EventLogFile/0ATD0000000055eOAA" },

"Id" : "0ATD0000000055eOAA",

"EventType" : "API",

"LogFile" :

"/services/data/v61.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.

Get Event Monitoring Content from a RecordExamples

Example

You can use REST API to retrieve BLOB data for event monitoring. Use a GET request similar to this:

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/EventLogFile/0ATD000000000pyOAA/LogFile

-H "Authorization: Bearer token"

Example response body

Event monitoring content is returned in binary form. Note that the response content type won’t 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

"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-//MyDomainName-my-salesforce-com/00O/o",

"54"

"URI", "00DD0000000K5xD", "20130728185536.725", "005D0000001REI0",

"10.0.62.141", "/00OD0000001ckx3",

"https-//MyDomainName-my-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 Get 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://MyDomainName.my.salesforce.com/services/data/v61.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 Compression Headers.

Delete Event Monitoring Data

You can delete event log files that contain a user’s log data. Deleting log files helps you comply with data protection and privacy

regulations and controls the information that others can access. You can’t delete individual rows from event logs. Instead, you must

delete the entire log file that contains the user activity.

To delete an event log file, enable deletion in Setup, create a permission set that includes the Delete Event Monitoring Records user

permission, and assign this permission set to your users. (Alternatively, you can assign the user permission to a custom profile.) Then

those users can query and delete the EventLogFile record by using Query and Delete resources in REST or delete() in SOAP.

Download Large Event Log Files Using cURL with RESTExamples

Note: You can’t delete individual rows from event logs. Because event logs are stored in blob format in the database, you must

delete the entire log file that contains the user activity.

1. In Setup, in the Quick Find box, enter Event, and then select Event Monitoring Settings.

2. Enable deletion of event monitoring data. This action is recorded in Setup Audit Trail.

The Delete Event Monitoring Records user permission is now available to assign to a permission set. (Alternatively, you can assign

the user permission to a custom profile.)

3. In Setup, in the Quick Find box, enter Permission, and then select Permission Sets.

4. Create a permission set that includes the Delete Event Monitoring Records user permission, and save the permission set.

5. In Setup, in the Quick Find box, enter users, and then select Users.

6. Select the user you want to grant permission to delete event monitoring data.

7. In the Permission Set Assignment section for this user, assign the permission set, and click Save. This action is recorded in Setup

Audit Trail.

Users assigned this permission set (or any custom profile that includes the Delete Event Monitoring Records user permission) can

now delete event monitoring data. The next steps show you how to use the API to delete the data.

8. To locate the logs containing the user activity that you want to delete, query the EventLogFile object. For details, see Query Event

Monitoring Data with REST on page 92.

9. Note the IDs of the returned logs.

10. Use the sObject Rows resource to delete records. Specify the record ID, and use the DELETE method. For more information, see

Delete a Record on page 47.

Delete Event Monitoring DataExamples

Query or View Hourly Event Log Files

EDITIONS

Available in: Enterprise,

Performance, Unlimited,

and Developer Editions

USER PERMISSIONS

To access the API and query

log files:

• API Enabled AND View

Event Log Files

To view event log files:

• View All Data

To review events in your org on an accelerated basis, get event log files in hourly increments for

recent activity. Hourly event log files can give you quicker visibility into security anomalies and

custom code performance issues.

Examples

Suppose you’re a security analyst monitoring for anomalous user behavior. By pulling more frequent

updates into your security system, you can be alerted that a suspicious event has taken place within

hours, rather than one or two days later.

In another example, let’s say you’re a developer. You’ve identified a series of Apex failures in your

org, and you want to proactively refactor your Apex code to improve performance. You review

hourly log files to pinpoint the issues and fix your code in hours, before your end users start

complaining about poor performance.

Considerations

•

Hourly event log file integration with the Event Monitoring Analytics app is unavailable.

•

Depending on event delivery and final processing time, an event is expected to take three to

six hours from the time of the event to be available in the log file. However, it can take longer.

•

When delays in processing occur and event logs for a particular hour arrive later, a new log file is created for the event/date/hour

and lists only the new events. Use the creation date and an incremental sequence number to identify a new log file. Always use the

most recently processed event log file for a particular date. However, if event log files have already been pulled into a third-party

application, they could require deduplication in that application.

If both hourly and daily logs are enabled, daily logs always have a sequence number of 0 because there is only one file per daily

interval. CreatedDate indicates when the file was generated. If CreatedDate is after the last event log file download, there are new

events to be processed.

For best practices, use CreatedDate in the WHERE clause to select logs created after the last downloaded event log file. For example,

if the last downloaded file was at 12PM 2/1/2018, to find the next log file, use +CreatedDate+>+"2018-02-01T12:00:00Z" in the

WHERE clause.

•

Your event log files may show a gap in data during site switches, instance refreshes, or unplanned system outages. However, during

site switches and instance refreshes, Salesforce makes a commercially reasonable effort to avoid such data loss by using an automated

process to replicate event logs.

•

In the unlikely case in which no log files are generated for 24 hours, contact Salesforce Support.

IN THIS SECTION:

Query Hourly Event Log Files

You query hourly event log files in the same way you query 24-hour log files.

Differences Between Hourly and 24-Hour Event Logs

You receive event log files approximately every hour in addition to 24-hour log files. Review the differences between the two logs

so that you can filter your files to analyze the event data you want.

Query Hourly Event Log Files

You query hourly event log files in the same way you query 24-hour log files.

Query or View Hourly Event Log FilesExamples

Suppose you’re an administrator. Your Chief Security Officer asks you to identify who modified specific accounts and opportunities in

the past two hours. You query the hourly URI event log files using the EventLogFile object to review the page requests and request

status. Because EventLogFile also returns 24-hour log files, use this SOQL syntax to filter out the 24-hour log files.

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/query?q=SELECT+Id+,

+EventType+,+Interval+,+LogDate+,+LogFile+FROM+EventLogFile+WHERE+EventType+=+'URI'+

AND+Interval+=+'Hourly' -H "Authorization: Bearer token"

In the query, Interval=Hourly makes sure that only hourly event log file data is returned. Alternatively, you can use Sequence

to filter out 24-hour event log files (Sequence!=0). To get both hourly and 24-hour files, use Sequence>=0.

If your sandbox org has URI events, you see log file records in your query results. You can also download the event log files to review the

data in a CSV file. For more information, see Trailhead: Download and Visualize Event Log Files.

Differences Between Hourly and 24-Hour Event Logs

You receive event log files approximately every hour in addition to 24-hour log files. Review the differences between the two logs so

that you can filter your files to analyze the event data you want.

24-Hour Log FilesHourly Log Files

One file generated for every 24 hours of activity.One or more files generated for every hour of activity.

Available in the API and integrated with the Event Monitoring

Analytics app and third-party visualization apps.

Available in the API. You can manually import data into third-party

visualization apps.

Key values in the EventLogFile object are:Key values in the EventLogFile object are:

•

Interval—Daily

•

Interval—Hourly

•

CreatedDate—Timestamp of when the log file was

created. Use this field to identify new files.

•

CreatedDate—Timestamp of when the log file was

created. Use this field to identify new files.

•

LogDate—Timestamp that marks the beginning of the

interval when the events occurred. For example, for events

•

LogDate—Timestamp that marks the beginning of the

interval when the events occurred. For example, for events

that occurred between 11:00 AM and 12:00 PM on 3/7/2016,

this field’s value is 2016-03-07T11:00:00.000Z.

that occurred on 3/7/2016, this field’s value is

2016-03-07T00:00:00.000+0000.

•

Sequence—1+. This value increases by 1 when events are

added in the same hour after the latest event log file is created.

The value resets to 1 in the subsequent hour.

•

Sequence—0

See also these Considerations regarding hourly event logs.

When a daily incremental log file is delivered, a new file replaces

the original file with the full set of available logs for that date. The

CreatedDate field is updated.

When an hourly incremental log file is delivered, a file with new

logs for that hour is created. The Sequence field is incremented

for each new file.

Note: Like with 24-hour event monitoring, hourly event log data is available for the past 30 days.

Query or View Hourly Event Log FilesExamples

Using Composite Resources

The examples in this section use composite resources to improve your application’s performance by minimizing the number of round-trips

between the client and server.

IN THIS SECTION:

Execute Dependent Requests in a Single API Call

The following example uses the Composite resource to execute several dependent requests all in a single call. First, it creates an

account and retrieves its information. Next it uses the account data and the Composite resource’s reference ID functionality to create

a contact and populate its fields based on the account data. Then it retrieves specific information about the account’s owner by

using query parameters in the request string. Finally, if the metadata has been modified since a certain date, it retrieves account

metadata. The composite.json file contains the composite request and subrequest data.

Update an Account, Create a Contact, and Link Them with a Junction Object

The following example uses the Composite resource to update some fields on an account, create a contact, and link the two records

with a junction object called AccountContactJunction. All these requests are executed in a single call. The

composite.json file contains the composite request and subrequest data.

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

Use the Composite Batch resource to execute multiple requests in a single API call.

Upsert an Account and Create a Contact

The following example uses the Composite resource to upsert an account and create a contact that is linked to the account. All these

requests are executed in a single call. The composite.json file contains the composite request and subrequest data.

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 record’s 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 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 record’s 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.

Using Composite Graphs

Composite graphs provide an enhanced way to perform composite requests, which execute a series of REST API requests in a single

call.

Using a Composite Graph

This example shows how to use a composite graph. It also demonstrates how one request can use more than one composite graph.

allOrNone Parameters in Composite and Collections Requests

If a Composite request uses sObject Collections, there are two or more allOrNone parameters that can interact, one on the

Composite request and one on each sObject Collections subrequest.

Using Composite ResourcesExamples

Execute Dependent Requests in a Single API Call

The following example uses the Composite resource to execute several dependent requests all in a single call. First, it creates an account

and retrieves its information. Next it uses the account data and the Composite resource’s reference ID functionality to create a contact

and populate its fields based on the account data. Then it retrieves specific information about the account’s owner by using query

parameters in the request string. Finally, if the metadata has been modified since a certain date, it retrieves account metadata. The

composite.json file contains the composite request and subrequest data.

Execute dependent requests in a single API call

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/composite/ -H

"Authorization: Bearer token -H "Content-Type: application/json" -d "@composite.json"

Request body composite.json file

{

"allOrNone" : true,

"compositeRequest" : [{

"method" : "POST",

"url" : "/services/data/v61.0/sobjects/Account",

"referenceId" : "NewAccount",

"body" : {

"Name" : "Salesforce",

"BillingStreet" : "Landmark @ 1 Market Street",

"BillingCity" : "San Francisco",

"BillingState" : "California",

"Industry" : "Technology"

}

},{

"method" : "GET",

"referenceId" : "NewAccountInfo",

"url" : "/services/data/v61.0/sobjects/Account/@{NewAccount.id}"

},{

"method" : "POST",

"referenceId" : "NewContact",

"url" : "/services/data/v61.0/sobjects/Contact",

"body" : {

"lastname" : "John Doe",

"Title" : "CTO of @{NewAccountInfo.Name}",

"MailingStreet" : "@{NewAccountInfo.BillingStreet}",

"MailingCity" : "@{NewAccountInfo.BillingAddress.city}",

"MailingState" : "@{NewAccountInfo.BillingState}",

"AccountId" : "@{NewAccountInfo.Id}",

"Email" : "[email protected]",

"Phone" : "1234567890"

}

},{

"method" : "GET",

"referenceId" : "NewAccountOwner",

"url" :

"/services/data/v61.0/sobjects/User/@{NewAccountInfo.OwnerId}?fields=Name,companyName,Title,City,State"

},{

"method" : "GET",

"referenceId" : "AccountMetadata",

Execute Dependent Requests in a Single API CallExamples

"url" : "/services/data/v61.0/sobjects/Account/describe",

"httpHeaders" : {

"If-Modified-Since" : "Tue, 31 May 2016 18:13:37 GMT"

}

}]

}

Response body after successfully executing the composite request

{

"compositeResponse" : [{

"body" : {

"id" : "001R00000033JNuIAM",

"success" : true,

"errors" : [ ]

"httpHeaders" : {

"Location" : "/services/data/v61.0/sobjects/Account/001R00000033JNuIAM"

"httpStatusCode" : 201,

"referenceId" : "NewAccount"

},{

"body" : {

all the account data

"httpHeaders" : {

"ETag" : "\"Jbjuzw7dbhaEG3fd90kJbx6A0ow=\"",

"Last-Modified" : "Fri, 22 Jul 2016 20:19:37 GMT"

"httpStatusCode" : 200,

"referenceId" : "NewAccountInfo"

},{

"body" : {

"id" : "003R00000025REHIA2",

"success" : true,

"errors" : [ ]

"httpHeaders" : {

"Location" : "/services/data/v61.0/sobjects/Contact/003R00000025REHIA2"

"httpStatusCode" : 201,

"referenceId" : "NewContact"

},{

"body" : {

"attributes" : {

"type" : "User",

"url" : "/services/data/v61.0/sobjects/User/005R0000000I90CIAS"

"Name" : "Jane Doe",

"CompanyName" : "Salesforce",

"Title" : Director,

"City" : "San Francisco",

"State" : "CA",

"Id" : "005R0000000I90CIAS"

100

Execute Dependent Requests in a Single API CallExamples

"httpHeaders" : { },

"httpStatusCode" : 200,

"referenceId" : "NewAccountOwner"

},{

"body" : null,

"httpHeaders" : {

"ETag" : "\"f2293620\"",

"Last-Modified" : "Fri, 22 Jul 2016 18:45:56 GMT"

"httpStatusCode" : 304,

"referenceId" : "AccountMetadata"

}]

}

Update an Account, Create a Contact, and Link Them with a Junction Object

The following example uses the Composite resource to update some fields on an account, create a contact, and link the two records

with a junction object called AccountContactJunction. All these requests are executed in a single call. The composite.json

file contains the composite request and subrequest data.

Update an account, create a contact, and link them with a junction object

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/composite/ -H

"Authorization: Bearer token -H "Content-Type: application/json" -d "@composite.json"

Request body composite.json file

{

"allOrNone" : true,

"compositeRequest" : [{

"method" : "PATCH",

"url" : "/services/data/v61.0/sobjects/Account/001xx000003DIpcAAG",

"referenceId" : "UpdatedAccount",

"body" : {

"Name" : "Salesforce",

"BillingStreet" : "Landmark @ 1 Market Street",

"BillingCity" : "San Francisco",

"BillingState" : "California",

"Industry" : "Technology"

}

},{

"method" : "POST",

"referenceId" : "NewContact",

"url" : "/services/data/v61.0/sobjects/Contact/",

"body" : {

"lastname" : "John Doe",

"Phone" : "1234567890"

}

},{

"method" : "POST",

"referenceId" : "JunctionRecord",

"url" : "/services/data/v61.0/sobjects/AccountContactJunction__c",

"body" : {

"accountId__c" : "001xx000003DIpcAAG",

101

Update an Account, Create a Contact, and Link Them with

a Junction Object

Examples

"contactId__c" : "@{NewContact.id}"

}

}]

}

Response body after successfully executing the composite request

{

"compositeResponse" : [{

"body" : null,

"httpHeaders" : { },

"httpStatusCode" : 204,

"referenceId" : "UpdatedAccount"

}, {

"body" : {

"id" : "003R00000025R22IAE",

"success" : true,

"errors" : [ ]

"httpHeaders" : {

"Location" : "/services/data/v61.0/sobjects/Contact/003R00000025R22IAE"

"httpStatusCode" : 201,

"referenceId" : "NewContact"

}, {

"body" : {

"id" : "a00R0000000iN4gIAE",

"success" : true,

"errors" : [ ]

"httpHeaders" : {

"Location" :

"/services/data/v61.0/sobjects/AccountContactJunction__c/a00R0000000iN4gIAE"

"httpStatusCode" : 201,

"referenceId" : "JunctionRecord"

}]

}

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

Use the Composite 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 account’s 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://MyDomainName.my.salesforce.com/services/data/v61.0/composite/batch/ -H

"Authorization: Bearer token -H "Content-Type: application/json" -d "@batch.json"

Request body batch.json file

{

"batchRequests" : [

102

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

{

"method" : "PATCH",

"url" : "v61.0/sobjects/account/001D000000K0fXOIAZ",

"richInput" : {"Name" : "NewName"}

},{

"method" : "GET",

"url" : "v61.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/v61.0/sobjects/Account/001D000000K0fXOIAZ"

"Name" : "NewName",

"BillingPostalCode" : "94105",

"Id" : "001D000000K0fXOIAZ"

}

}]

}

SEE ALSO:

Composite Batch

Upsert an Account and Create a Contact

The following example uses the Composite resource to upsert an account and create a contact that is linked to the account. All these

requests are executed in a single call. The composite.json file contains the composite request and subrequest data.

Upsert an account and create a contact

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/composite/ -H

"Authorization: Bearer token -H "Content-Type: application/json" -d "@composite.json"

Request body composite.json file

{

"allOrNone" : true,

"compositeRequest": [{

"method": "PATCH",

"url": "/services/data/v61.0/sobjects/Account/ExternalAcctId__c/ID12345",

"referenceId": "NewAccount",

"body": {

"Name": "Acme"

103

Upsert an Account and Create a ContactExamples

}

},{

"method" : "POST",

"url" : "/services/data/v61.0/sobjects/Contact",

"referenceId" : "newContact",

"body" : {

"LastName" : "Harrison",

"AccountId" : "@{NewAccount.id}"

}

}]

}

Response body after successfully executing the composite request

{

"compositeResponse" : [{

"body" : {

"id" : "0016g00000Wqu1EAAR",

"success" : true,

"errors" : [ ],

"created" : true

"httpHeaders" : {

"Location" : "/services/data/v61.0/sobjects/Account/0016g00000Wqu1EAAR"

"httpStatusCode" : 201,

"referenceId" : "NewAccount"

},{

"body" : {

"id" : "0036g00000WKnfLAAT",

"success" : true,

"errors" : [ ]

"httpHeaders" : {

"Location" : "/services/data/v61.0/sobjects/Contact/0036g00000WKnfLAAT"

"httpStatusCode" : 201,

"referenceId" : "newContact"

}]

}

SEE ALSO:

sObject Rows by External ID

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 record’s 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.

104

Create Nested RecordsExamples

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://MyDomainName.my.salesforce.com/services/data/v61.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"

}]

"Contacts" : {

"records" : [{

"attributes" : {"type" : "Contact", "referenceId" : "ref6"},

"lastname" : "Jones",

"title" : "President",

"email" : "[email protected]"

}]

}

105

Create Nested RecordsExamples

}]

}

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 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 record’s 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.

Example for creating four new accounts

curl https://MyDomainName.my.salesforce.com/services/data/v61.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", "referenceId" : "ref1"},

"name" : "SampleAccount1",

106

Create Multiple RecordsExamples

"phone" : "1111111111",

"website" : "www.salesforce.com",

"numberOfEmployees" : "100",

"industry" : "Banking"

},{

"attributes" : {"type" : "Account", "referenceId" : "ref2"},

"name" : "SampleAccount2",

"phone" : "2222222222",

"website" : "www.salesforce2.com",

"numberOfEmployees" : "250",

"industry" : "Banking"

},{

"attributes" : {"type" : "Account", "referenceId" : "ref3"},

"name" : "SampleAccount3",

"phone" : "3333333333",

"website" : "www.salesforce3.com",

"numberOfEmployees" : "52000",

"industry" : "Banking"

},{

"attributes" : {"type" : "Account", "referenceId" : "ref4"},

"name" : "SampleAccount4",

"phone" : "4444444444",

"website" : "www.salesforce4.com",

"numberOfEmployees" : "2500",

"industry" : "Banking"

}]

}

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"

}]

}

SEE ALSO:

sObject Tree

Using Composite Graphs

Composite graphs provide an enhanced way to perform composite requests, which execute a series of REST API requests in a single call.

107

Using Composite GraphsExamples

•

Regular composite requests allow you to execute a series of REST API requests in a single call. And you can use the output of one

request as the input to a subsequent request.

•

Composite graphs extend regular composite requests by allowing you to assemble a more complicated and complete series of

related objects and records.

•

Composite graphs also enable you to ensure that the steps in a given set of requests are either all completed or all not completed.

If you use this option, you don’t have to check which requests were successful.

•

Regular composite requests have a limit of 25 subrequests. Composite graphs increase this limit to 500.

Defining Composite Graphs

In general, a graph is a collection of connected nodes.

In the context of composite graph operations, the nodes are composite subrequests. For example, a node can be a composite subrequest

like this:

{

"url" : "/services/data/v61.0/sobjects/Account/",

"body" : {

"name" : "Cloudy Consulting"

"method" : "POST",

"referenceId" : "reference_id_account_1"

}

Each node features an endpoint representing a record.

Composite graph requests support only these URLs.

Supported HTTP MethodsURL

POST

See sObject Basic Information.

/services/data/vXX.X/sobjects/sObject

DELETE, GET, PATCH

See sObject Rows.

/services/data/vXX.X/sobjects/sObject/id

DELETE, GET, PATCH, POST

See sObject Rows by External ID.

/services/data/vXX.X/sobjects/sObject/customFieldName/externalId

108

Using Composite GraphsExamples

A composite graph can be directed meaning that some nodes use information from other nodes. For example, a node that creates a

Contact can use the ID of an Account node to link the Contact with the Account.

For example:

{

"graphs": [{

"graphId": "graph1",

"compositeRequest": [{

"body": {

"name": "Cloudy Consulting"

"method": "POST",

"referenceId": "reference_id_account_1",

"url": "/services/data/v61.0/sobjects/Account/"

{

"body": {

"FirstName": "Nellie",

"LastName": "Cashman",

"AccountId": "@{reference_id_account_1.id}"

"method": "POST",

"referenceId": "reference_id_contact_1",

"url": "/services/data/v61.0/sobjects/Contact/"

}

]

}]

}

Defining Composite Graphs in JSON

A composite graph is defined in JSON like this:

{

"graphId" : "graphId",

graph

}

In other words, like this, where each compositeSubrequest is a composite subrequest:

{

"graphId" : "graphId",

"compositeRequest" : [

compositeSubrequest,

...

]

}

109

Using Composite GraphsExamples

The graphId parameters enable you to identify the graphs when viewing the response. They need not be numeric, but they must

follow these restrictions:

•

They must be unique within each composite graph operation.

•

They must begin with an alphanumeric character.

•

They must be less that 40 characters long.

•

They can’t contain a period (’.’).

A single composite graph request can use one or more composite graphs. See Using a Composite Graph.

Example: Create Accounts, Contacts, Campaigns, Opportunities, Leads, and

CampaignMembers with a Composite Graph Request

This example shows a composite graph that performs the following actions:

1. Create Account 1.

2. Create Account 2 as a child of Account 1.

3. Create:

a. Contact 1, linked to Account 2.

b. Contact 2, who reports to Contact 1.

c. Contact 3 who reports to Contact 2.

4. Create a Campaign.

5. Create an Opportunity linked to Account 2 and the Campaign.

6. Create a Lead.

7. Create a CampaignMember linked to the Lead and the Campaign.

The JSON for this graph is:

{

"graphId" : "1",

"compositeRequest" : [

{

"url" : "/services/data/v61.0/sobjects/Account/",

"body" : {

"name" : "Cloudy Consulting",

110

Using Composite GraphsExamples

"description" : "Parent account"

"method" : "POST",

"referenceId" : "reference_id_account_1"

{

"url" : "/services/data/v61.0/sobjects/Account/",

"body" : {

"name" : "Easy Spaces",

"description" : "Child account",

."ParentId" : "@{reference_id_account_1.id}"

"method" : "POST",

"referenceId" : "reference_id_account_2"

{

"url" : "/services/data/v61.0/sobjects/Contact/",

"body" : {

"FirstName" : "Sam",

"LastName" : "Steele",

"AccountId" : "@{reference_id_account_2.id}"

"method" : "POST",

"referenceId" : "reference_id_contact_1"

{

"url" : "/services/data/v61.0/sobjects/Contact/",

"body" : {

"FirstName" : "Charlie",

"LastName" : "Dawson",

"ReportsToId" : "@{reference_id_contact_1.id}"

"method" : "POST",

"referenceId" : "reference_id_contact_2"

{

"url" : "/services/data/v61.0/sobjects/Contact/",

"body" : {

"FirstName" : "Nellie",

"LastName" : "Cashman",

"ReportsToId" : "@{reference_id_contact_2.id}"

"method" : "POST",

"referenceId" : "reference_id_contact_3"

{

"url" : "/services/data/v61.0/sobjects/Campaign/",

"body" : {

"name" : "Spring Campaign"

"method" : "POST",

"referenceId" : "reference_id_campaign"

{

111

Using Composite GraphsExamples

"url" : "/services/data/v61.0/sobjects/Opportunity/",

"body" : {

"name" : "Opportunity",

"stageName" : "Value Proposition",

"closeDate" : "2025-12-31",

"CampaignId" : "@{reference_id_campaign.id}",

"AccountId" : "@{reference_id_account_2.id}"

"method" : "POST",

"referenceId" : "reference_id_opportunity"

{

"url" : "/services/data/v61.0/sobjects/Lead/",

"body" : {

"FirstName" : "Belinda",

"LastName" : "Mulroney",

"Company" : "Klondike Quarry",

"Email" : "[email protected]"

"method" : "POST",

"referenceId" : "reference_id_lead"

{

"url" : "/services/data/v61.0/sobjects/CampaignMember/",

"body" : {

"CampaignId" : "@{reference_id_campaign.id}",

"LeadId" : "@{reference_id_lead.id}"

"method" : "POST",

"referenceId" : "reference_id_campaignmember"

}

]

}

Example: GET Details About a Resource and Then Use Them in a Composite Graph

Request

This example shows how you can use GET on a resource, and then use properties of that resource in subsequent requests.

{

"graphs" : [

{

"graphId" : "graph1",

"compositeRequest" : [

{

"method" : "GET",

"url" : "/services/data/v61.0/sobjects/Account/001R0000003fSRrIAM",

"referenceId" : "refAccount"

{

"body" : {

"name" : "Amazing opportunity for @{refAccount.Name}",

"StageName" : "Stage 1",

112

Using Composite GraphsExamples

"CloseDate" : "2025-06-01T23:28:56.782Z",

"AccountId" : "@{refAccount.Id}"

"method" : "POST",

"url" : "/services/data/v61.0/sobjects/Opportunity",

"referenceId" : "newOpportunity"

}

]

}

]

}

Graph Depth

•

Nodes with no parents are considered to be at depth 1.

•

The depth of another node is the maximum number of edges in the graph from depth 1 to that node. An edge between two nodes

occurs when the one node uses a property (such as @{reference_account.id} ) from another node.

The AllOrNone Parameter

In standard composite operations, the only control over what happens if an error occurs is the allOrNone parameter. If the value is

true, the entire composite request is rolled back. If the value is false, the remaining subrequests that don’t depend on the failed

subrequest are executed. Dependent subrequests aren’t executed, which can lead to a mix of processed and unprocessed records.

Composite graphs have the advantage that each graph is guaranteed to either complete all its subrequests successfully or to be rolled

back completely. In other words, the allOrNone parameter is implicitly considered to be true for each graph. A composite graph

request never results in a mix of processed and unprocessed records.

To ensure that graphs are independent, the following rules apply.

1. Subrequests in one graph can’t reference subrequests from another graph.

2. Each graph in one composite graph operation must be independent. If one graph can’t be processed successfully, that must not

prevent other graphs in the same operation from being processed.

Best Practices

As a general practice, keep your graphs as small as possible. For example, it’s more efficient to have 50 graphs with 10 nodes rather than

1 graph with 500 nodes. Keeping graphs small has two advantages:

•

If one item in a graph fails, only the items in that graph are rolled back. It’s easier to identify and handle errors in smaller graphs.

•

The server can process multiple, smaller graphs faster and more efficiently.

113

Using Composite GraphsExamples

Example: Submitting a Composite Graph Job

For an example showing how to submit a composite graph job, see Using a Composite Graph.

Using a Composite Graph

This example shows how to use a composite graph. It also demonstrates how one request can use more than one composite graph.

•

Regular composite requests allow you to execute a series of REST API requests in a single call. And you can use the output of one

request as the input to a subsequent request.

•

Composite graphs extend regular composite requests by allowing you to assemble a more complicated and complete series of

related objects and records.

•

Composite graphs also enable you to ensure that the steps in a given set of requests are either all completed or all not completed.

If you use this option, you don’t have to check which requests were successful.

•

Regular composite requests have a limit of 25 subrequests. Composite graphs increase this limit to 500.

Create a request:

curl -X POST curl https://MyDomainName.my.salesforce.com/services/data/v61.0/composite/graph

-H "Authorization: Bearer token" -H "Content-Type: application/json" --data @data.json

where the file data.json contains the definition of the graphs. The general format for the request body is:

{

"graphs": [

{

"graphId": "graphId",

"compositeRequest": [

compositeSubrequest,

...

]

{

"graphId": "graphId",

"compositeRequest": [

compositeSubrequest,

...

]

...

]

}

where compositeSubrequest is a composite subrequest result on page 369.

For example, two composite graph requests each create an Account and then create related records:

{

"graphs" : [

{

"graphId" : "1",

114

Using a Composite GraphExamples

"compositeRequest" : [

{

"url" : "/services/data/v61.0/sobjects/Account/",

"body" : {

"name" : "Cloudy Consulting"

"method" : "POST",

"referenceId" : "reference_id_account_1"

{

"url" : "/services/data/v61.0/sobjects/Contact/",

"body" : {

"FirstName" : "Nellie",

"LastName" : "Cashman",

"AccountId" : "@{reference_id_account_1.id}"

"method" : "POST",

"referenceId" : "reference_id_contact_1"

{

"url" : "/services/data/v61.0/sobjects/Opportunity/",

"body" : {

"CloseDate" : "2024-05-22",

"StageName" : "Prospecting",

"Name" : "Opportunity 1",

"AccountId" : "@{reference_id_account_1.id}"

"method" : "POST",

"referenceId" : "reference_id_opportunity_1"

}

]

{

"graphId" : "2",

"compositeRequest" : [

{

"url" : "/services/data/v61.0/sobjects/Account/",

"body" : {

"name" : "Easy Spaces"

"method" : "POST",

"referenceId" : "reference_id_account_2"

{

"url" : "/services/data/v61.0/sobjects/Contact/",

"body" : {

"FirstName" : "Charlie",

"LastName" : "Dawson",

"AccountId" : "@{reference_id_account_2.id}"

"method" : "POST",

"referenceId" : "reference_id_contact_2"

}

]

115

Using a Composite GraphExamples

}

]

}

The response is:

{

"graphs" : [

{

"graphId" : "1",

"graphResponse" : {

"compositeResponse" : [

{

"body" : {

"id" : "001R00000064wc7IAA",

"success" : true,

"errors" : [ ]

"httpHeaders" : {

"Location" : "/services/data/v61.0/sobjects/Account/001R00000064wc7IAA"

"httpStatusCode" : 201,

"referenceId" : "reference_id_account_1"

{

"body" : {

"id" : "003R000000DDMlTIAX",

"success" : true,

"errors" : [ ]

"httpHeaders" : {

"Location" : "/services/data/v61.0/sobjects/Contact/003R000000DDMlTIAX"

"httpStatusCode" : 201,

"referenceId" : "reference_id_contact_1"

{

"body" : {

"id" : "006R0000003FPYxIAO",

"success" : true,

"errors" : [ ]

"httpHeaders" : {

"Location" :

"/services/data/v61.0/sobjects/Opportunity/006R0000003FPYxIAO"

"httpStatusCode" : 201,

"referenceId" : "reference_id_opportunity_1"

}

]

"isSuccessful" : true

116

Using a Composite GraphExamples

{

"graphId" : "2",

"graphResponse" : {

"compositeResponse" : [

{

"body" : {

"id" : "001R00000064wc8IAA",

"success" : true,

"errors" : [ ]

"httpHeaders" : {

"Location" : "/services/data/v61.0/sobjects/Account/001R00000064wc8IAA"

"httpStatusCode" : 201,

"referenceId" : "reference_id_account_2"

{

"body" : {

"id" : "003R000000DDMlUIAX",

"success" : true,

"errors" : [ ]

"httpHeaders" : {

"Location" : "/services/data/v61.0/sobjects/Contact/003R000000DDMlUIAX"

"httpStatusCode" : 201,

"referenceId" : "reference_id_contact_2"

}

]

"isSuccessful" : true

}

]

}

For more information, see Using Composite Graphs.

allOrNone Parameters in Composite and Collections Requests

If a Composite request uses sObject Collections, there are two or more allOrNone parameters that can interact, one on the Composite

request and one on each sObject Collections subrequest.

•

If the Composite request has allOrNone set to true, then the all-or-none behavior also applies to each of the sObject Collections

subrequests, overriding the value of allOrNone in the subrequests.

•

If the Composite request has allOrNone set to false, then each sObject Collections subrequest behaves according to its value

of allOrNone.

117

allOrNone Parameters in Composite and Collections RequestsExamples

Consider, for example, what happens with this job where a Composite request includes two items: an sObject Collections request and

a request to create a Contact. The sObject Collections request tries to create two Accounts, one of which fails because there is already

an existing Account with the same information.

POST https://MyDomainName.my.salesforce.com/services/data/v61.0/composite -H "Authorization:

Bearer token"

{

"allOrNone" : outerFlag,

"collateSubrequests" : false,

"compositeRequest" : [

{

"method" : "POST",

"url" : "/services/data/v61.0/composite/sobjects",

"body" : {

"allOrNone" : innerFlag,

"records" : [

{

"attributes" : { "type" : "Account" },

"Name" : "Northern Trail Outfitters",

"BillingCity" : "San Francisco"

{

"attributes" : { "type" : "Account" },

"Name" : "Easy Spaces",

"BillingCity" : "Calgary"

}

]

"referenceId" : "newAccounts"

{

"method" : "POST",

"url" : "/services/data/v61.0/sObject/Contact",

"body" : {

"FirstName" : "John",

"LastName" : "Smith"

"referenceId" : "newContact"

}

]

}

The outerFlag and innerFlag parameters are either true or false, which leads to four possible cases.

Case 1: outerFlag = false, innerFlag = false

In this case, neither request has allOrNone set to true, so neither request is rolled back. One account is created and one fails.

118

allOrNone Parameters in Composite and Collections RequestsExamples

Case 2: outerFlag = false, innerFlag = true

In this case, the inner sObject Collections request has allOrNone set to true, so it is rolled back. The outer Composite request is

not rolled back.

Case 3: outerFlag = true, innerFlag = true

In this case, both requests have allOrNone set to true, so they are both rolled back.

119

allOrNone Parameters in Composite and Collections RequestsExamples

Case 4: outerFlag = true, innerFlag = false

The response body for this case is:

{

"compositeResponse" : [

{

"body" : [

{

"id" : "001R00000066cndIAA",

"success" : true,

"errors" : [ ]

{

"success" : false,

"errors" : [

{

"statusCode" : "DUPLICATES_DETECTED",

"message" : "Use one of these records?",

"fields" : [ ]

}

]

}

"httpHeaders" : { },

"httpStatusCode" : 200,

"referenceId" : "collection1"

{

"body" : [

{

"errorCode" : "PROCESSING_HALTED",

"message" : "The transaction was rolled back since another operation in the

same transaction failed."

}

"httpHeaders" : { },

"httpStatusCode" : 400,

"referenceId" : "newContact"

120

allOrNone Parameters in Composite and Collections RequestsExamples

}

]

}

In this case, the inner sObject Collections request has allOrNone set to false, so it is not immediately rolled back. However, the

outer Composite request has allOrNone set to true so it is rolled back, which also rolls back the inner sObject Collections request.

Note: Even though the response body for sObject Collections request shows "success" : true for the creation of the

first Account, the fact that the Composite request is rolled back means that the Account creation is rolled back. The final result is

that the new Account is not created.

121

allOrNone Parameters in Composite and Collections RequestsExamples

CHAPTER 4 Generating an OpenAPI 3.0 Document for

sObjects REST API (Beta)

You can generate an OpenAPI document for sObjects REST API using this opt-in beta feature. The OpenAPI

document represents sObject REST API resources that reflect your customizations and configurations.

Note: This feature is a Beta Service. Customer may opt to try such Beta Service in its sole discretion.

Any use of the Beta Service is subject to the applicable Beta Services Terms provided at Agreements

and Terms.

Supported Editions

This beta feature is available to Developer Editions, Partner Developer Editions, sandboxes, and scratch

orgs that have API Enabled.

About the Document

The OpenAPI document adheres to Version 3.0.1 of the OpenAPI Specification. For more information,

see https://www.openapis.org.

Note: This beta OpenAPI document is subject to change. Don’t build production integrations

based on this OpenAPI document.

What the OpenAPI Document Covers

You can retrieve, create, and update object data with REST API resources that this OpenAPI document

describes.

•

/services/data/v61.0/sobjects

–

Lists the available objects and their metadata for your data. Provides the organization encoding,

and the maximum batch size permitted in queries.

–

See Describe Global.

•

/services/data/v61.0/sobjects/sObject

–

Describes the individual metadata for the specified object. Can create an object record. For

example, retrieve the metadata for the Account object using the GET method or create an

Account object using the POST method.

–

See sObject Basic Information.

•

/services/data/v61.0/sobjects/{sObject}/describe

–

Describes the individual metadata at all levels for sObjects

–

See sObject Describe.

•

/services/data/v61.0/sobjects/sObject/{id}

122

Accesses records based on the specified object ID. Retrieves, updates, or deletes records. Can

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.

–

See sObject Rows.

•

/services/data/v61.0/sobjects/{sObject}/deleted

–

Retrieves the list of individual deleted records within the timespan for sObjects

–

See sObject Get Deleted.

•

/services/data/vXX.X/sobjects/{sObject}/{id}/{blobField}

–

Retrieves the specified blob field from an individual record and returns it as binary data

–

See sObject Blob Get.

Enabling the Beta

To enable this beta, follow these steps. You must have either the Modify All Data or the Customize

Application permission.

1. From Setup, in the Quick Find box, enter User Interface, and then select User Interface.

2. On the User Interface page, select Enable Salesforce Platform REST API, OpenAPI 3.0 Spec

Generation (Beta).

Note: Selecting this item asserts that you accept the Beta Services Terms provided at the

Agreements and Terms.

Generate an OpenAPI Document

To generate the OpenAPI document, send a POST request to

https://MyDomainName.my.salesforce.com/services/data/vXX.X/async/specifications/oas3.

The API version XX.X must be the latest version. The request body must be:

{

"resources" : [ selectors ]

}

To get all resources, use a quoted asterisk ("*") as a selector.

{

"resources" : ["*"]

}

To get specific sections of the OpenAPI document, use one or more quoted targeted selectors:

•

"/services/data/v61.0/sobjects"

•

"/services/data/v61.0/sobjects/sObject" where sObject can be the name

of any standard or custom object that you have access to in your org

•

"/services/data/v61.0/sobjects/sObject/{id}"

123

Generating an OpenAPI 3.0 Document for sObjects REST API

(Beta)

•

"/services/data/v61.0/sobjects/sObject/deleted"

•

"/services/data/v61.0/sobjects/{sObject}/deleted"

•

"/services/data/v61.0/sobjects/sObject/describe"

•

"/services/data/v61.0/sobjects/{sObject}/describe"

•

"/services/data/v61.0/sobjects/{sObject}/{id}/{blobField}"

Note:

•

{blobField}, {id}, and {sObject} must be entered literally. They aren’t variables.

•

Don’t add trailing slashes at the end of a selector, For example,

"/services/data/v61.0/sobjects/" retrieves nothing.

•

For the /describe and /deleted selectors, you can use either {sObject} literally

or an object name. The response body for these requests is the same for all objects.

•

If the * selector is used, no other selectors are allowed. This selector can’t be combined with

any other selectors and must be used exactly as shown.

•

The API version in the POST and GET requests and in the resource body must be the latest

version.

For example:

{

"resources" : [

"/services/data/v61.0/sobjects",

"/services/data/v61.0/sobjects/Contact",

"/services/data/v61.0/sobjects/Lead",

"/services/data/v61.0/sobjects/Lead/{id}",

"/services/data/v61.0/sobjects/{sObject}/deleted",

"/services/data/v61.0/sobjects/Account/describe",

"/services/data/v61.0/sobjects/{sObject}/{id}/{blobField}"

]

}

A successful POST request returns a JSON response body containing a URI to view the details page and

a URI to get the OpenAPI document. The URIs contain a locator ID. In this example, the locator ID is

NTByUjAwMDAwMDAwMDBh.

HTTP/1.1 202 Accepted

{ "results" :

"/v61.0/async/specifications/oas3/NTByUjAwMDAwMDAwMDBh/results",

"details" : "/v61.0/async/specifications/oas3/NTByUjAwMDAwMDAwMDBh"}

If the server encounters errors processing the request, it reports a “Failed” status and returns a 4xx or 5xx

status.

You’re limited to one POST request every 6 hours. If you send another POST request within 6 hours the

server responds with an HTTP 429 status code and an error message containing the initial POST request’s

locator ID.

124

Generating an OpenAPI 3.0 Document for sObjects REST API

(Beta)

View the Details Page

You can check the status of your request to generate an OpenAPI document and view other information

from the details page. This is an example details page.

{

"name" : "OAS3",

"apiTaskStatus" : "INPROGRESS",

"errors" : [],

"createdById" : "005xxxxxxxxxxxx",

"version" : 61.0

}

To view the details page, send a GET request using this URL.

https://MyDomainName.my.salesforce.com/services/data/vXX.X/async/

specifications/oas3/locatorID

For example:

https://MyDomainName.my.salesforce.com/services/data/vXX.X/async/

specifications/oas3/NTByUjAwMDAwMDAwMDBh

The API version in the GET request must be the latest version.

View the OpenAPI Document

To view the OpenAPI document for the target sObjects, sent a GET request using this URL.

https://MyDomainName.my.salesforce.com/services/data/vXX.X/async/

specifications/oas3/locatorID/results

For example:

https://MyDomainName.my.salesforce.com/services/data/vXX.X/async/

specifications/oas3/NTByUjAwMDAwMDAwMDBh/results

The server responds with the OpenAPI document. For example:

HTTP/1.1 200 OK{

"openapi": "3.0.1",

"info": {

"title": "Lightning Platform REST API",

"description": "REST API provides you with programmatic access

to your data in Salesforce.

The flexibility and scalability of REST API

make it an excellent choice for integrating Salesforce into your

applications

and for performing complex operations on a large

scale. You can use REST API tools to create, manipulate,

and search data in Salesforce by sending HTTP

requests to endpoints in Salesforce.

Depending on where you send requests, you access

125

Generating an OpenAPI 3.0 Document for sObjects REST API

(Beta)

and operate on different pieces of information, called resources.

Resources include records, query results,

metadata, and more. ",

"version": "61.0

"servers": [

...

"security": [

...

"paths": {

"/sobjects": { ... },

"/sobjects/Contact": { ... },

"/sobjects/Lead": { ... },

"/sobjects/Lead/{id}": { ... },

"/sobjects/{sObject}/deleted": { ... },

"/sobjects/{sObject}/describe": { ... },

"/sobjects/{sObject}/{id}/{blobField}": { ... }

"components": {

...

}

If you select a resource that doesn’t match any of the supported resources, or you select a resource that

you don’t have permissions to access, the request doesn’t fail but the OpenAPI document won’t contain

that resource. Also, the resource’s path won’t be visible in the OpenAPI document.

After the OpenAPI document is generated, you can retrieve the OpenAPI document again by using the

same locator ID for 48 hours. After 48 hours, using that locator ID results in a 404 (Not Found) error.

Giving Feedback

To give us your feedback, log in to Trailhead and then join the OpenAPI Specs for Salesforce REST APIs

Trailblazer Community.

Your feedback is valuable and can help us find existing problems and inspire future change. We’re looking

for general impressions, improvement suggestions, bugs, and feedback about how well this OpenAPI

document aligns with your OpenAPI use cases.

126

Generating an OpenAPI 3.0 Document for sObjects REST API

(Beta)

CHAPTER 5 Reference

The following table lists supported REST resources in the API and provides a brief description for each.

In each case, the URI for the resource follows the base URI, https://MyDomainName.my.salesforce.com.

For example, to retrieve basic information about an Account object in version 61.0 use

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account.

For information about standard and custom objects that you access with sObject resources, see Object Reference for the Salesforce

Platform.

Some of these resources are only available if you have the corresponding package installed or have the corresponding feature enabled.

Note: Some parts of request URIs are case-sensitive, such as IDs. Other parts of URIs aren't case-sensitive, such as object and field

names. If your requests aren't successful, check that your URI has the right letter cases by comparing the URI to the reference and

examples in this guide.

URI and DescriptionResource Name

/services/data

Versions

Lists summary information about each Salesforce version currently available, including the version,

label, and a link to each version's root.

/services/data/vXX.X

Resources by Version

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

/services/data/vXX.X/actions/standard

Invocable Actions

/services/data/vXX.X/actions/custom

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 company’s needs.

/services/data/vXX.X/analytics

Analytics

(Accesses Reports and

Dashboards REST API)

Accesses Reports and Dashboards REST API resources. See the Salesforce Reports and Dashboards

REST API Developer Guide.

/services/data/vXX.X/appMenu/

Get AppMenu Types

Accesses App Menu types in the Salesforce app dropdown menu.

/services/data/vXX.X/appMenu/AppSwitcher

AppMenu Items

Accesses App Menu items from the Salesforce app dropdown menu.

/services/data/vXX.X/appMenu/Salesforce1/

AppMenu Mobile Items

127

URI and DescriptionResource Name

Accesses App Menu items from the Salesforce mobile app for Android and iOS and the mobile web

navigation menu.

/services/data/vXX.X/asset-management

Asset Management

Makes make lifecycle-managed asset data available for sales and account reps to view in Lightning

Experience. See Customer Asset Lifecycle Management in the Connect REST API Developer Guide.

/services/data/vXX.X/async-queries

Async Queries

Submits a SOQL query to be processed asynchronously. See

•

Async Query in the Connect REST API Developer Guide.

•

Use Async SOQL with Real-Time Event Monitoring in the Salesforce Security Guide.

•

Async SOQL Use Cases in the Big Objects Implementation Guide.

/services/data/vXX.X/chatter

Chatter

(Connect REST API)

Accesses features in the Connect REST API. See the Connect REST API Developer Guide.

/services/data/vXX.X/commerce

Commerce

(Place Order REST API)

Accesses features in the Place Order REST API. See the Place Order REST API Developer Guide.

/services/data/vXX.X/compactLayouts?q=objectList

Compact Layouts

Returns a list of compact layouts for multiple objects.

/services/data/vXX.X/composite

Composite

Executes a series of REST API requests in a single POST request, or retrieves a list of other composite

resources with a GET request.

/services/data/vXX.X/composite/batch

Composite Batch

Executes up to 25 subrequests in a single request.

/services/data/vXX.X/composite/graph

Using Composite Graphs

Provides an enhanced way to perform composite requests.

/services/data/vXX.X/composite/tree

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.

/services/data/vXX.X/composite/sobjects

sObject Collections

Executes actions on multiple records in one request.

/services/data/vXX.X/connect

Connect REST API

Accesses features in the Connect REST API. See the Connect REST API Developer Guide.

128

Reference

URI and DescriptionResource Name

/services/data/vXX.X/connect/financialservices

Financial Services

Accesses Financial Services objects. See the Financial Services Cloud Developer Guide.

/services/data/vXX.X/connect/health/care-services

Health Cloud

Accesses Health Cloud objects. See the Health Cloud Developer Guide.

/services/data/vXX.X/connect/manufacturing

Manufacturing

Accesses Manufacturing Cloud objects. See the Manufacturing Cloud Developer Guide.

/services/data/vXX.X/connect/object-detection

Consumer Goods

/services/data/vXX.X/connect/visit/recommendations

Accesses the Consumer Goods Business API. See the Consumer Goods Cloud Developer Guide.

/services/data/vXX.X/consent

Consent

Tracks users’ consent preferences.

/services/data/vXX.X/contact-tracing

Contact Tracing

Tracks health contacts. See the Emergency Response Management for Public Health Developer

Guide.

/services/data/vXX.X/dedupe

Dedupe

Lists duplicate resources, job definitions, and jobs. See the Connect REST API Developer Guide.

/services/data/vXX.X/domino

Domino

For internal use only.

/services/data/vXX.X/eclair

Eclair

(geodata)

Accesses geodata definitions. See Charts Geodata Resource in the Analytics REST API Developer Guide.

/services/data/vXX.X/emailConnect

Email Connect

For internal use only.

/services/data/vXX.X/event/eventSchema/schemaId

Platform Event Schema by

Schema ID

Gets the definition of a platform event in JSON format for a schema ID. This resource is available in

REST API version 40.0 and later.

/services/data/vXX.X/folders

Folders

Use the Analytics Folders API to perform operations on report and dashboard folders. See Folders in

the Reports and Dashboards REST API Developer Guide.

129

Reference

URI and DescriptionResource Name

/services/data/vXX.X/jobs

Jobs

(Bulk API 2.0)

Accesses jobs in the Bulk API 2.0. See the Bulk API 2.0 and Bulk API Developer Guide.

/services/data/vXX.X/jsonxform

jsonxform

(Analytics REST API)

Tests the results of a rule in a Tableau template. See Rules Testing with jsonxform/transformation

endpoint the Analytics Templates Developer Guide.

/services/data/vXX.X/knowledgeManagement

Knowledge Management

Accesses Salesforce Knowledge features. See the Knowledge Developer Guide.

/services/data/vXX.X/licensing

Licensing

For internal use only.

/services/data/vXX.X/limits

Limits

Lists information about limits in your org. For each limit, this resource returns the maximum allocation

and the remaining allocation based on usage.

/services/data/vXX.X/limits/recordCount

Record Count

Lists information about object record counts in your organization.

/services/data/vXX.X/localizedvalue

Salesforce Surveys Translation

Resources

Use REST APIs to translate survey fields, view, update, or delete translated survey fields. The translated

values of surveys fields are stored in Flow fields.

/services/data/vXX.X/metadata

Metadata

Accesses features in the Metadata API. See the Metadata API Developer Guide.

/services/data/vXX.X/parameterizedSearch/?q=searchString

Parameterized Search

Executes a simple REST search using parameters instead of a SOSL clause. Indicate parameters in the

URI with the GET method. Or, use the POST method to create complex searches in a request body.

/services/data/vXX.X/payments

Payments

For internal use only.

/services/data/vXX.X/process/approvals

Process Approvals

Accesses 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.

/services/data/vXX.X/process/rules

Process Rules

130

Reference

URI and DescriptionResource Name

Accesses a list of all active workflow rules. Use the GET method to retrieve records or fields. Use the

HEAD method to retrieve information in HTTP headers. Use the POST method to trigger all active

workflow rules.

/services/data/vXX.X/query/?q=soql

Query

(SOQL)

Executes the specified SOQL query.

/services/data/vXX.X/queryAll/?q=soql

QueryAll

(SOQL)

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

/services/data/vXX.X/quickActions

Quick Actions

Returns a list of global quick actions and their types, as well as custom fields and objects that appear

in the Chatter feed.

/services/data/vXX.X/recent

SEE ALSO:

Conditional Request Headers

sObject Basic Information

Retrieves basic metadata for a specified object, or creates a new record for the specified object.

For example, this resource 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.

IN THIS SECTION:

Get Object Metadata Using sObject Basic Information

Gets basic metadata for a specified object, including some object properties, recent items, and URIs for other resources related to

the object.

Create Records Using sObject Basic Information

Creates a new record for a specified object based on field values in the request body.

Get Object Metadata Using sObject Basic Information

Gets basic metadata for a specified object, including some object properties, recent items, and URIs for other resources related to the

object.

To retrieve the complete metadata for an object, use the sObject Describe resource.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

The name of the object. For example, Account.

sObject

A required path parameter.

143

sObject Basic InformationReference

Example

For an example of retrieving metadata for an object, see Get Metadata for an Object on page 42.

SEE ALSO:

Object Reference for the Salesforce Platform

Create Records Using sObject Basic Information

Creates a new record for a specified object based on field values in the request body.

You must specify values for required fields in the request body. Specifying values for other fields is optional.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/

Formats

JSON, XML

HTTP Method

POST

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

An optional header, specifying the format for the request and response. Possible choices

are:

Content-Type

•

Content-Type: application/json

•

Content-Type: application/xml

The name of the object. For example, Account.

sObject

A required path parameter.

Example

•

For an example of creating a new record using POST, see Create a Record on page 45.

•

For an example of create a new record along with providing blob data for the record, see Insert or Update Blob Data on page 75.

SEE ALSO:

Object Reference for the Salesforce Platform

144

Create Records Using sObject Basic InformationReference

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.

For more information about the metadata that is retrieved, see DescribesObjectResult in the SOAP API Developers Guide.

You can use the If-Modified-Since or If-Unmodified-Since header with this resource. When using the

If-Modified-Since header, if no available object’s metadata has changed since the provided date, a 304 Not Modified

status code is returned with no response body.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/describe/

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

The name of the object. For example, Account.

sObject

A required path parameter.

An optional header specifying a date and time. The request returns records that have

been modified after that date and time.

If-Modified-Since

The format is EEE, dd MMM yyyy HH:mm:ss z. For example:

If-Modified-Since: Mon, 30 Nov 2020 08:34:54 MST.

An optional header specifying a date and time. The request returns records that have

not been modified after that date and time.

If-Unmodified-Since

The format is EEE, dd MMM yyyy HH:mm:ss z. For example:

If-Unmodified-Since: Mon, 30 Nov 2020 08:34:54 MST.

145

sObject DescribeReference

Example

See Get Field and Other Metadata for an Object. For an example that uses the If-Modified-Since HTTP header, see Get Object

Metadata Changes.

SEE ALSO:

Object Reference for the Salesforce Platform

Conditional Request Headers

sObject Get Deleted

Retrieves the list of individual records that have been deleted within the given timespan for the specified object. This resource is available

in REST 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 is 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 Guide for additional details on data replication and data replication limits.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/deleted/?start=startDateAndTime&end=endDateAndTime

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

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

start

specified dateTime value (for example, 12:30:15 is interpreted as 12:30:00 UTC). The

date and time must be formatted as described in Valid Date and DateTime Formats.

The date/time value for start must chronologically precede end. This parameter

should be URL-encoded.

146

sObject Get DeletedReference

DescriptionParameter

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

end

specified dateTime value (for example, 12:35:15 is interpreted as 12:35:00 UTC). The

date and time must be formatted as described in Valid Date and DateTime Formats.

This parameter should be URL-encoded

Response Body

DescriptionTypeProperty

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

arraydeletedRecords

was deleted in ISO 8601 format, using Coordinated Universal Time (UTC)

timezone.

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

timezone) of the last physically deleted object.

StringearliestDateAvailable

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

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

StringlatestDateCovered

Example

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

SEE ALSO:

Object Reference for the Salesforce Platform

sObject Get Updated

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

This resource is available in REST API version 31.0 and later.

This resource is commonly used in data replication applications. Note these 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 are found, EXCEEDED_ID_LIMIT is returned.

You can correct the error by choosing start and end dates that are closer together.

•

The call uses the SystemModstamp field to determine an object's add or change date. If SystemModstamp isn’t available,

the call uses LastModifiedDate.

See “Data Replication” in the SOAP API Developer Guide for additional details on data replication and data replication limits.

147

sObject Get UpdatedReference

Syntax

URI

/services/data/vXX.X/sobjects/sObject/updated/?start=startDateAndTime&end=endDateAndTime

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

Starting date/time (Coordinated Universal Time (UTC) time zone—not local— timezone)

of the timespan for which to retrieve the data. The API ignores the seconds portion of

start

the specified dateTime value (for example, 12:30:15 is interpreted as 12:30:00 UTC).

The date and time must be formatted as described in Valid Date and DateTime Formats.

The date/time value for start must chronologically precede end. This parameter

must be URL-encoded

Ending date/time (Coordinated Universal Time (UTC) time zone—not local— timezone)

of the timespan for which to retrieve the data. The API ignores the seconds portion of

end

the specified dateTime value (for example, 12:35:15 is interpreted as 12:35:00 UTC).

The date and time must be formatted as described in Valid Date and DateTime Formats.

This parameter must be URL-encoded

Response format

DescriptionTypeProperty

Array of updated records that satisfy the start and end dates specified in the

request. Each entry contains the record ID.

arrayids

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

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

StringlatestDateCovered

Examples

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

SEE ALSO:

Object Reference for the Salesforce Platform

148

sObject Get UpdatedReference

sObject Named Layouts

Retrieves information about alternate named layouts for a given object. This resource is available in REST API version 31.0 and later.

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.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/describe/namedLayouts/layoutName

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Request body

None

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/User/describe/namedLayouts/UserAlt

-H "Authorization: Bearer token"

SEE ALSO:

Object Reference for the Salesforce Platform

sObject Rows

Accesses records based on a specified object and record ID. Retrieves, updates, or deletes records based on the HTTP method. Use the

GET method to retrieve records or specific field values, the DELETE method to delete records, or the PATCH method to update records.

To create new records, use the sObject Basic Information or sObject Rows by External ID resources.

IN THIS SECTION:

Get Records Using sObject Rows

Gets a record based on the specified object and record ID. The fields and field values of the record are returned in the response body.

This resource can be used with external objects in API version 32.0 and later.

149

sObject Named LayoutsReference

Update Records Using sObject Rows

Updates a record based on the specified object and record ID. Field values provided in the request body replace the existing values

in the record. This resource can be used with external objects in API version 32.0 and later.

Delete Records Using sObject Rows

Deletes records based on the specified object and record ID. This resource can be used with external objects in API version 32.0 and

later.

Get Records Using sObject Rows

Gets a record based on the specified object and record ID. The fields and field values of the record are returned in the response body.

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.

For information about the items in the response body, see DescribeSObjectResult in the SOAP API Developer’s Guide.

If the object is an Account object, the response also contains an ETag header. For example: ETag:

"ddpAdaTHz+GcV35e7NLJ9iKD3XXVqAzXT1Sl2ykkP7g=--gzip" This ETag can be used with the If-Match and

If-None-Match headers. For more information, see Conditional Request Headers.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/id/

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

The name of the object. For example, Account.

sObject

The identifier of the object. For example, 001R0000005hDFYIA2.

A comma-delimited list of fields specifying the fields and values returned in the response

body. For example,

?fields=name,description,numberofemployees,industry.

fields

150

Get Records Using sObject RowsReference

DescriptionParameter

An optional header specifying a comma-delimited list of one or more ETags. This only

has an effect when used with Account objects. The request is only processed if the

Account’s ETag matches one of the ETags in the list.

For example: If-Match:

"94C83JSreaVMGpL+lUzv8Dr3inI0kCvuKATVJcTuApA=--gzip",

"ddpAdaTHz+GcV35e7NLJ9iKD3XXVqAzXT1Sl2ykkP7g=--gzip".

If-Match

An optional header specifying a comma-delimited list of one or more ETags. This only

has an effect when used with Account objects. The request is only processed if the

Account’s ETag does not match one of the ETags in the list.

For example: If-None-Match:

"94C83JSreaVMGpL+lUzv8Dr3inI0kCvuKATVJcTuApA=--gzip",

"ddpAdaTHz+GcV35e7NLJ9iKD3XXVqAzXT1Sl2ykkP7g=--gzip".

If-None-Match

An optional header specifying a date and time. The request returns records that have

been modified after that date and time.

If-Modified-Since

The format is EEE, dd MMM yyyy HH:mm:ss z

For example: If-Modified-Since: Mon, 30 Nov 2020 08:34:54

MST.

An optional header specifying a date and time. The request returns records that have

not been modified after that date and time.

If-Unmodified-Since

The format is EEE, dd MMM yyyy HH:mm:ss z

For example: If-Unmodified-Since: Mon, 30 Nov 2020 08:34:54

MST.

Example

For examples of retrieving records, see Get Field Values from a Standard Object Record.

SEE ALSO:

Object Reference for the Salesforce Platform

Update Records Using sObject Rows

Updates a record based on the specified object and record ID. Field values provided in the request body replace the existing values in

the record. 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.

For information about the items in the response body, see DescribeSObjectResult in the SOAP API Developer Guide.

151

Update Records Using sObject RowsReference

If the object is an Account object, the response also contains an ETag header. For example: ETag:

"ddpAdaTHz+GcV35e7NLJ9iKD3XXVqAzXT1Sl2ykkP7g=--gzip" This ETag can be used with the If-Match and

If-None-Match headers. For more information, see Conditional Request Headers.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/id/

Formats

JSON, XML

HTTP Method

PATCH

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

An optional header that specifies the format for the request and response. The possible

header values are:

Content-Type

•

Content-Type: application/json

•

Content-Type: application/xml

The name of the object. For example, Account and CustomObject__c.

sObject

The identifier of the object. For example, 001R0000005hDFYIA2.

An optional header specifying a comma-delimited list of one or more ETags. This only

has an effect when used with Account objects. The request is only processed if the

Account’s ETag matches one of the ETags in the list.

For example: If-Match:

"94C83JSreaVMGpL+lUzv8Dr3inI0kCvuKATVJcTuApA=--gzip",

"ddpAdaTHz+GcV35e7NLJ9iKD3XXVqAzXT1Sl2ykkP7g=--gzip".

If-Match

An optional header specifying a comma-delimited list of one or more ETags. This only

has an effect when used with Account objects. The request is only processed if the

Account’s ETag does not match one of the ETags in the list.

For example: If-None-Match:

"94C83JSreaVMGpL+lUzv8Dr3inI0kCvuKATVJcTuApA=--gzip",

"ddpAdaTHz+GcV35e7NLJ9iKD3XXVqAzXT1Sl2ykkP7g=--gzip".

If-None-Match

An optional header specifying a date and time. The request returns records that have

been modified after that date and time.

If-Modified-Since

The format is EEE, dd MMM yyyy HH:mm:ss z

152

Update Records Using sObject RowsReference

DescriptionParameter

For example: If-Modified-Since: Mon, 30 Nov 2020 08:34:54

MST.

An optional header specifying a date and time. The request returns records that have

not been modified after that date and time.

If-Unmodified-Since

The format is EEE, dd MMM yyyy HH:mm:ss z

For example: If-Unmodified-Since: Mon, 30 Nov 2020 08:34:54

MST.

Example

For an example of updating a record using PATCH, see Update a Record.

SEE ALSO:

Object Reference for the Salesforce Platform

Conditional Request Headers

Delete Records Using sObject Rows

Deletes records based on the specified object and record ID. 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.

If the object is an Account object, the response also contains an ETag header. For example: ETag:

"ddpAdaTHz+GcV35e7NLJ9iKD3XXVqAzXT1Sl2ykkP7g=--gzip" This ETag can be used with the If-Match and

If-None-Match headers. For more information, see Conditional Request Headers.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/id/

Formats

JSON, XML

HTTP Method

DELETE

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

The name of the object. For example, Account.

sObject

153

Delete Records Using sObject RowsReference

DescriptionParameter

The identifier of the record. For example, 001R0000005hDFYIA2.

An optional header specifying a comma-delimited list of one or more ETags. This only

has an effect when used with Account objects. The request is only processed if the

Account’s ETag matches one of the ETags in the list.

For example: If-Match:

"94C83JSreaVMGpL+lUzv8Dr3inI0kCvuKATVJcTuApA=--gzip",

"ddpAdaTHz+GcV35e7NLJ9iKD3XXVqAzXT1Sl2ykkP7g=--gzip".

If-Match

An optional header specifying a comma-delimited list of one or more ETags. This only

has an effect when used with Account objects. The request is only processed if the

Account’s ETag does not match one of the ETags in the list.

For example: If-None-Match:

"94C83JSreaVMGpL+lUzv8Dr3inI0kCvuKATVJcTuApA=--gzip",

"ddpAdaTHz+GcV35e7NLJ9iKD3XXVqAzXT1Sl2ykkP7g=--gzip".

If-None-Match

An optional header specifying a date and time. The request returns records that have

been modified after that date and time.

If-Modified-Since

The format is EEE, dd MMM yyyy HH:mm:ss z

For example: If-Modified-Since: Mon, 30 Nov 2020 08:34:54

MST.

An optional header specifying a date and time. The request returns records that have

not been modified after that date and time.

If-Unmodified-Since

The format is EEE, dd MMM yyyy HH:mm:ss z

For example: If-Unmodified-Since: Mon, 30 Nov 2020 08:34:54

MST.

Example

For an example of deleting a record using DELETE, see Delete a Record.

SEE ALSO:

Object Reference for the Salesforce Platform

sObject Rows by External ID

Creates, retrieves, upserts, or deletes records based on the value of a specified external ID field. By using the PATCH method with this

resource, you can send upsert requests to Salesforce.

154

sObject Rows by External IDReference

IN THIS SECTION:

Get Records Using sObject Rows by External ID

Retrieves a record based on the value of the specified external ID field.

Create Records Using sObject Rows by External ID

Creates a new record based on the field values included in the request body. This resource does not require the use of an external

ID field.

Upsert Records Using sObject Rows by External ID

Upserts a record based on the value of the specified external ID field. Based on whether the value of the external ID exists, the request

either creates a record or updates an existing one.

Delete Records Using sObject Rows by External ID

Deletes a record based on the value of the specified external ID field.

Return Headers Using sObject Rows by External ID

Returns only the headers that are returned by sending a GET request to the sObject Rows by External ID resource. This gives you a

chance to see returned header values of the GET request before retrieving the content itself.

Get Records Using sObject Rows by External ID

Retrieves a record based on the value of the specified external ID field.

Note: For security reasons, some Top Level Domains (TLD) can conflict with certain file format extensions. Adjust your

implementation to work around such cases.

For example, using an email address, such as [email protected], as the External ID returns a “404 not found” error.

There are several workarounds to handle conflicting TLDs.

•

Use a different External ID field.

•

Create a new External ID field that is the same as the email field and replace the "." with an "_" to handle this case.

•

Run a query for emails ending in ".inc" to retrieve the record ID and use that for the upsert request.

•

Use SOAP API instead of REST API for upsert requests.

•

Accept the email as a query parameter instead of a path parameter by creating a custom Apex REST API. Use Apex to perform

the upsert request.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/fieldName/fieldValue

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

None

155

Get Records Using sObject Rows by External IDReference

Example

For an example of retrieving a record based on an external ID, see Get a Record Using an External ID on page 49.

SEE ALSO:

Object Reference for the Salesforce Platform

Create Records Using sObject Rows by External ID

Creates a new record based on the field values included in the request body. This resource does not require the use of an external ID

field.

As a special case, in API version 37.0 and later, you can create a record with a POST request to

/services/data/vXX.X/sobjects/sObjectName/Id. Because Id has a null value, it is omitted from the request,

and the record is created according to the request body. Creating records with this resource is useful because you can use the same URI

in each POST request for each new record. In this case, you are not required to specify an external ID to create a record.

Note: Do not specify Id or an external ID field in the request body or an error is generated.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/Id

Formats

JSON, XML

HTTP Method

POST

Authentication

Authorization: Bearer token

Parameters

None

Example

Example Request

curl -X POST

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/Id -H

"Authorization: Bearer token" -H "Content-Type: application/json" -d "@newaccount.json"

SEE ALSO:

Object Reference for the Salesforce Platform

Upsert Records Using sObject Rows by External ID

Upserts a record based on the value of the specified external ID field. Based on whether the value of the external ID exists, the request

either creates a record or updates an existing one.

156

Create Records Using sObject Rows by External IDReference

•

If the external ID doesn't match an existing record, then a new record is created according to the request body. To prevent a new

record from being created, use the updateOnly parameter.

•

If the external ID matches one existing record, then the existing record is updated according to the request body.

•

If the external ID matches multiple existing records, then a 300 error is returned, and no records are created or updated.

If you’re upserting a record for an object that has a custom field with both the External ID and Unique attributes selected (a

unique index), you don’t need any special permissions. The Unique attribute prevents the creation of duplicates. If you’re upserting

a record for an object that has the External ID attribute selected but not the Unique attribute selected (a non-unique index),

your client application must have the permission “View All Data” to execute this call.

Note: For security reasons, some Top Level Domains (TLD) can conflict with certain file format extensions. Adjust your

implementation to work around such cases.

For example, using an email address, such as [email protected], as the External ID returns a “404 not found” error.

There are several workarounds to handle conflicting TLDs.

•

Use a different External ID field.

•

Create a new External ID field that is the same as the email field and replace the "." with an "_" to handle this case.

•

Run a query for emails ending in ".inc" to retrieve the record ID and use that for the upsert request.

•

Use SOAP API instead of REST API for upsert requests.

•

Accept the email as a query parameter instead of a path parameter by creating a custom Apex REST API. Use Apex to perform

the upsert request.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/fieldName/fieldValue

Formats

JSON, XML

HTTP Method

PATCH

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

An optional parameter that prevents a new record from being created. Forces the

upsert to behave like an update when updateOnly=true is used.

updateOnly

157

Upsert Records Using sObject Rows by External IDReference

Example

For examples of creating and updating records based on external IDs, see Insert or Update (Upsert) a Record Using an External ID on

page 50.

SEE ALSO:

Object Reference for the Salesforce Platform

Delete Records Using sObject Rows by External ID

Deletes a record based on the value of the specified external ID field.

Note: For security reasons, some Top Level Domains (TLD) can conflict with certain file format extensions. Adjust your

implementation to work around such cases.

For example, using an email address, such as [email protected], as the External ID returns a “404 not found” error.

There are several workarounds to handle conflicting TLDs.

•

Use a different External ID field.

•

Create a new External ID field that is the same as the email field and replace the "." with an "_" to handle this case.

•

Run a query for emails ending in ".inc" to retrieve the record ID and use that for the upsert request.

•

Use SOAP API instead of REST API for upsert requests.

•

Accept the email as a query parameter instead of a path parameter by creating a custom Apex REST API. Use Apex to perform

the upsert request.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/fieldName/fieldValue

Formats

JSON, XML

HTTP Method

DELETE

Authentication

Authorization: Bearer token

Parameters

None

SEE ALSO:

Object Reference for the Salesforce Platform

Return Headers Using sObject Rows by External ID

Returns only the headers that are returned by sending a GET request to the sObject Rows by External ID resource. This gives you a chance

to see returned header values of the GET request before retrieving the content itself.

158

Delete Records Using sObject Rows by External IDReference

Note: For security reasons, some Top Level Domains (TLD) can conflict with certain file format extensions. Adjust your

implementation to work around such cases.

For example, using an email address, such as [email protected], as the External ID returns a “404 not found” error.

There are several workarounds to handle conflicting TLDs.

•

Use a different External ID field.

•

Create a new External ID field that is the same as the email field and replace the "." with an "_" to handle this case.

•

Run a query for emails ending in ".inc" to retrieve the record ID and use that for the upsert request.

•

Use SOAP API instead of REST API for upsert requests.

•

Accept the email as a query parameter instead of a path parameter by creating a custom Apex REST API. Use Apex to perform

the upsert request.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/fieldName/fieldValue

Formats

JSON, XML

HTTP Method

HEAD

Authentication

Authorization: Bearer token

Parameters

None

SEE ALSO:

Object Reference for the Salesforce Platform

sObject Blob Get

Gets the specified blob field from an individual record and returns it as binary data. Only certain standard objects have blob fields, such

as Attachment, ContentNote, ContentVersion, Document, Folder, and Note.

Note: The sObject Blob Get resource isn’t compatible with Composite API requests, because it returns binary data instead of data

in JSON or XML formats. Instead, make individual sObject Blob Get requests to retrieve blob data.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/id/blobField

Formats

Binary data

HTTP Method

GET

159

sObject Blob GetReference

Authentication

Authorization: Bearer token

Parameters

none required

Example

For an example of retrieving blob data from a Document, see Get Blob Data on page 81.

SEE ALSO:

Object Reference for the Salesforce Platform

sObject ApprovalLayouts

Retrieve a list of approval layouts for a specified object. This resource is available in REST API version 30.0 and later.

IN THIS SECTION:

Get Approval Layouts

Gets a list of approval layouts for a specified object. This resource is available in REST API version 30.0 and later.

Return Headers for Approval Layouts

Returns only the headers that are returned by a GET request to sObject ApprovalLayouts resources. This gives you a chance to see

header values before retrieving the content of the resource. This resource is available in REST API version 30.0 and later.

SEE ALSO:

Object Reference for the Salesforce Platform

Get Approval Layouts

Gets a list of approval layouts for a specified object. This resource is available in REST API version 30.0 and later.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/describe/approvalLayouts/

Formats

JSON, XML

HTTP methods

GET

Authentication

Authorization: Bearer token

Request parameters

None required

160

sObject ApprovalLayoutsReference

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/describe/approvalLayouts/

-H "Authorization: Bearer token"

Example Response Body

{

"approvalLayouts" : [ {

"id" : "04aD00000008Py9IAE",

"label" : "MyApprovalProcessName",

"layoutItems" : [...],

"name" : "MyApprovalProcessName"

}, {

"id" : "04aD00000008Q0KIAU",

"label" : "Process1",

"layoutItems" : [...],

"name" : "Process1"

} ]

}

If you haven’t defined any approval layouts for an object, the response is {"approvalLayouts" : [ ]}.

Return Headers for Approval Layouts

Returns only the headers that are returned by a GET request to sObject ApprovalLayouts resources. This gives you a chance to see header

values before retrieving the content of the resource. This resource is available in REST API version 30.0 and later.

Syntax

URI

To return headers of a request for an approval layout description for a specified object, use

/services/data/vXX.X/sobjects/sObject/describe/approvalLayouts/

Formats

JSON, XML

HTTP methods

HEAD

Authentication

Authorization: Bearer token

Request parameters

None required

161

Return Headers for Approval LayoutsReference

Example

Example Request

curl -X HEAD --head

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/describe/approvalLayouts/

-H "Authorization: Bearer token"

sObject Single Approval Process

Retrieves an approval layout for a named approval process on a specified object. This resource is available in REST API version 30.0 and

later.

Get a Layout for a Single Approval Process on a Specified Object

Retrieves an approval layout for a named approval process on a specified object. This resource is available in REST API version 30.0 and

later.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/describe/approvalLayouts/approvalProcessName

Formats

JSON, XML

HTTP methods

GET

Authentication

Authorization: Bearer token

Request parameters

None required

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/describe/approvalLayouts/ExampleApprovalProcessName

-H "Authorization: Bearer token"

Example Response Body

{

"approvalLayouts" : [ {

"id" : "04aD00000008Py9IAE",

"label" : "ExampleApprovalProcessName",

"layoutItems" : [...],

"name" : "ExampleApprovalProcessName"

} ]

}

162

sObject Single Approval ProcessReference

Return Headers for a Single Approval Process on a Specified Object

Returns only the headers that are returned by a GET request to sObject ApprovalLayouts resources. This gives you a chance to see header

values before retrieving the content of the resource. Specify a particular approval process name to limit the request to one specific

approval layout. This resource is available in REST API version 30.0 and later.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/describe/approvalLayouts/approvalProcessName

Formats

JSON, XML

HTTP methods

HEAD

Authentication

Authorization: Bearer token

Request parameters

None required

Example

Example Request

curl -X HEAD --head

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/describe/approvalLayouts/ExampleApprovalProcessName

-H "Authorization: Bearer token"

sObject CompactLayouts

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

IN THIS SECTION:

Get Compact Layouts Using sObject CompactLayouts

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

Return Headers Using sObject CompactLayouts

Returns only the headers that are returned by a GET request to the sObject CompactLayouts resource. This gives you a chance to

see header values ahead of time before retrieving the content of the resource. This resource is available in REST API version 29.0 and

later.

SEE ALSO:

Object Reference for the Salesforce Platform

Get Compact Layouts Using sObject CompactLayouts

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

163

Return Headers for a Single Approval Process on a Specified

Object

Reference

Syntax

URI

/services/data/vXX.X/sobjects/sObject/describe/compactLayouts/

Formats

JSON, XML

HTTP methods

GET

Authentication

Authorization: Bearer token

Request parameters

None required

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/describe/compactLayouts

-H "Authorization: Bearer token"

Example 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,

164

Get Compact Layouts Using sObject CompactLayoutsReference

"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,

"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,

165

Get Compact Layouts Using sObject CompactLayoutsReference

"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,

"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,

166

Get Compact Layouts Using sObject CompactLayoutsReference

"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" : [ {

"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,

167

Get Compact Layouts Using sObject CompactLayoutsReference

"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",

"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/v61.0/sobjects/Account/describe/compactLayouts/012000000000000AAA"

}

} ],

"urls" : {

"primary" : "/services/data/v61.0/sobjects/Account/describe/compactLayouts/primary"

}

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

168

Get Compact Layouts Using sObject CompactLayoutsReference

Return Headers Using sObject CompactLayouts

Returns only the headers that are returned by a GET request to the sObject CompactLayouts resource. This gives you a chance to see

header values ahead of time before retrieving the content of the resource. This resource is available in REST API version 29.0 and later.

Syntax

URI

For a compact layout description for a specific object, use

/services/data/vXX.X/sobjects/sObject/describe/compactLayouts/

Formats

JSON, XML

HTTP methods

HEAD

Authentication

Authorization: Bearer token

Request parameters

None required

Example

Example Request

curl -X HEAD --head

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/describe/compactLayouts

-H "Authorization: Bearer token"

sObject Layouts

Retrieves lists of page layouts and their descriptions. You can request information for all of a specific object’s layouts or for layouts

associated with a specified record type on a specific object.

IN THIS SECTION:

Get Layouts and Descriptions for a Specified Object

Retrieves lists of layouts and their descriptions for a single object.

Return Layout Headers for a Specified Object

Returns only the headers that are returned by a GET request to sObject Layouts resources. This gives you a chance to see header

values ahead of time before retrieving the content of the resource.

SEE ALSO:

Object Reference for the Salesforce Platform

Get Layouts and Descriptions for a Specified Object

Retrieves lists of layouts and their descriptions for a single object.

169

Return Headers Using sObject CompactLayoutsReference

Syntax

URI

/services/data/vXX.X/sobjects/sObject/describe/layouts/

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Battle_Station__c/describe/layouts/

-H "Authorization: Bearer token"

Example Response Body

{

"layouts" : [ {

"buttonLayoutSection" : {

"detailButtons" : [

...

]

"detailLayoutSections" : [

...

"editLayoutSections" : [

...

"feedView" : null,

"highlightsPanelLayoutSection" : null,

"id" : "00ho000000BKMebAAH",

"multirowEditLayoutSections" : [ ],

"offlineLinks" : [ ],

"quickActionList" : {

"quickActionListItems" : [

...

]

"relatedContent" : null,

"relatedLists" : [

...

"saveOptions" : [ ]

} ],

170

Get Layouts and Descriptions for a Specified ObjectReference

"recordTypeMappings" : [

...

"recordTypeSelectorRequired" : [ false ]

}

Return Layout Headers for a Specified Object

Returns only the headers that are returned by a GET request to sObject Layouts resources. This gives you a chance to see header values

ahead of time before retrieving the content of the resource.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/describe/layouts/

Formats

JSON, XML

HTTP Method

HEAD

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl -X HEAD --head

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Battle_Station__c/describe/layouts/

-H "Authorization: Bearer token"

sObject Layouts for an Object With Multiple Record Types

Retrieves lists of page layouts and their descriptions for objects that have more than one record type defined.

Get Layouts and Descriptions for an Object With Multiple Record Types

Retrieves lists of layouts and their descriptions.

For a layout description for objects that have more than one record type defined, the recordTypeId can be obtained from the

result from /services/data/vXX.X/sobjects/sObject/describe/layouts/

A GET request for objects that have more than one record type defined returns null for the layouts section of the response.

171

Return Layout Headers for a Specified ObjectReference

Syntax

URI

/services/data/vXX.X/sobjects/sObject/describe/layouts/recordTypeId

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Chocolate__c/describe/layouts/0125c000000oIN9AAM

-H "Authorization: Bearer token"

Example Response Body

{

"buttonLayoutSection" : {

"detailButtons" : [

...

]

"detailLayoutSections" : [

...

"editLayoutSections" : [

...

"feedView" : null,

"highlightsPanelLayoutSection" : null,

"id" : "00ho000000CUJWIAA5",

"multirowEditLayoutSections" : [ ],

"offlineLinks" : [ ],

"quickActionList" : {

"quickActionListItems" : [

...

]

"relatedContent" : null,

"relatedLists" : [

...

"saveOptions" : [ ]

}

172

Get Layouts and Descriptions for an Object With Multiple

Record Types

Reference

Return Layout Headers for an Object With Multiple Record Types

Returns only the headers that are returned by a GET request to sObject Layouts resources. This gives you a chance to see header values

ahead of time before retrieving the content of the resource.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/describe/layouts/recordTypeId

Formats

JSON, XML

HTTP Method

HEAD

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl -X HEAD

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Chocolate__c/describe/layouts/0125c000000oIN9AAM

-H "Authorization: Bearer token"

sObject Global Publisher Layouts

Retrieves lists of global publisher layouts. Global publisher layouts customize the actions on global pages (like the Home page). In

Lightning Experience, these layouts populate the Global Actions menu.

IN THIS SECTION:

Get Global Publisher Layouts and Descriptions

Retrieves lists of global publisher layouts and their descriptions. Global publisher layouts customize the actions on global pages (like

the Home page). In Lightning Experience, these layouts populate the Global Actions menu.

Return Headers for All Global Publisher Layouts

Returns only the headers that are returned by a GET request to sObject Layouts resources. This gives you a chance to see header

values ahead of time before retrieving the content of the resource.

Get Global Publisher Layouts and Descriptions

Retrieves lists of global publisher layouts and their descriptions. Global publisher layouts customize the actions on global pages (like the

Home page). In Lightning Experience, these layouts populate the Global Actions menu.

173

Return Layout Headers for an Object With Multiple Record

Types

Reference

Syntax

URI

/services/data/vXX.X/sobjects/Global/describe/layouts/

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Global/describe/layouts/

-H "Authorization: Bearer token"

Example Response Body

{

"layouts": [

{

"buttonLayoutSection": null,

"detailLayoutSections": [],

"editLayoutSections": [],

"feedView": null,

"highlightsPanelLayoutSection": null,

"id": "00hRO000000Mo6jYAC",

"multirowEditLayoutSections": [],

"offlineLinks": [],

"quickActionList": {

"quickActionListItems": [

{

"accessLevelRequired": null,

"colors": [

{

"color": "65CAE4",

"context": "primary",

"theme": "theme4"

}

"iconUrl": null,

"icons": [

{

"contentType": "image/svg+xml",

"height": 0,

"theme": "theme4",

"url":

174

Get Global Publisher Layouts and DescriptionsReference

"https://rockyroads.test1.my.pc-rnd.salesforce.com/img/icon/t4v35/action/share_post.svg",

"width": 0

...

"label": "Post",

"miniIconUrl": "",

"quickActionName": "FeedItem.TextPost",

"targetSobjectType": null,

"type": "Post",

"urls": {}

...

]

"relatedContent": null,

"relatedLists": [],

"saveOptions": []

}

"recordTypeMappings": [],

"recordTypeSelectorRequired": [

false

]

}

Return Headers for All Global Publisher Layouts

Returns only the headers that are returned by a GET request to sObject Layouts resources. This gives you a chance to see header values

ahead of time before retrieving the content of the resource.

Syntax

URI

/services/data/vXX.X/sobjects/Global/describe/layouts/

Formats

JSON, XML

HTTP Method

HEAD

Authentication

Authorization: Bearer token

Parameters

None required

175

Return Headers for All Global Publisher LayoutsReference

Example

Example Request

curl -X HEAD

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Global/describe/layouts/

-H "Authorization: Bearer token"

sObject PlatformAction

Returns the description of the 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. This resource is available in API version 33.0 and later.

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

Syntax

URI

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

Formats

JSON, XML

HTTP methods

GET

Authentication

Authorization: Bearer token

Request body

None

SEE ALSO:

Object Reference for the Salesforce Platform

sObject Quick Actions

Access an object’s actions and the action details. This resource is available in REST API version 28.0 and later.

When working with actions, also refer to Quick Actions.

IN THIS SECTION:

Get sObject Quick Actions

Returns a specific object’s actions as well as global actions. This resource is available in REST API version 28.0 and later.

176

sObject PlatformActionReference

Return Headers Using sObject Quick Actions

Returns only the headers that are returned by sending a GET request to the sObject Quick Actions resource. This gives you a chance

to see the header values before retrieving the content of the resource. This resource is available in REST API version 28.0 and later.

SEE ALSO:

Object Reference for the Salesforce Platform

Get sObject Quick Actions

Returns a specific object’s actions as well as global actions. This resource is available in REST API version 28.0 and later.

This resource returns all actions—both global and standard—in addition to the ones requested.

When working with actions, also refer to Quick Actions.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/quickActions/

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/quickActions/

-H "Authorization: Bearer token"

Return Headers Using sObject Quick Actions

Returns only the headers that are returned by sending a GET request to the sObject Quick Actions resource. This gives you a chance to

see the header values before retrieving the content of the resource. This resource is available in REST API version 28.0 and later.

This resource returns all actions—both global and standard—in addition to the ones requested.

When working with actions, also refer to Quick Actions.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/quickActions/

177

Get sObject Quick ActionsReference

Formats

JSON, XML

HTTP Method

HEAD

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl -X HEAD --head

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/quickActions/

-H "Authorization: Bearer token"

sObject Specific Quick Actions

Access a specific action for an object. By using the POST method with this resource, you can create records using an object’s quick actions.

When working with actions, also refer to Quick Actions.

IN THIS SECTION:

Get Specific sObject Quick Actions

Gets a specific action for an object, as well as the action’s details. This resource is available in REST API version 28.0 and later.

Create Records Using Specific sObject Quick Actions

Creates a record via the specified quick action based on the field values included in the request body. This resource is available in

REST API version 28.0 and later.

Return Headers Using Specific sObject Quick Actions

Returns only the headers that are returned by sending a GET request to the sObject Quick Actions resource. This gives you a chance

to see the header values before retrieving the content of the resource. This resource is available in REST API version 28.0 and later.

Get Specific sObject Quick Actions

Gets a specific action for an object, as well as the action’s details. This resource is available in REST API version 28.0 and later.

When working with actions, also refer to Quick Actions.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/quickActions/actionName

Formats

JSON, XML

178

sObject Specific Quick ActionsReference

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/quickActions/CreateContact

-H "Authorization: Bearer token"

Create Records Using Specific sObject Quick Actions

Creates a record via the specified quick action based on the field values included in the request body. This resource is available in REST

API version 28.0 and later.

When working with actions, also refer to Quick Actions.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/quickActions/actionName

Formats

JSON, XML

HTTP Method

POST

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl -X POST

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/quickActions/CreateContact

-H 'Authorization: Bearer token -H "Content-Type: application/json" -d @newcontact.json'

Example Request Body

{

"contextId" : "001D000000JRSGf",

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

179

Create Records Using Specific sObject Quick ActionsReference

}

Return Headers Using Specific sObject Quick Actions

Returns only the headers that are returned by sending a GET request to the sObject Quick Actions resource. This gives you a chance to

see the header values before retrieving the content of the resource. This resource is available in REST API version 28.0 and later.

When working with actions, also refer to Quick Actions.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/quickActions/actionName

Formats

JSON, XML

HTTP Method

HEAD

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl -X HEAD --head

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/quickActions/CreateContact

-H "Authorization: Bearer token"

sObject Quick Action Details

Access the descriptive detail for a specific action on an object.

When working with actions, also refer to Quick Actions.

IN THIS SECTION:

Get sObject Quick Action Details

Returns a specific action’s descriptive detail. This resource is available in REST API version 28.0 and later.

Return Headers Using sObject Quick Action Details

Returns only the headers that are returned by sending a GET request to the sObject Quick Actions resource. This gives you a chance

to see the header values before retrieving the content of the resource. This resource is available in REST API version 28.0 and later.

180

Return Headers Using Specific sObject Quick ActionsReference

Get sObject Quick Action Details

Returns a specific action’s descriptive detail. This resource is available in REST API version 28.0 and later.

When working with actions, also refer to Quick Actions.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/quickActions/actionName/describe/

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/quickActions/CreateContact/describe/

-H "Authorization: Bearer token"

Return Headers Using sObject Quick Action Details

Returns only the headers that are returned by sending a GET request to the sObject Quick Actions resource. This gives you a chance to

see the header values before retrieving the content of the resource. This resource is available in REST API version 28.0 and later.

When working with actions, also refer to Quick Actions.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/quickActions/actionName/describe/

Formats

JSON, XML

HTTP Method

HEAD

Authentication

Authorization: Bearer token

Parameters

None required

181

Get sObject Quick Action DetailsReference

Example

Example Request

curl -X HEAD --head

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/quickActions/CreateContact/describe/

-H "Authorization: Bearer token"

sObject Quick Action Default Values

Retrieves the default values, including default field values, for a specific action on an object.

When working with actions, also refer to Quick Actions.

IN THIS SECTION:

Get sObject Quick Action Default Values

Returns a specific action’s default values, including field values. This resource is available in REST API version 28.0 and later.

Return Headers Using sObject Quick Action Default Values

Returns only the headers that are returned by sending a GET request to the sObject Quick Actions resource. This gives you a chance

to see the header values before retrieving the content of the resource. This resource is available in REST API version 28.0 and later.

Get sObject Quick Action Default Values

Returns a specific action’s default values, including field values. This resource is available in REST API version 28.0 and later.

When working with actions, also refer to Quick Actions.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/quickActions/actionName/defaultValues/

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/quickActions/CreateContact/defaultValues/

-H "Authorization: Bearer token"

182

sObject Quick Action Default ValuesReference

Return Headers Using sObject Quick Action Default Values

Returns only the headers that are returned by sending a GET request to the sObject Quick Actions resource. This gives you a chance to

see the header values before retrieving the content of the resource. This resource is available in REST API version 28.0 and later.

When working with actions, also refer to Quick Actions.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/quickActions/actionName/defaultValues/

Formats

JSON, XML

HTTP Method

HEAD

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl -X HEAD --head

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/quickActions/CreateContact/defaultValues/

-H "Authorization: Bearer token"

sObject Quick Action Default Values by ID

Evaluates the default values for a specific action on an object. Responses include default field values.

When working with actions, also refer to Quick Actions.

IN THIS SECTION:

Get sObject Quick Action Default Values by ID

Returns the default values for an action specific to the context_id object. This resource is available in REST API version 29.0 and

later.

Return Headers Using sObject Quick Action Default Values by ID

Returns only the headers that are returned by sending a GET request to the sObject Quick Actions resource. This gives you a chance

to see the header values before retrieving the content of the resource. This resource is available in REST API version 29.0 and later.

Get sObject Quick Action Default Values by ID

Returns the default values for an action specific to the context_id object. This resource is available in REST API version 29.0 and

later.

183

Return Headers Using sObject Quick Action Default ValuesReference

In API version 28.0, to evaluate the default values for an action, use

/services/data/vXX.X/sobjects/sObject/quickActions/action_name/defaultValues/parent_id.

When working with actions, also refer to Quick Actions.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/quickActions/actionName/defaultValues/contextId

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

None required

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/quickActions/CreateContact/defaultValues/001D000000JRWBd

-H "Authorization: Bearer token"

Return Headers Using sObject Quick Action Default Values by ID

Returns only the headers that are returned by sending a GET request to the sObject Quick Actions resource. This gives you a chance to

see the header values before retrieving the content of the resource. This resource is available in REST API version 29.0 and later.

In API version 28.0, to evaluate the default values for an action, use

/services/data/vXX.X/sobjects/sObject/quickActions/action_name/defaultValues/parent_id.

When working with actions, also refer to Quick Actions.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/quickActions/actionName/defaultValues/contextId

Formats

JSON, XML

HTTP Method

HEAD

Authentication

Authorization: Bearer token

Parameters

None required

184

Return Headers Using sObject Quick Action Default Values

by ID

Reference

Example

Example Request

curl -X HEAD --head

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/quickActions/CreateContact/defaultValues/001D000000JRWBd

-H "Authorization: Bearer token"

sObject Rich Text Image Get

Gets the specified image data from a specific rich text area field in a given record. To get an image, you must have a record with an image

uploaded to a rich text area field.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/id/richTextImageFields/fieldName/contentReferenceId

Formats

Binary data

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

Indicates the name of the standard object of the record.sObjectName

The ID of the object.id

The name of the rich text area field.fieldName

The reference ID that uniquely identifies an image within a rich text area field.

You can obtain the reference by retrieving information for the object. The description

shows the contents of the rich text area field. For example:

{

"attributes" : {

contentReferenceId

"type" : "Lead",

"url" :

"/services/data/v61.0/sobjects/Lead/00QRM000003ZfDb2AK"

"Id" : "00QRM000003ZfDb2AK",

...

"ContactPhoto__c" :

"Sarah Loehr and her two dogs.

<img alt=\"Sarah Loehr.\"

src=\"https://MyDomainName.file.force.com/servlet/rtaImage?

185

sObject Rich Text Image GetReference

DescriptionParameter

eid=00QRM000003ZfDb&

feoid=00NRM000001E73j&

refid=0EMRM00000002Ip\"></img>"

}

The refid parameter of the image (0EMRM00000002Ip in this example) is the

contentReferenceId.

Example

For an example of retrieving the blob data from a rich text area field, see Get an Image from a Rich Text Area Field on page 74.

SEE ALSO:

Object Reference for the Salesforce Platform

sObject Relationships

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. This resource

is available in REST API version 36.0 and later.

IN THIS SECTION:

Get Records Using sObject Relationships

Gets a record based on the specified object, record ID, and relationship field. The fields and field values of the record are returned

in the response body. If there are multiple related records, you can retrieve the complete set of associated records.

Update Records Using sObject Relationships

Updates a parent record based on the specified object, record ID, and relationship field name. Field values provided in the request

body replace the existing values in the record. Only a child-to-parent relationship can be traversed when you update records.

Delete Records Using sObject Relationships

Deletes a parent record based on the specified object, record ID, and relationship field name. Only a child-to-parent relationship can

be traversed when you delete records.

Get Records Using sObject Relationships

Gets a record based on the specified object, record ID, and relationship field. The fields and field values of the record are returned in the

response body. If there are multiple related records, you can retrieve the complete set of associated records.

If there’s no record associated with a relationship field, a 404 error response is returned. If the relationship field normally resolves to

multiple records and no relationship set exists, a 200 response is returned. If the fields parameter is used with fields that don’t exist

or aren’t visible to the consumer by field-level security, a 400 error response is returned. For other error messages, see Status Codes and

Error Responses.

186

sObject RelationshipsReference

Syntax

URI

/services/data/vXX.X/sobjects/sObject/id/relationshipFieldName

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

The name of the object. For example, Account.

sObject

The identifier of the record. For example, 001R0000005hDFYIA2.

The name of the field that contains the relationship. For example, Opportunities.

relationshipFieldName

Optional for GET. A comma-delimited list of fields in the associated relationship record

returned in the response body. For example:

/services/data/v61.0/sobjects/sObject/id/relationship

field?fields=field1,field2

fields

Example

For examples of using sObject Relationships to access relationship fields, see Traverse Relationships with Friendly URLs.

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Merchandise__c/a01D000000INjVe/Distributor__r

-H “Authorization: Bearer token”

Example Response Body

The response body is the contents of the record associated with the relationship field. Here’s an example of a request and JSON

response body for a simple relationship traversal that returns the Distributor__c record associated with a relationship field on custom

object Merchandise__c.

{

"attributes" :

{

"type" : "Distributor__c",

"url" : "/services/data/v61.0/sobjects/Distributor__c/a03D0000003DUhcIAG"

"Id" : "a03D0000003DUhcIAG",

"OwnerId" : "005D0000001KyEIIA0",

187

Get Records Using sObject RelationshipsReference

"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"

}

SEE ALSO:

Object Reference for the Salesforce Platform

Update Records Using sObject Relationships

Updates a parent record based on the specified object, record ID, and relationship field name. Field values provided in the request body

replace the existing values in the record. Only a child-to-parent relationship can be traversed when you update records.

If the fields parameter is used with fields that don’t exist or aren’t visible to the consumer by field-level security, a 400 error response

is returned. For other error messages, see Status Codes and Error Responses.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/id/relationshipFieldName

Formats

JSON, XML

HTTP Method

PATCH

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

The name of the object. For example, Contact.

sObject

The identifier of the record. For example, 003R0000005hDFYIA2, the contact ID.

The name of the field that contains the relationship. For example, Account. Account

is the name of the relationship on the child Contact object.

relationshipFieldName

Example

For an example of updating a record using PATCH, see

188

Update Records Using sObject RelationshipsReference

Update a Record.

SEE ALSO:

Object Reference for the Salesforce Platform

Delete Records Using sObject Relationships

Deletes a parent record based on the specified object, record ID, and relationship field name. Only a child-to-parent relationship can be

traversed when you delete records.

If the fields parameter is used with fields that don’t exist or aren’t visible to the consumer by field-level security, a 400 error response

is returned. For other error messages, see Status Codes and Error Responses.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/id/relationshipFieldName

Formats

JSON, XML

HTTP Method

DELETE

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

The name of the object. For example, Contact.

sObject

The identifier of the record. For example, 003R0000005hDFYIA2, the contact ID.

The name of the field that contains the relationship. For example, Account. Account

is the name of the relationship on the child Contact object.

relationshipFieldName

When you delete a parent record, it deletes all child records that have a master-detail relationship to the parent record.

Example

For examples of using sObject Relationships to delete a relationship record, see Traverse Relationships with Friendly URLs.

SEE ALSO:

Object Reference for the Salesforce Platform

189

Delete Records Using sObject RelationshipsReference

sObjects Suggested Articles

Returns results on suggested articles for a Case, Work Order, or Work Order Line. These suggestions are based on common keywords in

the title, description, and other information that’s entered before the record has been saved and assigned an ID. This resource is available

in REST API version 30.0 and later.

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. It’s intended to be used with other services that than use the IDs to get article

data for display.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/suggestedArticles

?language=articleLanguage&subject=subject&description=description.

Formats

JSON, XML

HTTP methods

GET

Authentication

Authorization: Bearer token

Request body

None required

Request parameters

DescriptionParameter

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.

articleTypes

Optional. The name of the data category group and the data category API name (not

category title) for desired articles. The syntax is

SEE ALSO:

Object Reference for the Salesforce Platform

Set User Password

Sets a user’s password based on the specified user ID. The password provided in the request body replaces the user’s existing password.

This resource is available in REST API version 24.0 and later.

You can only set one password per request. The new password must conform to the password policies for the organization, otherwise

an INVALID_NEW_PASSWORD error is returned.

If the session doesn’t have permission to access the user information, an INSUFFICIENT_ACCESS error is returned.

Syntax

URI

/services/data/vXX.X/sobjects/User/userId/password

Formats

JSON, XML

194

Get User Password Expiration StatusReference

HTTP Method

POST

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 83.

SEE ALSO:

Object Reference for the Salesforce Platform

Reset User Password

Initiates a password reset for a user based on the specified user ID. The user’s current password becomes invalid and the user receives

an email with a password reset link. To log in again, the user must finish resetting their password. This resource is available in REST API

version 24.0 and later.

Salesforce auto-generates a temporary password for the user and returns it in the response body. If the user can’t access the email link,

they can finish resetting their password by logging in with the temporary password.

If the session doesn’t have permission to access the user information, an INSUFFICIENT_ACCESS error is returned.

Syntax

URI

/services/data/vXX.X/sobjects/User/userId/password

Formats

JSON, XML

HTTP Method

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 83.

SEE ALSO:

Object Reference for the Salesforce Platform

195

Reset User PasswordReference

Return Headers Using sObject User Password

Returns only the headers that are returned by sending a GET request to the sObject User Password resource. This operation allows you

to see returned header values of the GET request before retrieving the content itself. This resource is available in REST API version 24.0

and later.

If the session doesn’t have permission to access the user information, an INSUFFICIENT_ACCESS error is returned.

Syntax

URI

/services/data/vXX.X/sobjects/User/userId/password

Formats

JSON, XML

HTTP Method

HEAD

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 83.

SEE ALSO:

Object Reference for the Salesforce Platform

sObject Self-Service User Password

Accesses self-service user passwords based on the specified user ID. Sets, resets, or gets the expiration status of a self-service user password

based on the HTTP method. Use the GET method to retrieve a password’s expiration status, the POST method to set a password, or the

DELETE method to initiate a password reset.

IN THIS SECTION:

Get Self-Service User Password Expiration Status

Retrieves a self-service user’s password expiration status based on the specified user ID. A True or False value is returned in the

response body. This resource is available in REST API version 24.0 and later.

Set Self-Service User Password

Sets a self-service user’s password based on the specified user ID. The password provided in the request body replaces the user’s

existing password. This resource is available in REST API version 24.0 and later.

Reset Self-Service User Password

Initiates a password reset for a self-service user based on the specified user ID. The user’s current password becomes invalid and the

user receives an email with a password reset link. To log in again, the user must finish resetting their password. This resource is

available in REST API version 24.0 and later.

196

Return Headers Using sObject User PasswordReference

Return Headers Using sObject Self-Service User Password

Returns only the headers that are returned by sending a GET request to the sObject Self-Service User Password resource. This operation

allows you to see returned header values of the GET request before retrieving the content itself. This resource is available in REST

API version 24.0 and later.

Get Self-Service User Password Expiration Status

Retrieves a self-service user’s password expiration status based on the specified user ID. A True or False value is returned in the response

body. This resource is available in REST API version 24.0 and later.

If the session doesn’t have permission to access the user information, an INSUFFICIENT_ACCESS error is returned.

Syntax

URI

/services/data/vXX.X/sobjects/SelfServiceUser/selfServiceUserId/password

Formats

JSON, XML

HTTP Method

GET

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 83.

SEE ALSO:

Object Reference for the Salesforce Platform

Set Self-Service User Password

Sets a self-service user’s password based on the specified user ID. The password provided in the request body replaces the user’s existing

password. This resource is available in REST API version 24.0 and later.

You can only set one password per request. The new password must conform to the password policies for the organization, otherwise

an INVALID_NEW_PASSWORD error is returned.

If the session doesn’t have permission to access the user information, an INSUFFICIENT_ACCESS error is returned.

Syntax

URI

/services/data/vXX.X/sobjects/SelfServiceUser/selfServiceUserId/password

Formats

JSON, XML

197

Get Self-Service User Password Expiration StatusReference

HTTP Method

POST

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 83.

SEE ALSO:

Object Reference for the Salesforce Platform

Reset Self-Service User Password

Initiates a password reset for a self-service user based on the specified user ID. The user’s current password becomes invalid and the user

receives an email with a password reset link. To log in again, the user must finish resetting their password. This resource is available in

REST API version 24.0 and later.

Salesforce auto-generates a temporary password for the user and returns it in the response body. If the user can’t access the email link,

they can finish resetting their password by logging in with the temporary password.

If the session doesn’t have permission to access the user information, an INSUFFICIENT_ACCESS error is returned.

Syntax

URI

/services/data/vXX.X/sobjects/SelfServiceUser/selfServiceUserId/password

Formats

JSON, XML

HTTP Method

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 83.

SEE ALSO:

Object Reference for the Salesforce Platform

198

Reset Self-Service User PasswordReference

Return Headers Using sObject Self-Service User Password

Returns only the headers that are returned by sending a GET request to the sObject Self-Service User Password resource. This operation

allows you to see returned header values of the GET request before retrieving the content itself. This resource is available in REST API

version 24.0 and later.

If the session doesn’t have permission to access the user information, an INSUFFICIENT_ACCESS error is returned.

Syntax

URI

/services/data/vXX.X/sobjects/SelfServiceUser/selfServiceUserId/password

Formats

JSON, XML

HTTP Method

HEAD

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 83.

SEE ALSO:

Object Reference for the Salesforce Platform

Platform Event Schema by Event Name

Gets the definition of a platform event in JSON format for an event name. This resource is available in REST API version 40.0 and later.

Description400 Bad Request

The request was formatted incorrectly—an invalid value was passed for the payloadFormat parameter

in the URI.

In API version 43.0

and later

The request was formatted incorrectly—the payloadFormat parameter was passed in the URI but this

API version doesn’t support this parameter.

In API version 42.0

and earlier

Syntax

URI

/services/data/vXX.X/sobjects/eventName/eventSchema

Formats

JSON

199

Return Headers Using sObject Self-Service User PasswordReference

HTTP methods

GET

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

(Optional query parameter. Available in API version 43.0 and later.) The format of the returned event

schema. This parameter can take one of the following values.

payloadFormat

•

EXPANDED—The JSON representation of the event schema, which is the default format when

payloadFormat isn’t specified in API version 43.0 and later. The expanded event schema

is in the open-source Apache Avro format but doesn’t strictly adhere to the record complex

type. For more information about the schema fields, see Apache Avro Format.

•

COMPACT—The JSON representation of the event schema that adheres to the open-source

Apache Avro specification for the record complex type. For more information about the schema

fields, see Apache Avro Format. Subscribers use the compact schema format to deserialize

compact events received in binary form.

Examples for API Version 43.0 and Later

This URI gets the schema of a platform event named Low_Ink__e. In API version 43.0 and later, the default response format is the

JSON representation of the event schema.

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Low_Ink__e/eventSchema

-H "Authorization: Bearer token"

Or:

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Low_Ink__e/eventSchema?payloadFormat=EXPANDED

-H "Authorization: Bearer token"

The returned response for the expanded format looks like the following in API version 61.0.

{

"name": "Low_Ink__e",

"namespace": "com.sforce.eventbus",

"type": "expanded-record",

"fields": [

{

"name": "data",

"type": {

"type": "record",

"name": "Data",

"namespace": "",

"fields": [

{

"name": "schema",

200

Platform Event Schema by Event NameReference

"type": "string"

{

"name": "payload",

"type": {

"type": "record",

"name": "Payload",

"doc": "",

"fields": [

{

"name": "CreatedDate",

"type": "string",

"doc": "CreatedDate:DateTime"

{

"name": "CreatedById",

"type": "string",

"doc": "CreatedBy:EntityId"

{

"name": "Printer_Model__c",

"type": [

"null",

"string"

"doc": "Data:Text:00NRM000001krnv",

"default": null

{

"name": "Serial_Number__c",

"type": [

"null",

"string"

"doc": "Data:Text:00NRM000001kro0",

"default": null

{

"name": "Ink_Percentage__c",

"type": [

"null",

"double"

"doc": "Data:Double:00NRM000001kro5",

"default": null

}

]

}

{

"name": "event",

"type": {

"type": "record",

"name": "Event",

201

Platform Event Schema by Event NameReference

"fields": [

{

"name": "replayId",

"type": "long"

}

]

}

]

}

{

"name": "channel",

"type": "string"

}

]

}

To get the compact (Apache Avro) format, use the following URI.

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Low_Ink__e/eventSchema?payloadFormat=COMPACT

-H "Authorization: Bearer token"

The returned response for the compact format looks like the following in API version 61.0.

{

"name": "Low_Ink__e",

"namespace": "com.sforce.eventbus",

"type": "record",

"fields": [

{

"name": "CreatedDate",

"type": "long",

"doc": "CreatedDate:DateTime"

{

"name": "CreatedById",

"type": "string",

"doc": "CreatedBy:EntityId"

{

"name": "Printer_Model__c",

"type": [

"null",

"string"

"doc": "Data:Text:00NRM000001krnv",

"default": null

{

"name": "Serial_Number__c",

"type": [

"null",

"string"

202

Platform Event Schema by Event NameReference

"doc": "Data:Text:00NRM000001kro0",

"default": null

{

"name": "Ink_Percentage__c",

"type": [

"null",

"double"

"doc": "Data:Double:00NRM000001kro5",

"default": null

}

"uuid": "5E5OtZj5_Gm6Vax9XMXH9A"

}

Note: The compact schema doesn’t include the replayId or channel fields because these fields aren’t necessary for

deserializing the compact event received.

Examples for API Version 42.0 and Earlier

In API version 42.0 and earlier, the response format adheres to the open-source Apache Avro specification for the record complex type.

Note: This format is what the API returns in API version 43.0 and later when appending the ?payloadFormat=COMPACT

parameter.

curl

https://MyDomainName.my.salesforce.com/services/data/v42.0/sobjects/Low_Ink__e/eventSchema

-H "Authorization: Bearer token"

The returned response looks like the following in API version 42.0.

{

"name": "Low_Ink__e",

"namespace": "com.sforce.eventbus",

"type": "record",

"fields": [

{

"name": "CreatedDate",

"type": "long",

"doc": "CreatedDate:DateTime"

{

"name": "CreatedById",

"type": "string",

"doc": "CreatedBy:EntityId"

{

"name": "Printer_Model__c",

"type": [

"null",

"string"

203

Platform Event Schema by Event NameReference

"doc": "Data:Text:00NRM000001krnv",

"default": null

{

"name": "Serial_Number__c",

"type": [

"null",

"string"

"doc": "Data:Text:00NRM000001kro0",

"default": null

{

"name": "Ink_Percentage__c",

"type": [

"null",

"double"

"doc": "Data:Double:00NRM000001kro5",

"default": null

}

"uuid": "5E5OtZj5_Gm6Vax9XMXH9A"

}

Note: When you change the definition of a platform event, the schema ID for this platform event changes.

Apache Avro Format

The fields in the returned response adhere to the open-source Apache Avro specification for the record complex type (see Avro Records

in the Apache Avro specification). Note the following:

•

name is the name of the platform event.

•

namespace corresponds to com.sforce.eventbus.

•

type is the Avro complex type.

•

fields is a JSON array containing the fields of the platform event. For each field:

–

type indicates that the field can be either null or have a value of the specified type. When the field isn’t present, the value is

default.

–

doc describes the field data type and includes the field ID for custom fields. This field is intended for internal use. For example,

Salesforce uses the data type information to convert DateTime fields from long to DateTime. We recommend that you don't rely

on this field's value because it might change in the future.

The response also includes the uuid field, which contains the schema’s ID. The ID is the MD5 fingerprint of the normalized Avro schema

encoded as a base-64 URL variant. You can append this ID to the /vXX.X/event/eventSchema/ URI to retrieve the schema.

Platform Event Schema by Schema ID

Gets the definition of a platform event in JSON format for a schema ID. This resource is available in REST API version 40.0 and later.

204

Platform Event Schema by Schema IDReference

Description400 Bad Request

The request was formatted incorrectly—an invalid value was passed for the payloadFormat parameter

in the URI.

In API version 43.0

and later

The request was formatted incorrectly—the payloadFormat parameter was passed in the URI but this

API version doesn’t support this parameter.

In API version 42.0

and earlier

Syntax

URI

/services/data/vXX.X/event/eventSchema/schemaId

Formats

JSON

HTTP methods

GET

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

(Optional query parameter. Available in API version 43.0 and later.) The format of the returned event

schema. This parameter can take one of the following values.

payloadFormat

•

EXPANDED—The JSON representation of the event schema, which is the default format when

payloadFormat isn’t specified in API version 43.0 and later. The expanded event schema

is in the open-source Apache Avro format but doesn’t strictly adhere to the record complex

type. For more information about the schema fields, see Apache Avro Format.

•

COMPACT—The JSON representation of the event schema that adheres to the open-source

Apache Avro specification for the record complex type. For more information about the schema

fields, see Apache Avro Format. Subscribers use the compact schema format to deserialize

compact events received in binary form.

Examples for API Version 43.0 and Later

This URI gets the schema of a platform event whose schema ID is 5E5OtZj5_Gm6Vax9XMXH9A. This schema ID is a sample ID.

Replace it with a valid schema ID for your event.

/services/data/v61.0/event/eventSchema/5E5OtZj5_Gm6Vax9XMXH9A

Or:

/services/data/v61.0/event/eventSchema/5E5OtZj5_Gm6Vax9XMXH9A?payloadFormat=EXPANDED

205

Platform Event Schema by Schema IDReference

In API version 43.0 and later, the response format is the JSON representation of the event schema by default. The returned response

looks like the following in API version 61.0.

{

"name": "Low_Ink__e",

"namespace": "com.sforce.eventbus",

"type": "expanded-record",

"fields": [

{

"name": "data",

"type": {

"type": "record",

"name": "Data",

"namespace": "",

"fields": [

{

"name": "schema",

"type": "string"

{

"name": "payload",

"type": {

"type": "record",

"name": "Payload",

"doc": "",

"fields": [

{

"name": "CreatedDate",

"type": "string",

"doc": "CreatedDate:DateTime"

{

"name": "CreatedById",

"type": "string",

"doc": "CreatedBy:EntityId"

{

"name": "Printer_Model__c",

"type": [

"null",

"string"

"doc": "Data:Text:00NRM000001krnv",

"default": null

{

"name": "Serial_Number__c",

"type": [

"null",

"string"

"doc": "Data:Text:00NRM000001kro0",

"default": null

{

206

Platform Event Schema by Schema IDReference

"name": "Ink_Percentage__c",

"type": [

"null",

"double"

"doc": "Data:Double:00NRM000001kro5",

"default": null

}

]

}

{

"name": "event",

"type": {

"type": "record",

"name": "Event",

"fields": [

{

"name": "replayId",

"type": "long"

}

]

}

]

}

{

"name": "channel",

"type": "string"

}

]

}

To get the compact (Apache Avro) format, use the following URI.

/services/data/v61.0/event/eventSchema/5E5OtZj5_Gm6Vax9XMXH9A?payloadFormat=COMPACT

The returned response for the compact format looks like the following in API version 61.0.

{

"name": "Low_Ink__e",

"namespace": "com.sforce.eventbus",

"type": "record",

"fields": [

{

"name": "CreatedDate",

"type": "long",

"doc": "CreatedDate:DateTime"

{

"name": "CreatedById",

"type": "string",

"doc": "CreatedBy:EntityId"

207

Platform Event Schema by Schema IDReference

{

"name": "Printer_Model__c",

"type": [

"null",

"string"

"doc": "Data:Text:00NRM000001krnv",

"default": null

{

"name": "Serial_Number__c",

"type": [

"null",

"string"

"doc": "Data:Text:00NRM000001kro0",

"default": null

{

"name": "Ink_Percentage__c",

"type": [

"null",

"double"

"doc": "Data:Double:00NRM000001kro5",

"default": null

}

"uuid": "5E5OtZj5_Gm6Vax9XMXH9A"

}

Note: The compact schema doesn’t include the replayId or channel fields because these fields aren’t necessary for

deserializing the compact event received.

Example for API Version 42.0 and Earlier

In API version 42.0 and earlier, the response format adheres to the open-source Apache Avro specification for the record complex type.

Note: This format is what the API returns in API version 43.0 and later when appending the ?payloadFormat=COMPACT

parameter.

This URI gets the schema of a platform event whose schema ID is 5E5OtZj5_Gm6Vax9XMXH9A. This schema ID is a sample ID.

Replace it with a valid schema ID for your event.

/services/data/v42.0/event/eventSchema/5E5OtZj5_Gm6Vax9XMXH9A

The returned response looks like the following in API version 42.0.

{

"name": "Low_Ink__e",

"namespace": "com.sforce.eventbus",

"type": "record",

"fields": [

{

"name": "CreatedDate",

208

Platform Event Schema by Schema IDReference

"type": "long",

"doc": "CreatedDate:DateTime"

{

"name": "CreatedById",

"type": "string",

"doc": "CreatedBy:EntityId"

{

"name": "Printer_Model__c",

"type": [

"null",

"string"

"doc": "Data:Text:00NRM000001krnv",

"default": null

{

"name": "Serial_Number__c",

"type": [

"null",

"string"

"doc": "Data:Text:00NRM000001kro0",

"default": null

{

"name": "Ink_Percentage__c",

"type": [

"null",

"double"

"doc": "Data:Double:00NRM000001kro5",

"default": null

}

"uuid": "5E5OtZj5_Gm6Vax9XMXH9A"

}

Note: When you change the definition of a platform event, the schema ID for this platform event changes.

If you don’t have the schema ID, you can get the schema by supplying the platform event name. Make a GET request to

/services/data/vXX.X/sobjects/eventName/eventSchema. See Platform Event Schema by Event Name.

Apache Avro Format

The fields in the returned response adhere to the open-source Apache Avro specification for the record complex type (see Avro Records

in the Apache Avro specification). Note the following:

•

name is the name of the platform event.

•

namespace corresponds to com.sforce.eventbus.

•

type is the Avro complex type.

•

fields is a JSON array containing the fields of the platform event. For each field:

209

Platform Event Schema by Schema IDReference

type indicates that the field can be either null or have a value of the specified type. When the field isn’t present, the value is

default.

–

doc describes the field data type and includes the field ID for custom fields. This field is intended for internal use. For example,

Salesforce uses the data type information to convert DateTime fields from long to DateTime. We recommend that you don't rely

on this field's value because it might change in the future.

The response also includes the uuid field, which contains the schema’s ID. The ID is the MD5 fingerprint of the normalized Avro schema

encoded as a base-64 URL variant. You can append this ID to the /vXX.X/event/eventSchema/ URI to retrieve the schema.

Get AppMenu Types

Gets a list of App Menu types in the Salesforce app dropdown menu. This resource is available in REST API version 29.0 and later.

Syntax

URI

/services/data/vXX.X/appMenu/

Formats

JSON, XML

HTTP method

GET

Authentication

Authorization: Bearer token

Request body

None

Request parameters

None required

Example

Example Request

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/appMenu/ -H

"Authorization: Bearer token"

AppMenu Items

Accesses App Menu items from the Salesforce app dropdown menu. To retrieve a list of App Menu items, use the GET method. To retrieve

the headers returned by a request for App Menu items, use the HEAD method.

IN THIS SECTION:

Get AppMenu Items

Gets a list of the App Menu items in the Salesforce Lightning dropdown menu. This resource is available in REST API version 29.0

and later.

210

Get AppMenu TypesReference

Return Headers of App Menu Item Requests

Returns only the headers that are returned by a GET request for the Salesforce app dropdown menu items. Use this URI to see the

header values before you retrieve the content of the resource. This resource is available in REST API version 29.0 and later.

Get AppMenu Items

Gets a list of the App Menu items in the Salesforce Lightning dropdown menu. This resource is available in REST API version 29.0 and

later.

Syntax

URI

/services/data/vXX.X/appMenu/AppSwitcher/

Formats

JSON, XML

HTTP methods

GET

Authentication

Authorization: Bearer token

Request body

None

Request parameters

None required

Example

Example Request

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/appMenu/AppSwitcher -H

"Authorization: Bearer token"

Return Headers of App Menu Item Requests

Returns only the headers that are returned by a GET request for the Salesforce app dropdown menu items. Use this URI to see the header

values before you retrieve the content of the resource. This resource is available in REST API version 29.0 and later.

Syntax

URI

/services/data/vXX.X/appMenu/AppSwitcher/

Formats

JSON, XML

HTTP method

HEAD

211

Get AppMenu ItemsReference

Authentication

Authorization: Bearer token

Request body

None

Request parameters

None required

Example

Example Request

curl -X HEAD --head

https://MyDomainName.my.salesforce.com/services/data/v61.0/appMenu/AppSwitcher -H

"Authorization: Bearer token"

AppMenu Mobile Items

Accesses App Menu items from the Salesforce mobile app for Android and iOS and the mobile web navigation menu.

IN THIS SECTION:

Get AppMenu Mobile Items

Gets a list of the App Menu items in the Salesforce mobile app for Android and iOS and the mobile web navigation menu. This

resource is available in REST API version 29.0 and later.

Return Headers of AppMenu Mobile Item Requests

Returns only the headers that are returned by a GET request to the Salesforce mobile app for Android and iOS and the mobile web

navigation menu. Use this URI to see the header values before you retrieve the content of the resource. This resource is available in

REST API version 29.0 and later.

Get AppMenu Mobile Items

Gets a list of the App Menu items in the Salesforce mobile app for Android and iOS and the mobile web navigation menu. This resource

is available in REST API version 29.0 and later.

Syntax

URI

/services/data/vXX.X/appMenu/Salesforce1/

Formats

JSON, XML

HTTP methods

GET

Authentication

Authorization: Bearer token

212

AppMenu Mobile ItemsReference

Request body

None

Request parameters

None required

Example

Example Request

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/appMenu/Salesforce1/

-H "Authorization: Bearer token"

Example Response Body

{

"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",

213

Get AppMenu Mobile ItemsReference

"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",

"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",

214

Get AppMenu Mobile ItemsReference

"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",

"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"

} ]

}

Return Headers of AppMenu Mobile Item Requests

Returns only the headers that are returned by a GET request to the Salesforce mobile app for Android and iOS and the mobile web

navigation menu. Use this URI to see the header values before you retrieve the content of the resource. This resource is available in REST

API version 29.0 and later.

Syntax

URI

/services/data/vXX.X/appMenu/Salesforce1/

Formats

JSON, XML

HTTP methods

HEAD

Authentication

Authorization: Bearer token

Request body

None

Request parameters

None required

215

Return Headers of AppMenu Mobile Item RequestsReference

Example

Example Request

curl -X HEAD --head

https://MyDomainName.my.salesforce.com/services/data/v61.0/appMenu/Salesforce1 -H

"Authorization: Bearer token"

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 isn’t supported for bulk queries. If you want to get the primary compact layout for PersonAccount, get it

directly from

/services/data/v61.0/sobjects/Account/describe/compactLayouts/primaryPersonAccount.

Syntax

URI

/services/data/vXX.X/compactLayouts?q=objectList

Formats

JSON, XML

HTTP methods

GET

Authentication

Authorization: Bearer token

Request parameters

DescriptionParameter

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.

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/compactLayouts?q=Account,Contact,CustomObj__c

-H "Authorization: Bearer token"

Example Response Body

{

"Account" : {

"actions" : [ {

216

Compact LayoutsReference

"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,

"width" : null,

"windowPosition" : null

...

"id" : null,

"label" : "System Default",

"name" : "SYSTEM"

}

"CustomObj__c" : {

"actions" : [ {

217

Compact LayoutsReference

"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"

}

Consent

Your users can store consent preferences in different locations and possibly inconsistently. You can locate your customers’ preferences

for consent across multiple records when using API version 44.0 and later. Tracking consent preferences helps you and your users respect

the most restrictive requests. You can use the Consent API with specific Data Cloud parameters with API version 50.0 and later.

Compile Consent Settings

Gets consent details based on a single action, like email or track, across specific consent management objects when the records have a

lookup relationship. This resource is available in REST API version 45.0 and later.

To call Consent API, you must have either the View All Data or the Allow User Access to Privacy Data user permission. Requiring a perm

ensures that the System Administrator gives explicit permission. This API accesses org-wide consent data, such as links between records

and the value of consent flags, not just records to which the user ordinarily has access.

Consent API gets consent details based on a single action, like email or track, across the Contact, Contact Point Type Consent, Data Use

Purpose, Individual, Lead, Person Account, and User objects when the records have a lookup relationship.

When you select email as the action, the API only aggregates consent for records that contain the same email address. If the record ID

specified in the URI is associated with a record that contains a different email address, the consent settings of the associated record aren’t

included in the API response. The Consent API can't locate records in which the email address field is protected by Platform Encryption.

Note: When the API compares consent settings across records, it doesn’t incorporate settings from converted leads.

218

ConsentReference

Response SchemaAPI ResponseFields ConsultedAction

{Within the time range

if specified in

ContactPointTypeConsent:

Contact.HasOptedOutOfEmail

"<ID/Email>" :

{

ContactPointTypeConsent.ContactPointType

ContactPointTypeConsent.EffectiveFrom

Returns TRUE if all

consulted field values

are 0.

"result" : "<Success/errormessage>",

"proceed" : { "emailResult" : "<Success/errormessage>",

email : “<true/false>” }

ContactPointTypeConsent.EffectiveTo

ContactPointTypeConsent.PrivacyConsentStatus

Returns FALSE if any

consulted field value is

DataUsePurpose.Name

}

Lead.HasOptedOutOfEmail

1 or if no related

}

PersonAccount.HasOptedOutOfEmail

Contact, Contact Point

Type Consent, Lead, or

Person Account object

exists.

{Returns TRUE if all

consulted field values

are 0.

fax

Contact.HasOptedOutOfFax

"<ID/Email>" :

{

DataUsePurpose.Name

Lead.HasOptedOutOfFax

Returns FALSE if any

consulted field value is

"result" : "<Success/errormessage>",PersonAccount.HasOptedOutOfFax

1 or if no related

"proceed" : { "faxResult" : "<Success/errormessage>", fax

: "<true/false>" }

Contact, Lead, or

Person Account object

exists.

}

{Returns TRUE if the

consulted field value is

geotrack

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.HasOptedOutGeoTracking

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

1 or if no related

Individual object exists.

"proceed" : { "geotrackResult" : "<Success/errormessage>",

"geotrack" : "<true/false>" }

}

{Within the time range

if specified in

ContactPointTypeConsent:

mail

ContactPointTypeConsent.ContactPointType

"<ID/Email>" :

{

ContactPointTypeConsent.EffectiveFrom

ContactPointTypeConsent.EffectiveTo

Returns TRUE if all

consulted field values

are 0.

"result" : "<Success/errormessage>",

"proceed" : { "mailingResult" : "<Success/errormessage>",

"mail" : "<true/false>" }

ContactPointTypeConsent.PrivacyConsentStatus

DataUsePurpose.Name

Returns FALSE if any

consulted field value is

}

1 or if no related

219

Compile Consent SettingsReference

}Contact, Contact Point

Type Consent, Lead, or

Person Account object

exists.

{Within the time range

if specified in

ContactPointTypeConsent:

phone

Contact.DoNotCall

"<ID/Email>" :

{

ContactPointTypeConsent.ContactPointType

ContactPointTypeConsent.EffectiveFrom

Returns TRUE if all

consulted field values

are 0.

"result" : "<Success/errormessage>",

"proceed" : { "phoneResult" : "<Success/errormessage>",

"phone" : "<true/false>" }

ContactPointTypeConsent.EffectiveTo

ContactPointTypeConsent.PrivacyConsentStatus

Returns FALSE if any

consulted field value is

DataUsePurpose.Name

}

Lead.DoNotCall

1 or if no related

}

PersonAccount.DoNotCall

Contact, Contact Point

Type Consent, Lead, or

Person Account object

exists.

{Returns TRUE if the

consulted field value is

portability

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.SendIndividualData

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

0 or if no related

Individual object exists.

"proceed" : { "portabilityResult" :

"<Success/errormessage>", "portability" : "<true/false>"

}

{Returns TRUE if the

consulted field value is

process

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.HasOptedOutProcessing

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

1 or if no related

Individual object exists.

"proceed" : { "processResult" : "<Success/errormessage>",

"process" : "<true/false>" }

}

{Returns TRUE if the

consulted field value is

profile

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.HasOptedOutProfiling

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

220

Compile Consent SettingsReference

"proceed" : { "profileResult" : "<Success/errormessage>",

"profile" : "<true/false>" }

1 or if no related

Individual object exists.

}

{Returns TRUE if the

consulted field value is

shouldforget

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.ShouldForget

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

0 or if no related

Individual object exists.

"proceed" : { "shouldForgetResult" :

"<Success/errormessage>", "shouldforget" :

"<true/false>" }

}

{Within the time range

if specified in

ContactPointTypeConsent:

social

ContactPointTypeConsent.ContactPointType

"<ID/Email>" :

{

ContactPointTypeConsent.EffectiveFrom

ContactPointTypeConsent.EffectiveTo

Returns TRUE if all

consulted field values

are 0.

"result" : "<Success/errormessage>",

"proceed" : { "socialResult" : "<Success/errormessage>",

"social" : "<true/false>" }

ContactPointTypeConsent.PrivacyConsentStatus

DataUsePurpose.Name

Returns FALSE if any

consulted field value is

}

1 or if no related

}

Contact, Contact Point

Type Consent, Lead, or

Person Account object

exists.

{Returns TRUE if the

consulted field value is

solicit

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.HasOptedOutSolicit

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

1 or if no related

Individual object exists.

"proceed" : { "solicitResult" : "<Success/errormessage>",

"solicit" : "<true/false>" }

}

{Returns TRUE if the

consulted field value is

storepiielsewhere

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.CanStorePiiElsewhere

221

Compile Consent SettingsReference

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

"proceed" : { "storePIIElsewhereResult" :

"<Success/errormessage>", "storepiielsewhere" :

"<true/false>" }

0 or if no related

Individual object exists.

}

{Returns TRUE if the

consulted field value is

track

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.HasOptedOutTracking

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

1 or if no related

Individual object exists.

"proceed" : { "trackResult" : "<Success/errormessage>",

"track" : "<true/false>" }

}

{Within the time range

if specified in

ContactPointTypeConsent:

web

ContactPointTypeConsent.ContactPointType

"<ID/Email>" :

{

ContactPointTypeConsent.EffectiveFrom

ContactPointTypeConsent.EffectiveTo

Returns TRUE if all

consulted field values

are 0.

"result" : "<Success/errormessage>",

"proceed" : { "webResult" : "<Success/errormessage>",

"web" : "<true/false>" }

ContactPointTypeConsent.PrivacyConsentStatus

DataUsePurpose.Name

Returns FALSE if any

consulted field value is

}

1 or if no related

}

Contact, Contact Point

Type Consent, Lead, or

Person Account object

exists.

Syntax

URI

/services/data/vXX.X/consent/action/action?ids=listOfIds

Formats

JSON

HTTP methods

GET

Authentication

Authorization: Bearer token

Request body

None

222

Compile Consent SettingsReference

Request parameters

DescriptionParameter

Required. The proposed action.

If this parameter is used, actions can't be used.

action

Optional: true or false. aggregatedConsent is the same as

aggregatedConsent=true. If true, one result is returned indicating whether

aggregatedConsent

to proceed or not, rather than a result for each ID. If any ID in the list returns false, the

aggregated result is false.

Optional. The timestamp for which consent is determined. The value is converted to

the UTC timezone and must be formatted as described in Valid Date and DateTime

Formats. If not specified, defaults to the current date and time.

datetime

Required. Comma-separated list of IDs. The ID can be the record ID or the email address

listed on the record.

ids

Optional. Use policy=requireExplicitConsent to specify in the API

response whether explicit consent was given for a contact point channel. The API

returns an infoNotFound response when consent isn’t specified.

This parameter is available in API version 49.0 and later.

policy

Optional. The reason for contacting a customer.purpose

Optional: true or false. verbose is the same as verbose=true. Verbose responses

are slower than non-verbose responses. See the examples for a verbose response.

verbose

Example

Request for URI structure

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/consent/action/track?ids=003xx000004TxyY,00Qxx00000syyO,003zz000004zzZ

-H "Authorization: Bearer token"

Request for Email addresses as IDs, specified purpose and timespan, and a verbose response

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/consent/action/[email protected],[email protected]&datetime=2018-12-12T00:00:00Z

-H "Authorization: Bearer token"

Response Body

{

"[email protected]" : {

"result" : "Success",

"proceed" : {

"email" : "true"

"emailResult" : "Success"

"explanation" : [ {

223

Compile Consent SettingsReference

"objectConsulted" : "ContactTypePointConsent",

"status" : "opt_in",

"purpose" : "billing",

"recordId" : "003xx000004TxyY",

"value" : "true"

},{

"objectConsulted" : "Contact",

"field" : "HasOptedOutOfTracking",

"recordId" : "1",

"value" : "true"

}]

"[email protected]" : {

"result" : "Success",

"proceed" : {

"email" : "false"

"emailResult" : "Success"

"explanation" : [ {

"objectConsulted" : "Contact",

"field" : "HasOptedOutOfEmail",

"recordId" : "00Qxx00000skwO",

"value" : "true"

} ]

}

Compile Multiple Types of Consent Settings

Gets consent details based on multiple actions, like email and track, across specific consent management objects when the records have

a lookup relationship. Available in API version 45.0 and later.

To call Consent API, you must have either the View All Data or the Allow User Access to Privacy Data user permission. Requiring a perm

ensures that the System Administrator gives explicit permission. This API accesses org-wide consent data, such as links between records

and the value of consent flags, not just records to which the user ordinarily has access.

Consent API gets consent details across the Contact, Contact Point Type Consent, Data Use Purpose, Individual, Lead, Person Account,

and User objects when the records have a lookup relationship.

The following table shows how the API responses are determined. If the consulted fields find conflicting consent preferences, the response

returns the least permissive preference. For example, if Contact.HasOptedOutOfEmail is false, but Lead.HasOptedOutOfEmail is true,

the response indicates that you can’t proceed with emailing the user.

When you select email as the action, the API only aggregates consent for records that contain the same email address. If the record ID

specified in the URI is associated with a record that contains a different email address, the consent settings of the associated record aren’t

included in the API response.

Note: When the API compares consent settings across records, it doesn’t incorporate settings from converted leads.

Response SchemaAPI ResponseFields ConsultedAction

{Within the time range

if specified in

ContactPointTypeConsent:

Contact.HasOptedOutOfEmail

"<ID/Email>" :

224

Compile Multiple Types of Consent SettingsReference

{Returns TRUE if all

consulted field values

are 0.

ContactPointTypeConsent.ContactPointType

"result" : "<Success/errormessage>",

"proceed" : { "emailResult" : "<Success/errormessage>",

email : “<true/false>” }

ContactPointTypeConsent.EffectiveFrom

ContactPointTypeConsent.EffectiveTo

Returns FALSE if any

consulted field value is

ContactPointTypeConsent.PrivacyConsentStatus

}

1 or if no related

DataUsePurpose.Name

}

Contact, Contact Point

Type Consent, Lead, or

Lead.HasOptedOutOfEmail

PersonAccount.HasOptedOutOfEmail

Person Account object

exists.

{Returns TRUE if all

consulted field values

are 0.

fax

Contact.HasOptedOutOfFax

"<ID/Email>" :

{

DataUsePurpose.Name

Lead.HasOptedOutOfFax

Returns FALSE if any

consulted field value is

"result" : "<Success/errormessage>",PersonAccount.HasOptedOutOfFax

1 or if no related

"proceed" : { "faxResult" : "<Success/errormessage>", fax

: "<true/false>" }

Contact, Lead, or

Person Account object

exists.

}

{Returns TRUE if the

consulted field value is

geotrack

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.HasOptedOutGeoTracking

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

1 or if no related

Individual object exists.

"proceed" : { "geotrackResult" : "<Success/errormessage>",

"geotrack" : "<true/false>" }

}

{Within the time range

if specified in

ContactPointTypeConsent:

mail

ContactPointTypeConsent.ContactPointType

"<ID/Email>" :

{

ContactPointTypeConsent.EffectiveFrom

ContactPointTypeConsent.EffectiveTo

Returns TRUE if all

consulted field values

are 0.

"result" : "<Success/errormessage>",

"proceed" : { "mailingResult" : "<Success/errormessage>",

"mail" : "<true/false>" }

ContactPointTypeConsent.PrivacyConsentStatus

DataUsePurpose.Name

Returns FALSE if any

consulted field value is

}

1 or if no related

}

Contact, Contact Point

Type Consent, Lead, or

Person Account object

exists.

225

Compile Multiple Types of Consent SettingsReference

{Within the time range

if specified in

ContactPointTypeConsent:

phone

Contact.DoNotCall

"<ID/Email>" :

{

ContactPointTypeConsent.ContactPointType

ContactPointTypeConsent.EffectiveFrom

Returns TRUE if all

consulted field values

are 0.

"result" : "<Success/errormessage>",

"proceed" : { "phoneResult" : "<Success/errormessage>",

"phone" : "<true/false>" }

ContactPointTypeConsent.EffectiveTo

ContactPointTypeConsent.PrivacyConsentStatus

Returns FALSE if any

consulted field value is

DataUsePurpose.Name

}

Lead.DoNotCall

1 or if no related

}

PersonAccount.DoNotCall

Contact, Contact Point

Type Consent, Lead, or

Person Account object

exists.

{Returns TRUE if the

consulted field value is

portability

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.SendIndividualData

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

0 or if no related

Individual object exists.

"proceed" : { "portabilityResult" :

"<Success/errormessage>", "portability" : "<true/false>"

}

{Returns TRUE if the

consulted field value is

process

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.HasOptedOutProcessing

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

1 or if no related

Individual object exists.

"proceed" : { "processResult" : "<Success/errormessage>",

"process" : "<true/false>" }

}

{Returns TRUE if the

consulted field value is

profile

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.HasOptedOutProfiling

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

1 or if no related

Individual object exists.

"proceed" : { "profileResult" : "<Success/errormessage>",

"profile" : "<true/false>" }

}

226

Compile Multiple Types of Consent SettingsReference

{Returns TRUE if the

consulted field value is

shouldforget

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.ShouldForget

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

0 or if no related

Individual object exists.

"proceed" : { "shouldForgetResult" :

"<Success/errormessage>", "shouldforget" :

"<true/false>" }

}

{Within the time range

if specified in

ContactPointTypeConsent:

social

ContactPointTypeConsent.ContactPointType

"<ID/Email>" :

{

ContactPointTypeConsent.EffectiveFrom

ContactPointTypeConsent.EffectiveTo

Returns TRUE if all

consulted field values

are 0.

"result" : "<Success/errormessage>",

"proceed" : { "socialResult" : "<Success/errormessage>",

"social" : "<true/false>" }

ContactPointTypeConsent.PrivacyConsentStatus

DataUsePurpose.Name

Returns FALSE if any

consulted field value is

}

1 or if no related

}

Contact, Contact Point

Type Consent, Lead, or

Person Account object

exists.

{Returns TRUE if the

consulted field value is

solicit

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.HasOptedOutSolicit

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

1 or if no related

Individual object exists.

"proceed" : { "solicitResult" : "<Success/errormessage>",

"solicit" : "<true/false>" }

}

{Returns TRUE if the

consulted field value is

storepiielsewhere

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.CanStorePiiElsewhere

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

0 or if no related

Individual object exists.

"proceed" : { "storePIIElsewhereResult" :

"<Success/errormessage>", "storepiielsewhere" :

"<true/false>" }

}

227

Compile Multiple Types of Consent SettingsReference

}

{Returns TRUE if the

consulted field value is

track

DataUsePurpose.Name

"<ID/Email>" :

{

Individual.HasOptedOutTracking

Returns FALSE if the

consulted field value is

"result" : "<Success/errormessage>",

1 or if no related

Individual object exists.

"proceed" : { "trackResult" : "<Success/errormessage>",

"track" : "<true/false>" }

}

{Within the time range

if specified in

ContactPointTypeConsent:

web

ContactPointTypeConsent.ContactPointType

"<ID/Email>" :

{

ContactPointTypeConsent.EffectiveFrom

ContactPointTypeConsent.EffectiveTo

Returns TRUE if all

consulted field values

are 0.

"result" : "<Success/errormessage>",

"proceed" : { "webResult" : "<Success/errormessage>",

"web" : "<true/false>" }

ContactPointTypeConsent.PrivacyConsentStatus

DataUsePurpose.Name

Returns FALSE if any

consulted field value is

}

1 or if no related

}

Contact, Contact Point

Type Consent, Lead, or

Person Account object

exists.

Syntax

URI

/services/data/vXX.X/consent/multiaction?actions=listOfActions&ids=listOfIds

Formats

JSON

HTTP methods

GET

Authentication

Authorization: Bearer token

Request body

None

Request parameters

DescriptionParameter

Required. Comma-separated list of proposed actions.

If this parameter is used, action can't be used.

actions

228

Compile Multiple Types of Consent SettingsReference

DescriptionParameter

Optional: true or false. aggregatedConsent is the same as

aggregatedConsent=true. If true, one result is returned indicating whether

aggregatedConsent

to proceed or not, rather than a result for each ID. If any ID in the list returns false, the

aggregated result is false.

Optional. The timestamp for which consent is determined. The value is converted to

the UTC timezone and must be formatted as described in Valid Date and DateTime

Formats. If not specified, defaults to the current date and time.

datetime

Required. Comma-separated list of IDs. The ID can be the record ID or the email address

listed on the record.

ids

Optional. Use policy=requireExplicitConsent to specify in the API

response whether explicit consent was given for a contact point channel. The API

returns an infoNotFound response when consent isn’t specified.

This parameter is available in API version 49.0 and later.

policy

Optional. The reason for contacting a customer.purpose

Optional: true or false. verbose is the same as verbose=true. Verbose responses

are slower than non-verbose responses. See the examples for a verbose response.

verbose

Example

Request for Multiaction URI structure

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/consent/multiaction?actions=track,geotrack,email&ids=003xx000008TiyY,00Qxx00000skwO,[email protected]

-H "Authorization: Bearer token"

Request for email addresses as IDs, specified purpose and timespan, and a verbose response

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/consent/action/[email protected],[email protected]&datetime=2018-12-12T00:00:00Z&purpose=billing&verbose=true

-H "Authorization: Bearer token"

Response Body

{

"[email protected]" : {

"result" : "Success",

"proceed" : {

"email" : "false"

"emailResult" : "Success"

"track" : "false"

"trackResult" : "Success"

"solicit" : "false"

"solicitResult" : "Success"

"explanation" : [ {

"objectConsulted" : "ContactTypePointConsent",

"status" : "opt_in",

229

Compile Multiple Types of Consent SettingsReference

"purpose" : "billing",

"recordId" : "003xx000004TxyY",

"value" : "true"

},{

"objectConsulted" : "Individual",

"field" : "HasOptedOutOfTracking",

"recordId" : "0PKx000006JkyZ",

"value" : "true"

}]

"[email protected]" : {

"result" : "Success",

"proceed" : {

"email" : "false"

"emailResult" : "Success"

"track" : "false"

"trackResult" : "Success"

"solicit" : "true"

"solicitResult" : "Success"

"explanation" : [ {

"objectConsulted" : "Contact",

"field" : "HasOptedOutOfEmail",

"recordId" : "00Qxx00000skwO",

"value" : "true"

},{

"objectConsulted" : "Individual",

"field" : "HasOptedOutOfSolicit",

"recordId" : "0PKx000003JcpK",

"value" : "false"

}]

}

Use the Consent API with Data Cloud

The Consent API supports Data Cloud. Use the Consent API to read and write to the Data Cloud profile. Contact your Salesforce

Representative for consumer rights guidance within Data Cloud.

Required Permissions

To use Data Cloud parameters for Consent API, you must have either the ModifyAllData or the ConsentApiUpdate user permission.

Requiring a perm ensures that the Salesforce admin gives explicit permission. These parameters write org-wide consent data, such as

links between records and the value of consent flags, which are usually inaccessible to non-admin users.

Actions Supported by Consent API with Data Cloud

DescriptionAction

This action is used to restrict processing of data in Data Cloud processes such as query and

segmentation.

Processing

230

Use the Consent API with Data CloudReference

DescriptionAction

This action is used to allow export of Data Cloud profile data.Portability

This action indicates the right to be forgotten, which means permanently deleting PII (Personally

Identifiable Information) data and any related records. After a profile is processed, it can no longer

be used again.

ShouldForget

Data Cloud Read Parameters

The Consent API allows you to gather information about the Data Cloud profile. Use the mode and ids Data Cloud parameters as

described below.

Syntax

HTTP method

GET

Available since release:

48.0

URI

Note: You can access the consent API using three different URIs based on the Action. The Actions supported are

processing,portability, and shouldforget.

/services/data/vXX.X/consent/action/processing?ids=<list_of_ids>&mode=<cdp>

/services/data/vXX.X/consent/action/portability?ids=<list_of_ids>&mode=<cdp>

/services/data/vXX.X/consent/action/shouldforget?ids=<list_of_ids>&mode=<cdp>

Request parameters

DescriptionParameter

Required. Comma-separated list of IDs. The ID provided must be present in a field

mapped to Individual.Individual Id.

ids

Optional. Default is normal. Valid value to retrieve a Data Cloud profile is cdp.mode

Read Example

URI

/services/data/v61.0/consent/action/portability?ids=00932I3SU92&mode=cdp

Response

{ "j00932I3SU92" : { "result" : "Success", "proceed" : { "portability" : "true"

"portabilityResult" : "Success" } } }

Write Parameters

The Consent API also allows you to write information to the Data Cloud profile. Use the ids, mode, and status parameters as described

below.

231

Use the Consent API with Data CloudReference

Note: You can update your consent information with the consent API using three different URIs. The URIs are based on the action

that is to be performed on the Data Cloud profile. The actions supported are processing, portability, and

shouldforget.

Syntax

HTTP method

PATCH

Available since release

50.0

URI when action is processing

/services/data/vXX.X/consent/action/processing?ids=list_of_ids&mode=cdp&status=optin

or optout

Request parameters when action is processing

DescriptionParameter

Required. Comma-separated list of IDs. The ID provided must be present in a field

mapped to Individual.Individual Id.

ids

Optional. Default is normal. Valid value to use for updating a Data Cloud profile is cdp.mode

Required. Status of the consent. Allowed values are optin or optout. However,

when action is processing use status as optout.

status

URI when action is shouldforget

/services/data/vXX.X/consent/action/shouldforget?ids=list_of_ids&mode=cdp&status=optin

or optout

Request parameters when action is shouldforget

DescriptionParameter

Required. Comma-separated list of IDs. The ID provided must be present in a field

mapped to Individual.Individual Id.

ids

Optional. Default is normal. Valid value to use for updating a Data CloudCDP profile is

cdp.

mode

Required. Status of the consent. Allowed values are optin or optout. However,

when action is shouldforget use status as optin.

status

URI action is portability

/services/data/vXX.X/consent/action/portability?ids=list_of_ids&mode=cdp&status=optin

or optout

232

Use the Consent API with Data CloudReference

Request parameters when action is portability

DescriptionParameter

Required. Comma-separated list of IDs. The ID provided must be present in a field

mapped to Individual.Individual Id.

ids

Optional. Default is normal. Valid value to use for updating a Data Cloud profile is cdp.mode

Required. Status of the consent. Allowed values are optin or optout. When action

is portability use status as optin.

status

Required only when mode is 'cdp' and the action is 'portability'. This parameter must

be passed in as part of the PATCH request body. This parameter is used to pass the S3

bucket location for portability requests to Data Cloud.

aws_s3_bucket_id

Required only when mode is 'cdp' and the action is 'portability'. This parameter must

be passed in as part of the PATCH request body. This parameter is used to pass the S3

bucket access key for portability requests to Data Cloud.

aws_access_key_id

Required only when mode is 'cdp' and the action is 'portability'. This parameter must

be passed in as part of the PATCH request body. This parameter is used to pass the S3

bucket secret access key for portability requests to Data Cloud.

aws_secret_access_key

Required only when mode is 'cdp' and the action is 'portability'. This parameter must

be passed in as part of the PATCH request body. This parameter is used to pass the S3

bucket folder for portability requests to Data Cloud.

aws_s3_folder

Required only when mode is 'cdp' and the action is 'portability'. This parameter must

be passed in as part of the PATCH request body. This parameter is used to pass the S3

bucket's aws region for portability requests to Data Cloud.

aws_region

Write Example

When action is processing

/services/data/v61.0/consent/action/processing?ids=100000695&mode=cdp&status=optout

body: {}

When action is portability

/services/data/v61.0/consent/action/portability?ids=100000695&mode=cdp&status=optin

body:{

"aws_s3_bucket_id" : "cdpgdprtest",

"aws_access_key_id": "ABCD1234WEXAMPLE",

"aws_secret_access_key": "WXYZ1234EXAMPLE",

"aws_s3_folder": "yyun/Person",

"aws_region": "us-west-1"

}

When action is shouldforget

/services/data/v61.0/consent/action/shouldforget?ids=100000695 &mode=cdp&status=optin

body: {}

233

Use the Consent API with Data CloudReference

Consent Write

Your users can store consent preferences in different locations. The Consent Write API can update and write consent across multiple

records through a single API call, helping you sync consent across records or populate the new Consent data model. This resource is

available in REST API version 48.0 and later.

Consent API writes consent values across the Contact, Contact Point Type Consent, Data Use Purpose, Individual, Lead, Person Account,

and User objects when the records have a lookup relationship or share an email address. This API can also write to the Data Cloud

Individual record. The Consent API can't locate records in which the email address field is protected by Platform Encryption.

Note: For the Spring ‘21 release, the API only takes in a single email address. Any record with a matching email address is updated

based on the parameters set in the API call.

All records with the email address listed are updated. If the Create Individual parameter is selected and no Individual record exists, the

API creates an Individual record. If warranted, the API also creates a Contact Point Type Consent and Contact Point Email record.

Only Data Cloud uses the request body. If not passing anything in the request body, pass in an empty object {}.

Syntax

URI

/services/data/vXX.X/consent/action/action?ids=listOfIds

Formats

JSON

HTTP methods

PATCH

Authentication

Authorization: Bearer token

Request parameters

DescriptionParameter

Optional. Use to pass information to Data Cloud, such as portability write location. Use

only for mode=cdp. This parameter must be passed in as part of the PATCH request

body.

blobParam

Optional. The date and time when consent is captured. The default is the date and

time the API call is made.

captureDate

Optional. Describes how consent is captured (web, phone, email). Supported values

are:

captureContactPointType

•

phone

•

web (default)

Optional. The source through which consent is captured. The default capture source

is Consent API. Max length 255 characters.

captureSource

234

Consent WriteReference

DescriptionParameter

Optional. Use to set the name for any new consent records. Default is: Individual

Name-Datetime (<Name> 2019-03-31T15:47:57). Max length is

255 characters.

consentName

Optional. Boolean. If set to true and the API call includes an email address that

matches multiple records without an Individual object, then an Individual object is

createIndividual

created. Any consent records with an email address that match the email in the API

call are linked to the new Individual object. If multiple records are found, then any

records not linked to an Individual object is linked to the Individual object found in the

other records. If more than one Individual object is found on the matching records,

then the call is rejected.

Optional. The date and time that the double opt-in is completed, formatted as described

in Valid Date and DateTime Formats.

doubleOptIn

Optional. The date from which consent is effective, formatted as described in Valid

Date and DateTime Formats. The default is the date the API call is made.

effectiveFrom

Optional. The date through which consent is effective, formatted as described in Valid

Date and DateTime Formats.

effectiveTo

Required. The email address used to sync consent. The ID can be the record ID or the

email address listed on the record. When mode=cdp, the ID value is a string equal

to the Individual ID attribute.

ids

Optional. The name of the person in an Individual record. If a name isn’t provided for

a new Individual record, then the local part of the passed-in email address is used. Max

length is 80 characters.

individualName

Optional. Default is normal. The allowed modes are: normal or cdp. With

mode=cdp, the request is passed to the Data Cloud platform to get or write consent.

mode

The mode=cdp parameter only supports the action, blobParam, and ids

parameters.

Optional. The data use purpose for which consent is provided. Must use an existing

data use purpose that you previously created. If more than one purpose with the same

name exists, only one purpose is selected.

purposeName

Required. Status of the consent (OptIn, OptOut, Seen, NotSeen.) If action exists

on an Individual object (for example, tracking or processing), the only valid values are

OptIn and OptOut.

status

Action

Allowed values are:

•

fax

•

geotrack

•

mailing

•

phone

235

Consent WriteReference

•

portability

•

process

•

profile

•

shouldForget

•

social

•

solicit

•

storePiiElsewhere

•

track

•

web

Security

To call the Consent Write API, you must have either the ModifyAllData or the ConsentApiUpdate user permission. This API writes org-wide

consent data, such as links between records and the value of consent flags, and not just records to which the user ordinarily has access.

The ConsentApiUpdate user permission grants full write permission to the user during the Consent Write API call.

Example

Example Request

curl -X PATCH

https://MyDomainName.my.salesforce.com/services/data/v61.0/consent/action/<action>?ids=<email-OR-recordID>&status=<optout/optin/seen/notseen>&createIndividual=<true/false>

-H "Content-Type: application/json" -d "@exampleRequestBody.json"

Example Request Body

{}

Example Response Body

{

"<email-OR-recordID>" : {

"result" : "Success",

"edited" : [{

"objectType" : "<Contact, Lead, User, etc.>",

"field" : "<HasOptedOutofFax, DoNotCall,etc>",

"valueOfField" : "<true/false>",

"id" : "<recordID>"

}],

}

Embedded Service Configuration Describe

Retrieves the values for your Embedded Service deployment configuration or the headers returned by a request.

236

Embedded Service Configuration DescribeReference

IN THIS SECTION:

Get Embedded Service Configuration

Get the values for your Embedded Service deployment configuration, including the branding colors, font, and site URL. This resource

is available in REST API version 45.0 and later.

Return Headers for Embedded Service Configuration

Returns only the headers from a GET request to the Embedded Service Configuration Describe resource. This gives you a chance to

see header values ahead of time before retrieving the content of the resource. You must be logged in to the account that owns the

EmbeddedServiceConfigDeveloperName you are querying. This resource is available in REST API version 45.0 and later.

Get Embedded Service Configuration

Get the values for your Embedded Service deployment configuration, including the branding colors, font, and site URL. This resource is

available in REST API version 45.0 and later.

You must be logged in to the account that owns the EmbeddedServiceConfigDeveloperName you are querying.

Syntax

URI

/services/data/vXX.X/support/embeddedservice/configuration/embeddedServiceConfigDeveloperName

Formats

JSON

HTTP method

GET

Authentication

Authorization: Bearer token

Request parameters

None

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/support/embeddedservice/configuration/TestOne

-H "Authorization: Bearer token"

Example Response Body

{

"embeddedServiceConfig" : {

"areGuestUsersAllowed" : false,

"authMethod" : "CustomLogin",

"embeddedServiceBranding" : {

"contrastInvertedColor" : "#ffffff",

"contrastPrimaryColor" : "#333333",

"font" : "Salesforce Sans",

"height" : 498,

"navBarColor" : "#222222",

237

Get Embedded Service ConfigurationReference

"primaryColor" : "#222222",

"secondaryColor" : "#005290",

"width" : 320

"embeddedServiceLiveAgent" : {

"avatarImg" : "",

"embeddedServiceQuickActions" : [ {

"order" : 1,

"quickActionDefinition" : "Snapins_Case_OfflineCaseQuickAction_08hRM00000000cC",

"quickActionType" : "OfflineCase"

}, {

"order" : 1,

"quickActionDefinition" : "Snapins_Contact_PrechatQuickAction_08hRM00000000RC",

"quickActionType" : "Prechat"

}, {

"order" : 2,

"quickActionDefinition" : "Snapins_Case_PrechatQuickAction_08hRM00000000RC",

"quickActionType" : "Prechat"

} ],

"enabled" : true,

"fontSize" : "Medium",

"headerBackgroundImg" : "https://google.com/img/headerBgImgUrl.png",

"isOfflineCaseEnabled" : true,

"isQueuePositionEnabled" : true,

"liveChatButton" : "573RM0000004GGf",

"liveChatDeployment" : "572RM0000004CDV",

"offlineCaseBackgroundImg" : "https://google.com/img/offlineBgImgUrl.png",

"prechatBackgroundImg" : "https://google.com/img/prechatBgImgUrl.png",

"prechatEnabled" : true,

"scenario" : "Service",

"smallCompanyLogoImg" : "https://google.com/img/logoImgUrl.png",

"waitingStateBackgroundImg" : "https://google.com/img/bgImgUrl.png"

"shouldHideAuthDialog" : false,

"siteUrl" : "https://snapins-15f082fb956-15fbc261d27.stmfa.stm.force.com/napili2"

}

Return Headers for Embedded Service Configuration

Returns only the headers from a GET request to the Embedded Service Configuration Describe resource. This gives you a chance to see

header values ahead of time before retrieving the content of the resource. You must be logged in to the account that owns the

EmbeddedServiceConfigDeveloperName you are querying. This resource is available in REST API version 45.0 and later.

Syntax

URI

/services/data/vXX.X/support/embeddedservice/configuration/embeddedServiceConfigDeveloperName

238

Return Headers for Embedded Service ConfigurationReference

Formats

JSON

HTTP method

HEAD

Authentication

Authorization: Bearer token

Request parameters

None

Invocable Actions

Represents standard and custom invocable actions. 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 company’s needs.

IN THIS SECTION:

Get Invocable Actions

Gets standard and custom invocable action URIs from Salesforce. This resource is available in REST API version 32.0 and later.

Return HTTP Headers for Invocable Actions

Returns only the headers that are returned by sending a GET request to the invocable actions resource. This gives you a chance to

see returned header values of the GET request before retrieving the content. This resource is available in REST API version 32.0 and

later.

SEE ALSO:

Apex Developer Guide : InvocableMethod Annotation

Get Invocable Actions

Gets standard and custom invocable action URIs from Salesforce. This resource is available in REST API version 32.0 and later.

Example

URI

/services/data/vXX.X/actions

Formats

JSON, XML

HTTP Methods

GET

239

Invocable ActionsReference

Authentication

Authorization: Bearer token

Request parameters

None required

Example

Example Request

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/actions -H "Authorization:

Bearer token"

Example Response Body

{

"standard" : "/services/data/v61.0/actions/standard",

"custom" : "/services/data/v61.0/actions/custom"

}

Return HTTP Headers for Invocable Actions

Returns only the headers that are returned by sending a GET request to the invocable actions resource. This gives you a chance to see

returned header values of the GET request before retrieving the content. This resource is available in REST API version 32.0 and later.

URI

/services/data/vXX.X/actions

Formats

JSON, XML

HTTP Methods

HEAD

Authentication

Authorization: Bearer token

Request parameters

None required

240

Return HTTP Headers for Invocable ActionsReference

Example

Example Request

curl -X HEAD --head https://MyDomainName.my.salesforce.com/services/data/v61.0/actions -H

"Authorization: Bearer token"

Example Response Body

HTTP/1.1 200 OK

Date: Mon, 21 Nov 2022 22:56:26 GMT

Invocable Actions Custom

Represents custom invocable actions that can be statically invoked. You can also get basic information for each type of action.

IN THIS SECTION:

Get Custom Invocable Actions

Gets the list of all custom invocable actions. Some actions require special access. This resource is available in REST API version 32.0

and later.

Return HTTP Headers for Custom Invocable Actions

Returns only the headers that are returned by sending a GET request to the custom invocable actions resource. This gives you a

chance to see returned header values of the GET request before retrieving the content. This resource is available in REST API version

32.0 and later.

SEE ALSO:

Apex Developer Guide : InvocableMethod Annotation

Get Custom Invocable Actions

Gets the list of all custom invocable actions. Some actions require special access. This resource is available in REST API version 32.0 and

later.

Sending email with the emailAlert action counts against your daily email limit for workflows. For more information, see Daily

Allocations for Email Alerts in Salesforce Help.

When invoking an Apex action using the POST method and supplying the inputs in the request, only the following primitive types are

supported as inputs:

•

Blob

•

Boolean

•

Date

•

Datetime

•

Decimal

•

Double

•

Integer

•

Long

241

Invocable Actions CustomReference

•

String

•

Time

Describe and invoke for an Apex action respect the profile access for the Apex class. If you don’t have access, an error is issued.

If you add an Apex action to a flow, and then remove the Invocable Method annotation from the Apex class, a runtime error in the flow

occurs.

When a flow user invokes an autolaunched flow, the active flow version runs. If there’s no active version, the latest version runs. When

a flow admin invokes a flow, the latest version always runs.

If any of these elements are used in a flow, packageable components that reference the elements aren’t automatically included in the

package.

•

Apex action

•

Email alerts

•

Post to Chatter core action

•

Quick Action core action

•

Send Email core action

•

Submit for Approval core action

For example, if you use an email alert, manually add the email template that’s used by that email alert. To deploy the package successfully,

manually add those referenced components to the package.

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

Syntax

URI

/services/data/vXX.X/actions/custom

Formats

JSON, XML

HTTP Methods

\ GET

Authentication

Authorization: Bearer token

Request parameters

None required

242

Get Custom Invocable ActionsReference

Example

Example Request

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/actions/custom -H

"Authorization: Bearer token"

Example Response Body

{

"quickAction" : "/services/data/v61.0/actions/custom/quickAction",

"apex" : "/services/data/v61.0/actions/custom/apex",

"emailAlert" : "/services/data/v61.0/actions/custom/emailAlert",

"flow" : "/services/data/v61.0/actions/custom/flow",

"sendNotification" : "/services/data/v61.0/actions/custom/sendNotification",

"generatePromptResponse" :

"/services/data/v60.0/actions/custom/generatePromptResponse"

}

Return HTTP Headers for Custom Invocable Actions

Returns only the headers that are returned by sending a GET request to the custom invocable actions resource. This gives you a chance

to see returned header values of the GET request before retrieving the content. This resource is available in REST API version 32.0 and

later.

URI

/services/data/vXX.X/actions/custom

Formats

JSON, XML

HTTP Methods

HEAD

Authentication

Authorization: Bearer token

Request parameters

None required

243

Return HTTP Headers for Custom Invocable ActionsReference

Example

Example Request

curl -X HEAD --head

https://MyDomainName.my.salesforce.com/services/data/v61.0/actions/custom -H "Authorization:

Bearer token"

Example Response Body

HTTP/1.1 200 OK

Date: Mon, 21 Nov 2022 22:56:26 GMT

Invocable Actions Standard

Represents standard invocable actions that can be statically invoked. You can also get basic information for each type of action.

IN THIS SECTION:

Get Standard Invocable Actions

Gets the list of standard invocable actions that are provided by Salesforce. Some actions require special access. This resource is

available in REST API version 32.0 and later.

Return HTTP Headers for Standard Invocable Actions

Returns only the headers that are returned by sending a GET request to the standard invocable actions resource. This gives you a

chance to see returned header values of the GET request before retrieving the content. This resource is available in REST API version

32.0 and later.

SEE ALSO:

Apex Developer Guide : InvocableMethod Annotation

Get Standard Invocable Actions

Gets the list of standard invocable actions that are provided by Salesforce. Some actions require special access. This resource is available

in REST API version 32.0 and later.

For Salesforce Omnichannel Inventory and Salesforce Order Management, you can also call the corresponding Connect REST API endpoints

or Apex ConnectApi methods. For more information, see Salesforce Omnichannel Inventory Resources and Salesforce Order Management

Resources in the Connect REST API Developer Guide, and ConnectApi Namespace in the Apex Reference Guide.

The Post to Chatter action supports the following features using a special format in the body post. For example, the string Hi

@[005000000000001], check out #[some_topic] is stored appropriately as Hi @Joe, check out

#some_topic where “@Joe” and “#some_topic” are links to the user and topic, respectively.

•

@mentions using @[<id>]

•

Topic links using #[<topicString>]

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

244

Invocable Actions StandardReference

Syntax

URI

/services/data/vXX.X/actions/standard

Formats

JSON, XML

HTTP Methods

GET

Authentication

Authorization: Bearer token

Request parameters

None required

Example

Example Request

curl https://MyDomainName.my.salesforce.com/services/data/v61.0/actions/standard -H

"Authorization: Bearer token"

Example Response Body

{

"actions" : [ {

"label" : "Post to Chatter",

"name" : "chatterPost",

"type" : "CHATTERPOST",

"url" : "/services/data/v61.0/actions/standard/chatterPost"

}, {

"label" : "Enable Folder Support for a Content Workspace (Library)",

"name" : "contentWorkspaceEnableFolders",

"type" : "CONTENTWORKSPACE_ENABLE_FOLDERS",

"url" : "/services/data/v61.0/actions/standard/contentWorkspaceEnableFolders"

}, {

"label" : "Send Email",

"name" : "emailSimple",

"type" : "EMAILSIMPLE",

"url" : "/services/data/v61.0/actions/standard/emailSimple"

}, {

"label" : "Submit for Approval",

"name" : "submit",

"type" : "SUBMITAPPROVAL",

245

Get Standard Invocable ActionsReference

"url" : "/services/data/v61.0/actions/standard/submit"

}, {

"label" : "Deactivate Session-Based Permission Set",

"name" : "deactivateSessionPermSet",

"type" : "DEACTIVATE_SESSION_PERM_SET",

"url" : "/services/data/v61.0/actions/standard/deactivateSessionPermSet"

}, {

"label" : "Activate Session-Based Permission Set",

"name" : "activateSessionPermSet",

"type" : "ACTIVATE_SESSION_PERM_SET",

"url" : "/services/data/v61.0/actions/standard/activateSessionPermSet"

}, {

"label" : "Choose Price Book",

"name" : "choosePricebook",

"type" : "CHOOSE_PRICEBOOK",

"url" : "/services/data/v61.0/actions/standard/choosePricebook"

}, {

"label" : "Routing Address Verification",

"name" : "routingAddressVerification",

"type" : "ROUTING_ADDRESS_VERIFICATION",

"url" : "/services/data/v61.0/actions/standard/routingAddressVerification"

}, {

"label" : "Create Customer Contact Request",

"name" : "contactRequestAction",

"type" : "CONTACT_REQUEST_ACTION",

"url" : "/services/data/v61.0/actions/standard/contactRequestAction"

}, {

"label" : "Publish Managed Content Release",

"name" : "managedContentReleasePublish",

"type" : "MANAGED_CONTENT_RELEASE_PUBLISH",

"url" : "/services/data/v61.0/actions/standard/managedContentReleasePublish"

} ]

}

Return HTTP Headers for Standard Invocable Actions

Returns only the headers that are returned by sending a GET request to the standard invocable actions resource. This gives you a chance

to see returned header values of the GET request before retrieving the content. This resource is available in REST API version 32.0 and

later.

Syntax

URI

/services/data/vXX.X/actions/standard

Formats

JSON, XML

246

Return HTTP Headers for Standard Invocable ActionsReference

HTTP Methods

HEAD

Authentication

Authorization: Bearer token

Request parameters

None required

Example

Example Request

curl -X HEAD --head

https://MyDomainName.my.salesforce.com/services/data/v61.0/actions/standard -H

"Authorization: Bearer token"

Example Response Body

HTTP/1.1 200 OK

Date: Mon, 21 Nov 2022 22:56:26 GMT

List View Basic Information

Returns basic information for a specific list view, including the label, API name, and ID. This resource is available in REST API version 32.0

and later.

URI

/services/data/vXX.X/sobjects/sObject/listviews/listViewID

Formats

JSON, XML

HTTP Methods

GET

Authentication

Authorization: Bearer token

Parameters

None

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcBeMAK

-H "Authorization: Bearer token"

247

List View Basic InformationReference

Example Response Body

{

"describeUrl" :

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcBeMAK/describe",

"developerName" : "NewThisWeek",

"id" : "00BD0000005WcBeMAK",

"label" : "New This Week",

"resultsUrl" :

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcBeMAK/results",

"soqlCompatible" : true,

"url" : "/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcBeMAK"

}

List View Describe

Returns detailed information about a list view, including the ID, the columns, and the SOQL query.

This resource is available in REST API version 32.0 and later.

URI

/services/data/vXX.X/sobjects/sObject/listviews/queryLocator/describe

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

None

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcBeMAK/describe

-H "Authorization: Bearer token"

Example Response Body

{

"columns" : [ {

"ascendingLabel" : "Z-A",

"descendingLabel" : "A-Z",

"fieldNameOrPath" : "Name",

"hidden" : false,

"label" : "Account Name",

"selectListItem" : "Name",

"sortDirection" : "ascending",

"sortIndex" : 0,

248

List View DescribeReference

"sortable" : true,

"type" : "string"

}, {

"ascendingLabel" : "Z-A",

"descendingLabel" : "A-Z",

"fieldNameOrPath" : "Site",

"hidden" : false,

"label" : "Account Site",

"selectListItem" : "Site",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : true,

"type" : "string"

}, {

"ascendingLabel" : "Z-A",

"descendingLabel" : "A-Z",

"fieldNameOrPath" : "BillingState",

"hidden" : false,

"label" : "Billing State/Province",

"selectListItem" : "BillingState",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : true,

"type" : "string"

}, {

"ascendingLabel" : "9-0",

"descendingLabel" : "0-9",

"fieldNameOrPath" : "Phone",

"hidden" : false,

"label" : "Phone",

"selectListItem" : "Phone",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : true,

"type" : "phone"

}, {

"ascendingLabel" : "Low to High",

"descendingLabel" : "High to Low",

"fieldNameOrPath" : "Type",

"hidden" : false,

"label" : "Type",

"selectListItem" : "toLabel(Type)",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : true,

"type" : "picklist"

}, {

"ascendingLabel" : "Z-A",

"descendingLabel" : "A-Z",

"fieldNameOrPath" : "Owner.Alias",

"hidden" : false,

"label" : "Account Owner Alias",

"selectListItem" : "Owner.Alias",

"sortDirection" : null,

249

List View DescribeReference

"sortIndex" : null,

"sortable" : true,

"type" : "string"

}, {

"ascendingLabel" : null,

"descendingLabel" : null,

"fieldNameOrPath" : "Id",

"hidden" : true,

"label" : "Account ID",

"selectListItem" : "Id",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : false,

"type" : "id"

}, {

"ascendingLabel" : null,

"descendingLabel" : null,

"fieldNameOrPath" : "CreatedDate",

"hidden" : true,

"label" : "Created Date",

"selectListItem" : "CreatedDate",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : false,

"type" : "datetime"

}, {

"ascendingLabel" : null,

"descendingLabel" : null,

"fieldNameOrPath" : "LastModifiedDate",

"hidden" : true,

"label" : "Last Modified Date",

"selectListItem" : "LastModifiedDate",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : false,

"type" : "datetime"

}, {

"ascendingLabel" : null,

"descendingLabel" : null,

"fieldNameOrPath" : "SystemModstamp",

"hidden" : true,

"label" : "System Modstamp",

"selectListItem" : "SystemModstamp",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : false,

"type" : "datetime"

} ],

"id" : "00BD0000005WcBe",

"orderBy" : [ {

"fieldNameOrPath" : "Name",

"nullsPosition" : "first",

"sortDirection" : "ascending"

}, {

250

List View DescribeReference

"fieldNameOrPath" : "Id",

"nullsPosition" : "first",

"sortDirection" : "ascending"

} ],

"query" : "SELECT name, site, billingstate, phone, tolabel(type), owner.alias, id,

createddate, lastmodifieddate, systemmodstamp FROM Account WHERE CreatedDate = THIS_WEEK

ORDER BY Name ASC NULLS FIRST, Id ASC NULLS FIRST",

"scope" : null,

"sobjectType" : "Account",

"whereCondition" : {

"field" : "CreatedDate",

"operator" : "equals",

"values" : [ "THIS_WEEK" ]

}

List View Results

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.

Syntax

URI

/services/data/vXX.X/sobjects/sObject/listviews/listViewID/results

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

DescriptionParameter

The maximum number of records to return, between 1-2000.

The default value is 25.

limit

The first record to return. Use this parameter to paginate the

results. The default value is 1.

offset

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcCNMA0/results

-H "Authorization: Bearer token"

251

List View ResultsReference

Example Response Body

{

"columns" : [ {

"ascendingLabel" : "Z-A",

"descendingLabel" : "A-Z",

"fieldNameOrPath" : "Name",

"hidden" : false,

"label" : "Account Name",

"selectListItem" : "Name",

"sortDirection" : "ascending",

"sortIndex" : 0,

"sortable" : true,

"type" : "string"

}, {

"ascendingLabel" : "Z-A",

"descendingLabel" : "A-Z",

"fieldNameOrPath" : "Site",

"hidden" : false,

"label" : "Account Site",

"selectListItem" : "Site",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : true,

"type" : "string"

}, {

"ascendingLabel" : "Z-A",

"descendingLabel" : "A-Z",

"fieldNameOrPath" : "BillingState",

"hidden" : false,

"label" : "Billing State/Province",

"selectListItem" : "BillingState",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : true,

"type" : "string"

}, {

"ascendingLabel" : "9-0",

"descendingLabel" : "0-9",

"fieldNameOrPath" : "Phone",

"hidden" : false,

"label" : "Phone",

"selectListItem" : "Phone",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : true,

"type" : "phone"

}, {

"ascendingLabel" : "Low to High",

"descendingLabel" : "High to Low",

"fieldNameOrPath" : "Type",

"hidden" : false,

"label" : "Type",

"selectListItem" : "toLabel(Type)",

252

List View ResultsReference

"sortDirection" : null,

"sortIndex" : null,

"sortable" : true,

"type" : "picklist"

}, {

"ascendingLabel" : "Z-A",

"descendingLabel" : "A-Z",

"fieldNameOrPath" : "Owner.Alias",

"hidden" : false,

"label" : "Account Owner Alias",

"selectListItem" : "Owner.Alias",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : true,

"type" : "string"

}, {

"ascendingLabel" : null,

"descendingLabel" : null,

"fieldNameOrPath" : "Id",

"hidden" : true,

"label" : "Account ID",

"selectListItem" : "Id",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : false,

"type" : "id"

}, {

"ascendingLabel" : null,

"descendingLabel" : null,

"fieldNameOrPath" : "CreatedDate",

"hidden" : true,

"label" : "Created Date",

"selectListItem" : "CreatedDate",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : false,

"type" : "datetime"

}, {

"ascendingLabel" : null,

"descendingLabel" : null,

"fieldNameOrPath" : "LastModifiedDate",

"hidden" : true,

"label" : "Last Modified Date",

"selectListItem" : "LastModifiedDate",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : false,

"type" : "datetime"

}, {

"ascendingLabel" : null,

"descendingLabel" : null,

"fieldNameOrPath" : "SystemModstamp",

"hidden" : true,

"label" : "System Modstamp",

253

List View ResultsReference

"selectListItem" : "SystemModstamp",

"sortDirection" : null,

"sortIndex" : null,

"sortable" : false,

"type" : "datetime"

} ],

"developerName" : "MyAccounts",

"done" : true,

"id" : "00BD0000005WcCN",

"label" : "My Accounts",

"records" : [ {

"columns" : [ {

"fieldNameOrPath" : "Name",

"value" : "Burlington Textiles Corp of America"

}, {

"fieldNameOrPath" : "Site",

"value" : null

}, {

"fieldNameOrPath" : "BillingState",

"value" : "NC"

}, {

"fieldNameOrPath" : "Phone",

"value" : "(336) 222-7000"

}, {

"fieldNameOrPath" : "Type",

"value" : "Customer - Direct"

}, {

"fieldNameOrPath" : "Owner.Alias",

"value" : "TUser"

}, {

"fieldNameOrPath" : "Id",

"value" : "001D000000JliSTIAZ"

}, {

"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" : "Dickenson plc"

}, {

"fieldNameOrPath" : "Site",

"value" : null

}, {

"fieldNameOrPath" : "BillingState",

"value" : "KS"

}, {

"fieldNameOrPath" : "Phone",

254

List View ResultsReference

"value" : "(785) 241-6200"

}, {

"fieldNameOrPath" : "Type",

"value" : "Customer - Channel"

}, {

"fieldNameOrPath" : "Owner.Alias",

"value" : "TUser"

}, {

"fieldNameOrPath" : "Id",

"value" : "001D000000JliSVIAZ"

}, {

"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" : "Edge Communications"

}, {

"fieldNameOrPath" : "Site",

"value" : null

}, {

"fieldNameOrPath" : "BillingState",

"value" : "TX"

}, {

"fieldNameOrPath" : "Phone",

"value" : "(512) 757-6000"

}, {

"fieldNameOrPath" : "Type",

"value" : "Customer - Direct"

}, {

"fieldNameOrPath" : "Owner.Alias",

"value" : "TUser"

}, {

"fieldNameOrPath" : "Id",

"value" : "001D000000JliSSIAZ"

}, {

"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" : [ {

255

List View ResultsReference

"fieldNameOrPath" : "Name",

"value" : "Express Logistics and Transport"

}, {

"fieldNameOrPath" : "Site",

"value" : null

}, {

"fieldNameOrPath" : "BillingState",

"value" : "OR"

}, {

"fieldNameOrPath" : "Phone",

"value" : "(503) 421-7800"

}, {

"fieldNameOrPath" : "Type",

"value" : "Customer - Channel"

}, {

"fieldNameOrPath" : "Owner.Alias",

"value" : "TUser"

}, {

"fieldNameOrPath" : "Id",

"value" : "001D000000JliSXIAZ"

}, {

"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" : "GenePoint"

}, {

"fieldNameOrPath" : "Site",

"value" : null

}, {

"fieldNameOrPath" : "BillingState",

"value" : "CA"

}, {

"fieldNameOrPath" : "Phone",

"value" : "(650) 867-3450"

}, {

"fieldNameOrPath" : "Type",

"value" : "Customer - Channel"

}, {

"fieldNameOrPath" : "Owner.Alias",

"value" : "TUser"

}, {

"fieldNameOrPath" : "Id",

"value" : "001D000000JliSPIAZ"

}, {

"fieldNameOrPath" : "CreatedDate",

256

List View ResultsReference

"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" : "Grand Hotels and Resorts Ltd"

}, {

"fieldNameOrPath" : "Site",

"value" : null

}, {

"fieldNameOrPath" : "BillingState",

"value" : "IL"

}, {

"fieldNameOrPath" : "Phone",

"value" : "(312) 596-1000"

}, {

"fieldNameOrPath" : "Type",

"value" : "Customer - Direct"

}, {

"fieldNameOrPath" : "Owner.Alias",

"value" : "TUser"

}, {

"fieldNameOrPath" : "Id",

"value" : "001D000000JliSWIAZ"

}, {

"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" : "Pyramid Construction Inc."

}, {

"fieldNameOrPath" : "Site",

"value" : null

}, {

"fieldNameOrPath" : "BillingState",

"value" : null

}, {

"fieldNameOrPath" : "Phone",

"value" : "(014) 427-4427"

}, {

257

List View ResultsReference

"fieldNameOrPath" : "Type",

"value" : "Customer - Channel"

}, {

"fieldNameOrPath" : "Owner.Alias",

"value" : "TUser"

}, {

"fieldNameOrPath" : "Id",

"value" : "001D000000JliSUIAZ"

}, {

"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" : "sForce"

}, {

"fieldNameOrPath" : "Site",

"value" : null

}, {

"fieldNameOrPath" : "BillingState",

"value" : "CA"

}, {

"fieldNameOrPath" : "Phone",

"value" : "(415) 901-7000"

}, {

"fieldNameOrPath" : "Type",

"value" : null

}, {

"fieldNameOrPath" : "Owner.Alias",

"value" : "TUser"

}, {

"fieldNameOrPath" : "Id",

"value" : "001D000000JliSaIAJ"

}, {

"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" : "United Oil and Gas Corp."

258

List View ResultsReference

}, {

"fieldNameOrPath" : "Site",

"value" : null

}, {

"fieldNameOrPath" : "BillingState",

"value" : "NY"

}, {

"fieldNameOrPath" : "Phone",

"value" : "(212) 842-5500"

}, {

"fieldNameOrPath" : "Type",

"value" : "Customer - Direct"

}, {

"fieldNameOrPath" : "Owner.Alias",

"value" : "TUser"

}, {

"fieldNameOrPath" : "Id",

"value" : "001D000000JliSZIAZ"

}, {

"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" : "United Oil and Gas, Singapore"

}, {

"fieldNameOrPath" : "Site",

"value" : null

}, {

"fieldNameOrPath" : "BillingState",

"value" : "Singapore"

}, {

"fieldNameOrPath" : "Phone",

"value" : "(650) 450-8810"

}, {

"fieldNameOrPath" : "Type",

"value" : "Customer - Direct"

}, {

"fieldNameOrPath" : "Owner.Alias",

"value" : "TUser"

}, {

"fieldNameOrPath" : "Id",

"value" : "001D000000JliSRIAZ"

}, {

"fieldNameOrPath" : "CreatedDate",

"value" : "Fri Aug 01 21:15:46 GMT 2014"

}, {

259

List View ResultsReference

"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" : "United Oil and Gas, UK"

}, {

"fieldNameOrPath" : "Site",

"value" : null

}, {

"fieldNameOrPath" : "BillingState",

"value" : "UK"

}, {

"fieldNameOrPath" : "Phone",

"value" : "+44 191 4956203"

}, {

"fieldNameOrPath" : "Type",

"value" : "Customer - Direct"

}, {

"fieldNameOrPath" : "Owner.Alias",

"value" : "TUser"

}, {

"fieldNameOrPath" : "Id",

"value" : "001D000000JliSQIAZ"

}, {

"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"

260

List View ResultsReference

}, {

"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 for an Object

Returns the list of list views for the specified sObject, including the ID and other basic information about each list view. This resource is

available in REST API version 32.0 and later.

URI

/services/data/vXX.X/sobjects/sObject/listviews

Formats

JSON, XML

HTTP Methods

GET

Authentication

Authorization: Bearer token

Parameters

None

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/sobjects/Account/listviews

-H "Authorization: Bearer token"

Example Response Body

{

"done" : true,

"listviews" : [ {

"describeUrl" :

261

List Views for an ObjectReference

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcBeMAK/describe",

"developerName" : "NewThisWeek",

"id" : "00BD0000005WcBeMAK",

"label" : "New This Week",

"resultsUrl" :

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcBeMAK/results",

"soqlCompatible" : true,

"url" : "/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcBeMAK"

}, {

"describeUrl" :

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcBpMAK/describe",

"developerName" : "NewLastWeek",

"id" : "00BD0000005WcBpMAK",

"label" : "New Last Week",

"resultsUrl" :

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcBpMAK/results",

"soqlCompatible" : true,

"url" : "/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcBpMAK"

}, {

"describeUrl" :

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcC6MAK/describe",

"developerName" : "PlatinumandGoldSLACustomers",

"id" : "00BD0000005WcC6MAK",

"label" : "Platinum and Gold SLA Customers",

"resultsUrl" :

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcC6MAK/results",

"soqlCompatible" : true,

"url" : "/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcC6MAK"

}, {

"describeUrl" :

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcCEMA0/describe",

"developerName" : "RecentlyViewedAccounts",

"id" : "00BD0000005WcCEMA0",

"label" : "Recently Viewed Accounts",

"resultsUrl" :

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcCEMA0/results",

"soqlCompatible" : true,

"url" : "/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcCEMA0"

}, {

"describeUrl" :

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcCFMA0/describe",

"developerName" : "AllAccounts",

"id" : "00BD0000005WcCFMA0",

"label" : "All Accounts",

"resultsUrl" :

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcCFMA0/results",

"soqlCompatible" : true,

"url" : "/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcCFMA0"

}, {

"describeUrl" :

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcCNMA0/describe",

"developerName" : "MyAccounts",

"id" : "00BD0000005WcCNMA0",

"label" : "My Accounts",

262

List Views for an ObjectReference

"resultsUrl" :

"/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcCNMA0/results",

"soqlCompatible" : true,

"url" : "/services/data/v61.0/sobjects/Account/listviews/00BD0000005WcCNMA0"

} ],

"nextRecordsUrl" : null,

"size" : 6,

"sobjectType" : "Account"

}

Support Knowledge with REST API

Knowledge Support REST APIs allow both authorized and guest users to retrieve the user’s visible data categories and their associated

articles. This resource is available in REST API version 38.0 and later.

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.

Syntax

URI

/services/data/vXX.X/support

Method

GET

Formats

JSON, XML

Authentication

Authorization: Bearer token

Example

Example Response Body

{

"dataCategoryGroups" : "/services/data/vXX.X/support/dataCategoryGroups",

"knowledgeArticles" : "/services/data/vXX.X/support/knowledgeArticles"

}

IN THIS SECTION:

Data Category Groups

Get data category groups that are visible to the current user. This resource is available in REST API version 38.0 and later.

Data Category Detail

Gets data category details and the child categories by a given category. This resource can be used in API version 38.0 and later.

263

Support Knowledge with REST APIReference

Articles List

Get a page of online articles for the given language and category through either search or query. This resource is available in REST

API version 38.0 and later.

Articles Details

Gets all online article fields, accessible to the user. This resource is available with article IDs in REST API version 38.0 and later, and

this resource is available with article URL names in version 44.0 and later.

Data Category Groups

Get data category groups that are visible to the current user. This resource is available in REST API version 38.0 and later.

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 user’s 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.

Syntax

URI

/services/data/vXX.X/support/dataCategoryGroups

Method

GET

Formats

JSON, XML

Authentication

Authorization: Bearer token

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.

Input:

string sObjectName: Required. KnowledgeArticleVersion only.

boolean topCategoriesOnly: Optional. Defaults to true

•

True returns only the top level categories.

•

False returns the entire tree.

Note: All the input parameters are case-sensitive.

Output:

A list of the active data category groups that are visible to the current user in the site context. Returns id, name, label, and their top

level categories or the entire data category group tree that are visible to the current user. The labels must be translated to the given

language if they are available.

•

Data Category Group List

264

Data Category GroupsReference

This payload lists the active root Data Category Groups that can be used in other requests to return the data categories and

articles related to it.

{

"categoryGroups": [ Data Category Group, ....],

}

Note: Returns only the active groups that are associated to the given entity (by sObjectName). Only

KnowledgeArticleVersion is supported.

•

Data Category Group

This represents an individual data category group, and its root category.

{

"name": String, // the unique name of the category group

"label": String, // returns the translated version if it is available

"objectUsage" : String, // currently only "KnowledgeArticleVersion" is available.

"topCategories": [ Data Category Summary, ....]

}

•

Data Category Summary

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

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/support/dataCategoryGroups?sObjectName=KnowledgeArticleVersion

-H "Authorization: Bearer token"

Example Response Body

{

"categoryGroups" : [ {

"label" : "Doc",

"name" : "Doc",

"objectUsage" : "KnowledgeArticleVersion",

"topCategories" : [ {

"childCategories" : null,

"label" : "All",

265

Data Category GroupsReference

"name" : "All",

"url" :

"/services/data/v61.0/support/dataCategoryGroups/Doc/dataCategories/All?sObjectName=KnowledgeArticleVersion"

} ]

}, {

"label" : "Manual",

"name" : "Manual",

"objectUsage" : "KnowledgeArticleVersion",

"topCategories" : [ {

"childCategories" : null,

"label" : "All",

"name" : "All",

"url" :

"/services/data/v61.0/support/dataCategoryGroups/Manual/dataCategories/All?sObjectName=KnowledgeArticleVersion"

} ]

}

Data Category Detail

Gets data category details and the child categories by a given category. This resource can be used in API version 38.0 and later.

Salesforce Knowledge must be enabled in your organization. Use the language code format used in Which Languages Does Salesforce

Support?.

Syntax

URI

/services/data/vXX.X/support/dataCategoryGroups/group/dataCategories/category

Method

GET

Formats

JSON, XML

Authentication

Authorization: Bearer token

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.

Input:

string sObjectName: Required. KnowledgeArticleVersion only.

Output:

Details of the category and a list of child categories (name, label, etc.).

•

Data Category Detail

266

Data Category DetailReference

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 isn’t visible to the current user the return is empty.

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/support/dataCategoryGroups/Doc/dataCategories/All?sObjectName=KnowledgeArticleVersion

-H "Authorization: Bearer token"

Example Response Body

{

"childCategories" : [ {

"childCategories" : null,

"label" : "Help",

"name" : "Help",

"url" :

"/services/data/v61.0/support/dataCategoryGroups/Doc/dataCategories/Help?sObjectName=KnowledgeArticleVersion"

}, {

"childCategories" : null,

"label" : "QA",

"name" : "QA",

"url" :

"/services/data/v61.0/support/dataCategoryGroups/Doc/dataCategories/QA?sObjectName=KnowledgeArticleVersion"

} ],

"label" : "All",

"name" : "All",

"url" :

"/services/data/v61.0/support/dataCategoryGroups/Doc/dataCategories/All?sObjectName=KnowledgeArticleVersion"

}

Articles List

Get a page of online articles for the given language and category through either search or query. This resource is available in REST API

version 38.0 and later.

267

Articles ListReference

Syntax

URI

/services/data/vXX.X/support/knowledgeArticles

Method

GET

Formats

JSON, XML

Authentication

Authorization: Bearer token

HTTP headers

Accept: Optional. Can be either application/json or application/xml.

Accept-language: Required. The article must be an active language in the user’s organization

•

If the language code isn’t 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.

The characters ? and * are used for wildcard searches. The characters (, ), and " are used for complex search terms. See

https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_sosl_find.htm.

string channel: Optional, defaults to user’s 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. There is a limit of three data category conditions, otherwise you get

INVALID_FILTER_VALUE.

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.

Output:

A page of online articles in the given language and category visible to the current user.

•

Article Page

268

Articles ListReference

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.

Note: if the user input parameter has the default value, the API does not show this parameter in either

currentPageUrl or nextPageUrl.

•

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,

"articleType": String, // apiName of the article type, available in API v44.0

and later

"title": String,

"urlName": String, // available in API v44.0 and later

"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

269

Articles ListReference

language specified

"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

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.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

Example Response Body

{

"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/v61.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/v61.0/support/knowledgeArticles/kA0xx000000000LCAQ",

270

Articles ListReference

"viewCount" : 0,

"viewScore" : 0.0

}, {

"articleNumber" : "000001012",

"categoryGroups" : [ ],

"downVoteCount" : 0,

"id" : "kA0xx000000006GCAQ",

"lastPublishedDate" : "2016-06-21T21:10:48Z",

"summary" : null,

"title" : "Test Draft 2",

"upVoteCount" : 0,

"url" : "/services/data/v61.0/support/knowledgeArticles/kA0xx000000006GCAQ",

"viewCount" : 0,

"viewScore" : 0.0

} ],

"currentPageUrl" :

"/services/data/v61.0/support/knowledgeArticles?channel=Pkb&pageSize=3&sort=ViewScore",

"nextPageUrl" : null,

"pageNumber" : 1

}

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?.

Valid channel Values

•

When using the options string channel, where the matching articles are visible, the following values are valid.

–

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

•

If channel isn’t 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.

271

Articles ListReference

Articles Details

Gets all online article fields, accessible to the user. This resource is available with article IDs in REST API version 38.0 and later, and this

resource is available with article URL names in version 44.0 and later.

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

Valid channel Values

•

When using the options string channel, where the matching articles are visible, the following values are valid.

–

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

•

If channel isn’t 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.

Syntax

Method

GET

272

Articles DetailsReference

Formats

JSON, XML

Authentication

Authorization: Bearer token

Endpoint

/services/data/vXX.X/support/knowledgeArticles/articleId_or_articleUrlName

HTTP headers

Accept: Optional. Can be either application/json or application/xml.

Accept-language: Required. The article must be an active language in the user’s organization

•

If the language code isn’t 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 user’s 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.

boolean isUrlName: Optional, defaults to false. If true, indicates that the last portion of the endpoint is a URL name instead of an

article ID. Available in API v44.0 and later

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,

"articleType": String, // apiName of the article type, available in API

v44.0 and later

"title": String,

"urlName": String, // available in API v44.0 and later

"summary": String,

"url": URL,

"versionNumber": Int,

"createdDate": Date, // in ISO8601 format

"createdBy": User Summary on page 274,

"lastModifiedDate": Date, // in ISO8601 format

"lastModifiedBy": User Summary on page 274,

"lastPublishedDate": Date, // in ISO8601 format

"layoutItems": [ Article Field, ... ], // standard and custom fields visible

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

273

Articles DetailsReference

"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/vXX.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 administrator’s layout.

{

"type": Enum, // see the Notes

"name": String, // In API v43.0 and earlier, the developer name. In

API v44.0 and later, the API name.

"label": String, // label

"value": String,

}

Example

Example Request

curl

https://MyDomainName.my.salesforce.com/services/data/v61.0/support/knowledgeArticles/kA0xx000000000LCAQ

HTTP Headers:

274

Articles DetailsReference

Content-Type: application/json; charset=UTF-8

Accept: application/json

Accept-Language: en-US

Example Response Body

{

"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/v61.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/v61.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",

275

Articles DetailsReference

"value" : "en_US"

}, {

"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,