Salesforce Rest API usage with an example
to show how to upsert records


To upsert records in to salesforce objects using the REST API.

Get ready with

I would recommend you to use a developer account to experiment.
Get ready with following things.

  1. User credentials
    • Username of salesforce account. Let me use
    • Password corresponding to the username.
    • Security Token of the user is required.
      You can generate your security token as follows.
      1. Go to user settings
      2. Search security and click Reset My Security Token
      3. Click Reset Security Token button.
      4. You will get it in the email.
    • Let me use, password, securitytoken for above 3.
  2. Connected App
    • Consumer Key of the Connected App.
    • Consumer Secret of the Connected App.
    • In case, you don't have a Connected App. Follow below steps to set up one.
      1. Go to Setup
      2. Search apps and click on Create apps in the Build section.
      3. In Connected Apps section click new button.
      4. In Basic Information, fill in Connected App Name, API Name, Contact Email
      5. In API (Enable OAuth Settings),
        • Check Enable OAuth Settings.
        • Callback URL, fill in some dummy url.
        • In, Selected OAuth Scopes, Add relevant Access and manage your data (api).
      6. Save the Connected App.
      7. Then, Continue to next page.
      8. You can get Consumer Key and Consumer Secret from this page.
    • Let me use consumerkey and consumersecret for examples.

Rest API

  • HTTP Request
    • For simplicity, I have shown the HTTP request.
    • It should be fairly easy to translate it in to any language.
    • Also, I have manually added line breaks into request body for readability.
    • X-PrettyPrint header is used to get formatted JSON response from salesforce.
    • https is used for URLs.
  • HTTP Response
    • Only response body is shown in the response section.
    • Also, response code is shown in case of upsert api.

Access Token

First step is to login and get the access token.


POST /services/oauth2/token HTTP/1.1
X-PrettyPrint: 1
Content-Type: application/x-www-form-urlencoded



  "instance_url" : "",
  "id" : "",
  "token_type" : "Bearer",
  "issued_at" : "1454735969118",
  • We have to use access_token in Authorization Header as Authorization: Bearer access_token
  • We have to use the instance_url returned for accessing all resources.
  • id contains more information of the user
  • For further requests, I am going to use access_token for access_token.

Get an object

Here, I am retrieving a custom object, Mutual Fund.


GET /services/data/v35.0/sobjects/Mutual_Fund__c HTTP/1.1
Authorization: Bearer access_token
X-PrettyPrint: 1


  "objectDescribe": {
    "activateable": false,
    "createable": true,
    "custom": true,
    "customSetting": false,
    "deletable": true,
    "deprecatedAndHidden": false,
    "feedEnabled": true,
    "keyPrefix": "a00",
    "label": "Mutual Fund",
    "labelPlural": "Mutual Funds",
    "layoutable": true,
    "mergeable": false,
    "name": "Mutual_Fund__c",
    "queryable": true,
    "replicateable": true,
    "retrieveable": true,
    "searchable": true,
    "triggerable": true,
    "undeletable": true,
    "updateable": true,
    "urls": {
      "compactLayouts": "/services/data/v35.0/sobjects/Mutual_Fund__c/describe/compactLayouts",
      "rowTemplate": "/services/data/v35.0/sobjects/Mutual_Fund__c/{ID}",
      "approvalLayouts": "/services/data/v35.0/sobjects/Mutual_Fund__c/describe/approvalLayouts",
      "describe": "/services/data/v35.0/sobjects/Mutual_Fund__c/describe",
      "quickActions": "/services/data/v35.0/sobjects/Mutual_Fund__c/quickActions",
      "layouts": "/services/data/v35.0/sobjects/Mutual_Fund__c/describe/layouts",
      "sobject": "/services/data/v35.0/sobjects/Mutual_Fund__c"
  "recentItems": [
      "attributes": {
        "type": "Mutual_Fund__c",
        "url": "/services/data/v35.0/sobjects/Mutual_Fund__c/a002800000P9WeyAAF"
      "Id": "a002800000P9WeyAAF",
      "Name": "Motilal Focused Midcap 30 - DP G"

Get a record

Here, I am getting a specific record from the Mutual Funds object.


GET /services/data/v35.0/sobjects/Mutual_Fund__c/a002800000P9WeyAAF HTTP/1.1
Authorization: Bearer access_token
X-PrettyPrint: 1


  "attributes": {
    "type": "Mutual_Fund__c",
    "url": "/services/data/v35.0/sobjects/Mutual_Fund__c/a002800000P9WeyAAF"
  "Id": "a002800000P9WeyAAF",
  "OwnerId": "00528000002A6JaAAK",
  "IsDeleted": false,
  "Name": "Motilal Focused Midcap 30 - DP G",
  "CreatedDate": "2016-02-05T09:50:59.000+0000",
  "CreatedById": "00528000002A6JaAAK",
  "LastModifiedDate": "2016-02-05T10:46:48.000+0000",
  "LastModifiedById": "00528000002A6JaAAK",
  "SystemModstamp": "2016-02-05T10:46:48.000+0000",
  "LastViewedDate": "2016-02-05T10:32:24.000+0000",
  "LastReferencedDate": "2016-02-05T10:32:24.000+0000",
  "checked__c": false,
  "External_ID__c": 104

Upsert a record

  • Upsert operation will update the existing record or create a new record, if is not available.
  • Request format is same for both update and insert operation done via upsert operation.
  • An External ID field is required to perform this operation,
  • Here, External_ID__c is the custom numeric field which is checked as External ID.
  • External ID and its value should be specified in the url.
    Example: /services/data/v35.0/sobjects/Mutual_Fund__c/External_ID__c/104
  • Different response for update and insert operation as shown below.

Updating an existing record.


PATCH /services/data/v35.0/sobjects/Mutual_Fund__c/External_ID__c/104 HTTP/1.1
Authorization: Bearer access_token
X-PrettyPrint: 1
Content-Type: application/json

    "Name": "Motilal Focused Midcap 30 - DP (G)"


204 No Content

Response code 204 is returned in case of update operation.

Inserting a new record.


PATCH /services/data/v35.0/sobjects/Mutual_Fund__c/External_ID__c/111 HTTP/1.1
Authorization: Bearer access_token
X-PrettyPrint: 1
Content-Type: application/json

    "Name": "SBI Blue Chip Fund - Direct (G)"


201 Created

    "id": "a002800000PA0AzAAL",
    "success": true,
    "errors": []

Response code 201 is returned in case of insert operation.


  • It should be fairly simple to upsert records using the Upsert REST API.
  • Other operations such as insert, update, delete are similar to upsert using relevant http verb.
  • Rest API approach is right one when number of records involved is low and if it has to be real time.
  • Bulk API should be used, if you are dealing with 1000s of records and batch mode.



Great!! You read till this point, just go ahead and share this post to your followers, collegues and friends. Thanks!

About Author

Sakthi Priyan H
Passionate Programmer

  • I am passionate about building excellent teams, processes and systems.
  • Primarily I use Java, Scala and Python for building various systems and tools.
  • Building API services, Big data processing and Machine Learning systems in Crayon Data.
  • Also, interested in Golang and building web apps using Javascript ecosystem.
  • I wrote my first program in BASIC in 1998, Passionate about computers since then.