REST API Developer Guide

213229

REST API Developer Guide

Version 56.0, Spring

23
@salesforcedocs

Last updated: February 3, 2023

© Copyright 2000-2023 Salesforce, Inc. All rights reserved. Salesforce is a registered trademark of Salesforce, Inc., as are other

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

CONTENTS

Chapter 1: Introduction to REST API........................................1 What Is REST API?......................................................2 API Compatible Editions and Development Environments...........................2 REST Resources and Requests.............................................3 REST API Architecture...................................................4 Authorization Through Connected Apps and OAuth 2.0............................6 Headers............................................................6 Assignment Rule Header.............................................7 Call Options Header................................................8 Compression Headers..............................................8 Conditional Request Headers..........................................9 Duplicate Rule Header..............................................11 Limit Info Header..................................................11 Package Version Header............................................12 Query Options Header..............................................12 Warning Header..................................................13 Send REST Requests with cURL............................................13 Configure Salesforce CORS Allowlist.........................................14 Valid Date and DateTime Formats..........................................15 Status Codes and Error Responses.........................................16 API End-of-Life.......................................................17 Chapter 2: Quick Start................................................18 Using cURL.........................................................19 Step One: Sign up for Salesforce Developer Edition...............................19 Step Two: Set Up Authentication...........................................20 Step Three: Walk Through the Sample Code...................................22 Using Other Tools....................................................26 Chapter 3: Examples................................................27 Getting Information About My Organization...................................28 List Available REST API Versions........................................28 List Org Limits....................................................29 List Available REST Resources.........................................33 Get a List of Objects................................................36 Get a List of Objects If Metadata Has Changed.............................37 Working with Object Metadata............................................37 Retrieve Metadata for an Object.......................................37 Get Field and Other Metadata for an Object...............................38 Get Object Metadata Changes........................................39 Working with Records..................................................40 Create a Record..................................................41 Update a Record..................................................41 Delete a Record..................................................43 Get Field Values from a Standard Object Record............................43 Get Field Values from an External Object Record by Using the Salesforce ID..........44 Get Field Values from an External Object Record by Using the External ID Standard Field..........................................................44 Retrieve a Record Using an External ID...................................45 Insert or Update (Upsert) a Record Using an External ID.......................45 Traverse Relationships with Friendly URLs.................................49 Get a List of Deleted Records Within a Given Timeframe.......................55 Get a List of Updated Records Within a Given Timeframe.......................56 Delete Lightning Experience Event Series.....................................56 Working with Searches and Queries........................................57 Execute a SOQL Query..............................................58 Execute a SOQL Query that Includes Deleted Items...........................59 Get Feedback on Query Performance (Beta)...............................60 Search for a String.................................................61 Get the Default Search Scope and Order..................................64 Get Search Result Layouts for Objects....................................65 View Relevant Items...............................................67 Get an Image from a Rich Text Area Field.....................................69 Insert or Update Blob Data..............................................70 Retrieve Blob Data....................................................76 Working with Recently Viewed Information....................................77 View Recently Viewed Records........................................77 Mark Records as Recently Viewed......................................78 Managing User Passwords..............................................78 Manage User Passwords............................................79 Working with Approval Processes and Process Rules.............................80 Get a List of All Approval Processes.....................................81 Submit a Record for Approval.........................................81 Approve a Record.................................................82 Reject a Record..................................................83 Bulk Approvals...................................................83 Get a List of Process Rules...........................................84 Get a Particular Process Rule.........................................85 Trigger Process Rules..............................................86 Using Event Monitoring.................................................86 Describe Event Monitoring Using REST...................................87 Query Event Monitoring Data with REST...................................88 Get Event Monitoring Content from a Record ..............................89

Contents

Download Large Event Log Files Using cURL with REST.........................90 Delete Event Monitoring Data.........................................90 Query or View Hourly Event Log Files.....................................91 Using Composite Resources.............................................93 Execute Dependent Requests in a Single API Call............................94 Update an Account, Create a Contact, and Link Them with a Junction Object.........96 Update a Record and Get Its Field Values in a Single Request...................98 Upsert an Account and Create a Contact.................................99 Create Nested Records.............................................100 Create Multiple Records............................................102 Using Composite Graphs...........................................103 Using a Composite Graph..........................................109 allOrNone Parameters in Composite and Collections Requests..................113 Chapter 4: Generating an OpenAPI 3.0 Document for sObjects REST API (Beta).....117 Chapter 5: Reference ...............................................122 Versions..........................................................131 Resources by Version..................................................131 Limits............................................................132 Describe Global.....................................................136 sObject Basic Information...............................................137 Retrieve Object Metadata Using sObject Basic Information.....................137 Create Records Using sObject Basic Information............................138 sObject Describe....................................................139 sObject Get Deleted..................................................140 sObject Get Updated..................................................142 sObject Named Layouts................................................143 sObject Rows.......................................................144 Get Records Using sObject Rows......................................144 Update Records Using sObject Rows...................................146 Delete Records Using sObject Rows....................................147 sObject Rows by External ID.............................................149 Get Records Using sObject Rows by External ID............................149 Create Records Using sObject Rows by External ID..........................150 Upsert Records Using sObject Rows by External ID..........................151 Delete Records Using sObject Rows by External ID..........................152 Return Headers Using sObject Rows by External ID..........................153 sObject Blob Retrieve..................................................153 sObject ApprovalLayouts...............................................154 Get Approval Layouts..............................................154 Return Headers for Approval Layouts...................................155 sObject Single Approval Process..........................................156 Get a Layout for a Single Approval Process on a Specified Object................156

Contents

Return Headers for a Single Approval Process on a Specified Object..............157 sObject CompactLayouts...............................................157 Get Compact Layouts Using sObject CompactLayouts........................158 Return Headers Using sObject CompactLayouts............................163 sObject Layouts.....................................................163 Get Layouts and Descriptions for a Specified Object..........................164 Return Layout Headers for a Specified Object..............................165 sObject Layouts for an Object With Multiple Record Types.........................166 Get Layouts and Descriptions for an Object With Multiple Record Types............166 Return Layout Headers for an Object With Multiple Record Types.................167 sObject Global Publisher Layouts..........................................167 Get Global Publisher Layouts and Descriptions.............................168 Return Headers for All Global Publisher Layouts............................169 sObject PlatformAction.................................................170 sObject Quick Actions.................................................170 Get sObject Quick Actions...........................................171 Return Headers Using sObject Quick Actions..............................171 sObject Specific Quick Actions............................................172 Retrieve Specific sObject Quick Actions..................................172 Create Records Using Specific sObject Quick Actions.........................173 Return Headers Using Specific sObject Quick Actions.........................174 sObject Quick Action Details.............................................174 Get sObject Quick Action Details.......................................175 Return Headers Using sObject Quick Action Details..........................175 sObject Quick Action Default Values........................................176 Get sObject Quick Action Default Values.................................176 Return Headers Using sObject Quick Action Default Values....................177 sObject Quick Action Default Values by ID....................................177 Get sObject Quick Action Default Values by ID.............................178 Return Headers Using sObject Quick Action Default Values by ID.................178 sObject Rich Text Image Retrieve..........................................179 sObject Relationships.................................................180 Get Records Using sObject Relationships.................................181 Update Records Using sObject Relationships..............................182 Delete Records Using sObject Relationships...............................183 sObjects Suggested Articles.............................................184 sObjects Suggested Articles by ID.........................................186 sObject User Password................................................187 Get User Password Expiration Status...................................188 Set User Password...............................................188 Reset User Password..............................................189 Return Headers Using sObject User Password.............................190

REST API Developer Guide

Version 56.0, Spring

23
@salesforcedocs

Last updated: February 3, 2023

© Copyright 2000-2023 Salesforce, Inc. All rights reserved. Salesforce is a registered trademark of Salesforce, Inc., as are other

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

CONTENTS

Chapter 1: Introduction to REST API........................................1 What Is REST API?......................................................2 API Compatible Editions and Development Environments...........................2 REST Resources and Requests.............................................3 REST API Architecture...................................................4 Authorization Through Connected Apps and OAuth 2.0............................6 Headers............................................................6 Assignment Rule Header.............................................7 Call Options Header................................................8 Compression Headers..............................................8 Conditional Request Headers..........................................9 Duplicate Rule Header..............................................11 Limit Info Header..................................................11 Package Version Header............................................12 Query Options Header..............................................12 Warning Header..................................................13 Send REST Requests with cURL............................................13 Configure Salesforce CORS Allowlist.........................................14 Valid Date and DateTime Formats..........................................15 Status Codes and Error Responses.........................................16 API End-of-Life.......................................................17 Chapter 2: Quick Start................................................18 Using cURL.........................................................19 Step One: Sign up for Salesforce Developer Edition...............................19 Step Two: Set Up Authentication...........................................20 Step Three: Walk Through the Sample Code...................................22 Using Other Tools....................................................26 Chapter 3: Examples................................................27 Getting Information About My Organization...................................28 List Available REST API Versions........................................28 List Org Limits....................................................29 List Available REST Resources.........................................33 Get a List of Objects................................................36 Get a List of Objects If Metadata Has Changed.............................37 Working with Object Metadata............................................37 Retrieve Metadata for an Object.......................................37 Get Field and Other Metadata for an Object...............................38 Get Object Metadata Changes........................................39 Working with Records..................................................40 Create a Record..................................................41 Update a Record..................................................41 Delete a Record..................................................43 Get Field Values from a Standard Object Record............................43 Get Field Values from an External Object Record by Using the Salesforce ID..........44 Get Field Values from an External Object Record by Using the External ID Standard Field..........................................................44 Retrieve a Record Using an External ID...................................45 Insert or Update (Upsert) a Record Using an External ID.......................45 Traverse Relationships with Friendly URLs.................................49 Get a List of Deleted Records Within a Given Timeframe.......................55 Get a List of Updated Records Within a Given Timeframe.......................56 Delete Lightning Experience Event Series.....................................56 Working with Searches and Queries........................................57 Execute a SOQL Query..............................................58 Execute a SOQL Query that Includes Deleted Items...........................59 Get Feedback on Query Performance (Beta)...............................60 Search for a String.................................................61 Get the Default Search Scope and Order..................................64 Get Search Result Layouts for Objects....................................65 View Relevant Items...............................................67 Get an Image from a Rich Text Area Field.....................................69 Insert or Update Blob Data..............................................70 Retrieve Blob Data....................................................76 Working with Recently Viewed Information....................................77 View Recently Viewed Records........................................77 Mark Records as Recently Viewed......................................78 Managing User Passwords..............................................78 Manage User Passwords............................................79 Working with Approval Processes and Process Rules.............................80 Get a List of All Approval Processes.....................................81 Submit a Record for Approval.........................................81 Approve a Record.................................................82 Reject a Record..................................................83 Bulk Approvals...................................................83 Get a List of Process Rules...........................................84 Get a Particular Process Rule.........................................85 Trigger Process Rules..............................................86 Using Event Monitoring.................................................86 Describe Event Monitoring Using REST...................................87 Query Event Monitoring Data with REST...................................88 Get Event Monitoring Content from a Record ..............................89

Contents

Download Large Event Log Files Using cURL with REST.........................90 Delete Event Monitoring Data.........................................90 Query or View Hourly Event Log Files.....................................91 Using Composite Resources.............................................93 Execute Dependent Requests in a Single API Call............................94 Update an Account, Create a Contact, and Link Them with a Junction Object.........96 Update a Record and Get Its Field Values in a Single Request...................98 Upsert an Account and Create a Contact.................................99 Create Nested Records.............................................100 Create Multiple Records............................................102 Using Composite Graphs...........................................103 Using a Composite Graph..........................................109 allOrNone Parameters in Composite and Collections Requests..................113 Chapter 4: Generating an OpenAPI 3.0 Document for sObjects REST API (Beta).....117 Chapter 5: Reference ...............................................122 Versions..........................................................131 Resources by Version..................................................131 Limits............................................................132 Describe Global.....................................................136 sObject Basic Information...............................................137 Retrieve Object Metadata Using sObject Basic Information.....................137 Create Records Using sObject Basic Information............................138 sObject Describe....................................................139 sObject Get Deleted..................................................140 sObject Get Updated..................................................142 sObject Named Layouts................................................143 sObject Rows.......................................................144 Get Records Using sObject Rows......................................144 Update Records Using sObject Rows...................................146 Delete Records Using sObject Rows....................................147 sObject Rows by External ID.............................................149 Get Records Using sObject Rows by External ID............................149 Create Records Using sObject Rows by External ID..........................150 Upsert Records Using sObject Rows by External ID..........................151 Delete Records Using sObject Rows by External ID..........................152 Return Headers Using sObject Rows by External ID..........................153 sObject Blob Retrieve..................................................153 sObject ApprovalLayouts...............................................154 Get Approval Layouts..............................................154 Return Headers for Approval Layouts...................................155 sObject Single Approval Process..........................................156 Get a Layout for a Single Approval Process on a Specified Object................156

Contents

Return Headers for a Single Approval Process on a Specified Object..............157 sObject CompactLayouts...............................................157 Get Compact Layouts Using sObject CompactLayouts........................158 Return Headers Using sObject CompactLayouts............................163 sObject Layouts.....................................................163 Get Layouts and Descriptions for a Specified Object..........................164 Return Layout Headers for a Specified Object..............................165 sObject Layouts for an Object With Multiple Record Types.........................166 Get Layouts and Descriptions for an Object With Multiple Record Types............166 Return Layout Headers for an Object With Multiple Record Types.................167 sObject Global Publisher Layouts..........................................167 Get Global Publisher Layouts and Descriptions.............................168 Return Headers for All Global Publisher Layouts............................169 sObject PlatformAction.................................................170 sObject Quick Actions.................................................170 Get sObject Quick Actions...........................................171 Return Headers Using sObject Quick Actions..............................171 sObject Specific Quick Actions............................................172 Retrieve Specific sObject Quick Actions..................................172 Create Records Using Specific sObject Quick Actions.........................173 Return Headers Using Specific sObject Quick Actions.........................174 sObject Quick Action Details.............................................174 Get sObject Quick Action Details.......................................175 Return Headers Using sObject Quick Action Details..........................175 sObject Quick Action Default Values........................................176 Get sObject Quick Action Default Values.................................176 Return Headers Using sObject Quick Action Default Values....................177 sObject Quick Action Default Values by ID....................................177 Get sObject Quick Action Default Values by ID.............................178 Return Headers Using sObject Quick Action Default Values by ID.................178 sObject Rich Text Image Retrieve..........................................179 sObject Relationships.................................................180 Get Records Using sObject Relationships.................................181 Update Records Using sObject Relationships..............................182 Delete Records Using sObject Relationships...............................183 sObjects Suggested Articles.............................................184 sObjects Suggested Articles by ID.........................................186 sObject User Password................................................187 Get User Password Expiration Status...................................188 Set User Password...............................................188 Reset User Password..............................................189 Return Headers Using sObject User Password.............................190