REST API v1 - Edit Records
- Zoho Creator's v1 APIs will reach their end-of-life on February 3rd, 2021. We strongly recommend you to migrate to the new v2 APIs. Refer to this post to learn more.
- Accounts in Zoho's Australia data center (.com.au) can only use Creator's v2 APIs
- Corresponding v2 APIs: Update Records and Update Record by ID
Table of Contents
URL
When accessed by the application owner:
https://creator.zoho.com/api/<ownerName>/<format>/<applicationName>/form/<formName>/record/update
When accessed by a shared user:
https://creator.zoho.com/api/<ownerName>/<format>/<applicationName>/view/<viewName>/record/update
where,
| <ownerName> | This is the admin username which can be obtained using zoho.adminuser or zoho.appuri variables (refer to this page). You can also view your app URL in the URL bar of your browser. |
| <applicationName> , <formName> and <viewName> | These are the link names of your application, form and report (that is shared to the users), respectively. They can be referred to from here. |
| <format> | This is the format in which you want the API to respond - xml or json |
Formats
xml, json
HTTP Method
POST
Parameters
| Parameter Name | Usage | Description |
| authtoken | Mandatory | A valid Auth Token. Refer this page to generate authtoken. |
| scope | Mandatory | Specify its value to creatorapi |
| criteria | Mandatory | The criteria must be specified in the format <criteria column name> <operator> <value> Example : (Name == "Jean" && DOB == "20-Jul-1981") |
| fieldName | Mandatory | This is the link name of a field. This parameter's value specifies the value to be set for that field. Refer to this page for the link names used in your applications. |
| formName | Optional | Specifies the link name of the form being updated. Required if being updated by a shared user. |
| process_until_limit | Recommended | For performance reasons, this API supports editing a maximum of 200 records per call. Refer to this section to learn how to process when more than 200 records match the given criteria. |
Prerequisites
- A valid AuthToken
- Please ensure that you've enabled the API accesspermission for the required users. It's enabled by default. It determines if the user is allowed to use your Creator application's APIs.
Sample Request
<form method="POST" action="https://creator.zoho.com/api/sampleapps/json/sample/form/Employee/record/update">
<input type="hidden" name ="authtoken" value="***********">
<input type="hidden" name ="scope" id="scope" value="creatorapi">
<input type="text" name="criteria" value="Name=Gary">
<input type="text" name="process_until_limit" value="true">
<input type="text" name="Basic" value="20000">
<input type="text" name="Address" value="UK">
<input type="submit" value="Update Record">
</form>
Sample Response
XML response
Below is an example of how this API's XML response will look when the API request includes process_until_limit=ture and there are a maximum of 200 records that match the given criteria. Refer to this section for the response with regard to editing more than 200 records.<response>
<result>
<form name="Employee">
<update>
<criteria>Name=Gary</criteria>
<newvalues>
<field name="Basic">
<value>20000</value>
</field>
<field name="Address">
<value>UK</value>
</field>
</newvalues>
<status>Success</status>
</update>
<more_records>false</more_records>
</form>
</result>
</response>
JSON response
Below is an example of how this API's JSON response will look when the API request includes process_until_limit=true and there are a maximum of 200 records that match the given criteria. Refer to this section for the response with regard to editing more than 200 records."formname": [
"RestAPI",
{
"operation": [
"update",
{
"criteria":"Name=Gary",
"newvalues": [
{
"Basic": "20000",
"Address": "UK"
}
],
"status":"Success"
}
],
"more_records": false
}
]
}
Note:
- The owner of the application with authtoken can update a record in a Form
- A user with an authtoken and share permission can update a record in a View with record editing enabled
- Updating multi select fields is supported. The values to be updated must be comma-separated. For example, <input type="text" name="mulSelect" value="A,C" />
Error Codes
- When the operation is successful, the response message will be displayed with status "Success"
- If there is an error in the request format, the corresponding error code with error message will be displayed. Please refer to the topic Error codes and descriptions to know about them.
Limits
For performance reasons, the Edit Records REST API supports editing a maximum of 200 records per call. You'll have to include process_until_limit=true when hitting this API endpoint and loop your API requests till more_records is returned as false in the response. The following table lists all the relevant scenarios:
| Does the API request include process_until_limit=true ? | Number of matching records | Result |
| Yes | up to 200 | All matching records will be edited. The more_records key in the response will have the value false. |
| Yes | More than 200 | First 200 matching records will be edited and the more_records key in the response will have the value true.
You'll have to hit this API endpoint till the more_records key's value is returned as false. |
| No | up to 200 | All matching records will be edited. Response will not contain the more_records key. |
| No | More than 200 | This API will fail and the response will contain:
|