Zoho: Create or update records in a specified module
Zoho record.upsertRecords: arguments, response, policy and SDK examples.
← Record operations · Get started
Operation zoho.upsertrecords
Provider route: POST /crm/v8/{module}/upsert. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/zoho with npm, or alter-sdk-zoho with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { ZohoIntegration } from "@alter-ai/zoho";
async function execute(input: Parameters<ZohoIntegration["record"]["upsertRecords"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new ZohoIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.record.upsertRecords(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_zoho import ZohoIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = ZohoIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.record.upsert_records(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
path | object | Required within parent | Additional keys: not allowed |
path.module | string | Required within parent | Maximum length: 25 |
body | Model | Required within parent | Expand Create or update records in a specified module — request body — body |
Referenced models: Create or update records in a specified module — request body — body
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | Model | Alternative | Expand Create or update records in a specified module — response body — data |
$ (anyOf 2) | object | Alternative | Represents the multi-status response returned when a bulk operation results in mixed success and failure outcomes. Additional keys: not allowed |
$ (anyOf 2).data | array | Required within parent | Contains the list of per-record results for the operation. Maximum items: 100 Minimum items: 2 |
$ (anyOf 2).data[] | JSON | Each item | Represents a single record operation result, which is either a success or error item identified by the status field. |
$ (anyOf 2).data[] (anyOf 1) | Model | Alternative | Expand Create or update records in a specified module — response body — data / data / item / action: insert, update, code: SUCCESS, status: success |
$ (anyOf 2).data[] (anyOf 2) | Model | Alternative | Expand Create or update records in a specified module — response body — data data item value |
$ (anyOf 2).data (allOf 1) | JSON | All variants apply | Ensures the response contains at least one successful result in the data array. |
$ (anyOf 2).data (allOf 2) | JSON | All variants apply | Ensures the response contains at least one failed result in the data array. |
Referenced models: Create or update records in a specified module — response body — data data item value, Create or update records in a specified module — response body — data / data / item / action: insert, update, code: SUCCESS, status: success, Create or update records in a specified module — response body — data
Schemas
Section titled “Schemas”24 more schemas are linked from the tables above, on the schema pages.
Create or update records in a specified module — response body — data data item value
Referenced models: Create records in a specified module — response body — data / data / item / value / code: INVALID DATA, status: error — Invalid Data Value Error, Create records in a specified module — response body — data / data / item / value / code: INVALID DATA, status: error — Invalid Max Length Error, Create records in a specified module — response body — data / data / item / value / code: INVALID DATA, status: error — Invalid Supported Values Error, Create records in a specified module — response body — data / data / item / value / code: MULTIPLE OR MULTI ERRORS, status: error, Create records in a specified module — response body — data / data / item / value / code: AUTHORIZATION FAILED, status: error, Create records in a specified module — response body — data / data / item / value / code: DEPENDENT FIELD MISSING, status: error, Create records in a specified module — response body — data / data / item / value / code: DEPENDENT MISMATCH, status: error, Create records in a specified module — response body — data / data / item / value / code: DUPLICATE DATA, status: error, Create records in a specified module — response body — data / data / item / value / code: INVALID DATA, status: error — Record Invalid Data Type Error, Create records in a specified module — response body — data / data / item / value / code: INVALID MODULE, status: error, Create records in a specified module — response body — data / data / item / value / code: INVALID REQUEST METHOD, status: error, Create records in a specified module — response body — data / data / item / value / code: MANDATORY NOT FOUND, status: error — Record Mandatory Not Found Error
Create or update records in a specified module — response body — data / data / item / action: insert, update, code: SUCCESS, status: success
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Represents a single record upsert success data result item. Additional keys: not allowed |
action | string | Required within parent | Represents the action that triggered the record lock. Known values: insert, update |
code | string | Required within parent | Represents the error code identifying the type of failure. Known values: SUCCESS |
details | Model | Required within parent | Expand Create or update records in a specified module — response body — data / data / item / action: insert, update, code: SUCCESS, status: success details |
duplicate_field | JSON | Required within parent | |
duplicate_field (anyOf 1) | string | Alternative | Represents the duplicate field value. Maximum length: 255 |
duplicate_field (anyOf 2) | null | Alternative | Represents the duplicate field value. Maximum length: 255 |
message | string | Required within parent | Represents the error message describing why the operation failed. |
status | string | Required within parent | Indicates the overall result status of the request. Known values: success |
Referenced models: Create or update records in a specified module — response body — data / data / item / action: insert, update, code: SUCCESS, status: success details
Create or update records in a specified module — response body — data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Represents the response schema for the record upsert success operation. Additional keys: not allowed |
data | array | Required within parent | Represents the data value. Maximum items: 100 Minimum items: 1 |
data[] | object | Each item | Represents a single item in the RecordUpsertSuccessResponse array. Additional keys: not allowed |
data[].action | string | Required within parent | Represents the data value. Known values: insert, update |
data[].code | string | Required within parent | Represents the data value. Known values: SUCCESS |
data[].details | Model | Required within parent | Expand Create or update records in a specified module — response body — data data item details |
data[].duplicate_field | JSON | Required within parent | |
data[].duplicate_field (anyOf 1) | string | Alternative | Represents the data value. Maximum length: 255 |
data[].duplicate_field (anyOf 2) | null | Alternative | Represents the data value. Maximum length: 255 |
data[].message | string | Required within parent | Represents the data value. |
data[].status | string | Required within parent | Represents the data value. Known values: success |
Referenced models: Create or update records in a specified module — response body — data data item details
Create or update records in a specified module — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Request body schema for upsert operations, allowing creation or update of records based on duplicate fields. Additional keys: not allowed |
data | array | Required within parent | List of records to be created or updated using the upsert operation. Maximum items: 100 Minimum items: 1 |
data[] | Model | Each item | Expand Update a specific record by ID — request body — body data item |
duplicate_check_fields | array | Optional | Specifies the fields used to check for duplicate records during an Upsert operation. Duplicate check fields can be system-defined unique fields or user-defined unique fields. The following are the system-defined duplicate check fields for the respective modules: Leads - "Email"; Accounts - "Account_Name"; Contacts - "Email"; Deals - "Deal_Name"; Campaigns - "Campaign_Name"; Cases - "Subject"; Solutions - "Solution_Title"; Products - "Product_Name"; Vendors - "Vendor_Name"; PriceBooks - "Price_Book_Name"; Quotes - "Subject"; SalesOrders - "Subject"; PurchaseOrders - "Subject"; Invoices - "Subject"; Custom Modules - "Name". If a matching record is found based on these fields, the record is updated; otherwise, a new record is inserted. |
duplicate_check_fields[] | string | Each item | API name of the field used for duplicate record verification. Maximum length: 100 |
lar_id | string | Optional | The unique ID of the assignment rule to trigger while inserting a record. Use the Get Assignment Rules API to retrieve valid values. This key must be provided parallel to the data key. Supported for all modules where assignment rules are applicable, such as Leads, Contacts, Deals, Accounts, Tasks, Cases, and Custom. Maximum length: 19 Minimum length: 1 Pattern: ^[1-9][0-9]{0,18}$ |
trigger | array | Optional | Specifies the CRM features to execute for the API request. Supported values are "workflow", "approval", and "blueprint". If the "trigger" parameter is not specified, workflows, approvals, and blueprints related to the API are executed. Specify an empty array [] to prevent these features from executing. |
trigger[] | string | Each item | Represents a single item in the RecordsInputSchema array. One of: approval, workflow, blueprint, pathfinder, orchestration |
wf_trigger | string or null | Optional | Workflow trigger identifier to be executed as part of the upsert operation. Maximum length: 50 |
Referenced models: Update a specific record by ID — request body — body data item
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: zoho.upsertrecords. Catalog operation: upsertRecords. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.