Update Records

Purpose

To update existing entities in the module.

Request Details

Request URL

{api-domain}/crm/{version}/{module_api_name}

To update a specific record:
{api-domain}/crm/{version}/{module_api_name}/{record_id}

Supported modules

Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Events, Calls, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, Appointments, Appointments Rescheduled History, Services and Custom

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope=ZohoCRM.modules.ALL
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names

leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, custom, appointments, appointments_rescheduled_history, services and notes

Possible operation types

ALL - Full access to the record
WRITE - Edit records in the module
UPDATE - Update records in the module

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v5/Deals"
-X PUT
-d "@updatedeal.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
CopiedSyntax:
<variable> =zoho.crm.updateRecord(<module_name>, <record_ID>, <record_value>, [<query_value>], [<connection>]);
mandatory: module_name, record_id

Sample Request:
leadinfo = 
 {
 "Company":"Zylker", 
 "Last_Name":"Stewart", 
 "Phone":"9876XXXXXX",
 "Email":"stewart@zylker.com"
 }; 

response = zoho.crm.updateRecord("Leads",23033XXXXXXXXXXXXXX,leadinfo);

In the request, "@updatelead.json" contains the sample input.

Request JSON Keys

  • idstring, mandatory

    Specify the unique ID of the record that you want to update. Refer to Get Records API to get the unique ID of the record.

  • $append_valuesJSON object, optional

    Represents whether you want to append the values of the multi-select picklist you specified in the input to the existing values. Specify the API names of the multi-select picklist and "true" or "false" as key-value pairs in this JSON object. The value "true" adds the values in the input to the multi-select picklist, while the value "false" replaces the existing values with the ones in the input.
    Example:
    "$append_values":{
    "Multi_Select_1": true,
    "Multi_Select_2": false
    }
    Note that the values are appended or replaced only for those records that have this key in the input. For the other multi-select picklists, the existing values are simply replaced by default.

Note

  • The 'INVALID_DATA' error is thrown if the field value length is more than the maximum length defined for that field.
  • If an API is used inside a Function and the field value length exceeds the limit, then that function receives error response from the API. For ex: If the max length for a "Text field" is defined as 10, then value given for it in API cannot be "12345678901", as it has 11 characters.
  • A maximum of 100 records can be updated per API call.
  • You must use only Field API names in the input. You can obtain the field API names from
    • Fields metadata API (the value for the key “api_name” for every field). (Or)
    • Setup > Developer Space > APIs > API Names > {Module}. Choose “Fields” from the “Filter By” drop-down.
  • Records with Subform details can also be updated to CRM using the Records API. Please look at Subforms API to learn more about updating subform information within a record.
  • If the update API calls for a record are from DRE(Functions), due to workflow triggered on the same record's create/update, workflow alone will not get executed, irrespective of the trigger param configuration.
  • Use the "_delete" key to delete data from multi-select lookup, multi-user lookup, and image upload fields. You must pass the ID of the linking module in the input. Refer to the sample input for details.
  • All records that are updated will enter the review process by default.
  • You can also use the sample response of each module as the input when you insert, update, or upsert a record in that corresponding module.
  • Refer to the Get Records API to know more about field types and limits.
  • You can update all fields in a module that are supported in the insert records operation.
  • You must provide the layout ID field if you want to
    • include the layout specific mandatory fields in the API-level mandatory check
    • include only the fields that are defined in your layout for API- level processing and ignore the rest

Sample Input

Copied{
  "data": [
    {
      "id": "3652397000003852095",
      "Deal_Name": "v5 Update",
      "Stage": "Closed Won",
      "Pipeline": "Standard (Standard)",
      "Foreign_Languages": [ //multi-select picklist
        "Korean","Spanish"
      ],
      "$append_values": {
        "Foreign_Languages": false
      },
      "Image_Upload": [
        {
          "File_Id__s": "2cxx2fa"
        },
        {
          "id": "738964000002363016",
          "_delete": null
        }
      ],
      "Listings": [//multi-select lookup
        {
          "Interested_Listings": {
          "id": "3652397000001988001"
          }
        },
        {
          "id": "431581000000697244",
          "_delete": null
         }
      ],
      "AssociatedUser": [//multi-user lookup
        {
          "User": {
            "name": "J Smith",
            "id": "3652397000000281001"
          }
        },
        {
            "id": "431581000000701821",
            "_delete": null
         }
      ]
    }
  ]
}

Possible Errors

  • INVALID_MODULEHTTP 400

    The module name given seems to be invalid
    Resolution: You have specified an invalid module name or there is no tab permission, or the module could have been removed from the available modules. Specify a valid module API name.

  • INVALID_MODULEHTTP 400

    The given module is not supported in API
    Resolution: The modules such as Documents and Projects are not supported in the current API. (This error will not be shown, once these modules are been supported). Specify a valid module API name.

  • INVALID_DATAHTTP 400

    the id given seems to be invalid
    Resolution: You have specified an incorrect record ID. Please specify a valid record ID. Refer to Get Records API to get valid record IDs.

  • MANDATORY_NOT_FOUNDHTTP 400

    Required field not found
    Resolution: You have not specified unique ID of the record to be updated in the request. Please specify the ID of the record to be updated, refer to Get Records API to get valid record IDs.

  • INVALID_URL_PATTERNHTTP 404

    Please check if the URL trying to access is a correct one
    Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to request URL section above.

  • OAUTH_SCOPE_MISMATCHHTTP 401

    Unauthorized
    Resolution: Client does not have ZohoCRM.modules.{module_name}.UPDATE scope. Create a new client with valid scope. Refer to scope section above.

  • NO_PERMISSIONHTTP 403

    Permission denied to update
    Resolution: The user does not have permission to update records data. Contact your system administrator.

  • INTERNAL_ERRORHTTP 500

    Internal Server Error
    Resolution: Unexpected and unhandled exception in Server. Contact support team.

  • INVALID_REQUEST_METHODHTTP 400

    The http request method type is not a valid one
    Resolution: You have specified an invalid HTTP method to access the API URL. Specify a valid request method. Refer to endpoints section above.

  • AUTHORIZATION_FAILEDHTTP 400

    User does not have sufficient privilege to update records
    Resolution: The user does not have the permission to update records. Contact your system administrator.

  • DUPLICATE_DATAHTTP 400

    duplicate data
    Resolution: You have specified a duplicate value for one or more unique fields. Refer to Fields Metadata API to know the unique fields.

  • LIMIT_EXCEEDEDHTTP 400

    Only 50 participants can be added to an event.
    Resolution: You are trying to update an event with more than 50 participants. You can add only upto 50 participants to an event.

  • RECORD_LOCKEDHTTP 400

    Cannot update record that is not approved yet
    Resolution: Please wait until the Zia image or the merge duplicates process is complete and try again.

  • RECORD_LOCKEDHTTP 400

    You cannot perform this operation as the record is locked.
    Resolution: Please wait until the record is unlocked.

  • NOT_APPROVEDHTTP 400

    Cannot update record that is not approved yet
    Resolution:

    • Case 1: If the record is in the rejected state due to Zia image validation, either upload a new image (or) delete the failed image and, resubmit the record to Zia image validation.
    • Case 2: If the record is in Zia record approval, the system will not allow you to update the images of the record until the reviewer approves or rejects the record.

Sample Response

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "details": {
                "Modified_Time": "2021-05-02T11:17:33+05:30",
                "Modified_By": {
                    "name": "Patricia Boyle",
                    "id": "554023000000235011"
                },
                "Created_Time": "2021-05-02T11:17:33+05:30",
                "id": "554023000000527003",
                "Created_By": {
                    "name": "Patricia Boyle",
                    "id": "554023000000235011"
                }
            },
            "message": "record updated",
            "status": "success"
        }
    ]
}