openapi: 3.2.0 info: title: Records Upsert API description: The Zoho CRM Records API allows you to perform CRUD (Create, Read, Update, Delete) operations on records across all modules in your CRM. Use this API to retrieve, create, update, delete, upsert, and clone records. version: '8.0' servers: - url: https://zohoapis.{dc}/crm/{version} description: API Server URL variables: dc: enum: - com - eu - in - cn - au default: com description: API Server URL TLD version: default: v8 description: API Version tags: - name: Upsert paths: /{module}/upsert: post: operationId: upsertRecords summary: To insert a new or update an existing record based on duplicate check field description: The Upsert API allows you to insert a new record or update an existing one based on duplicate check field values. parameters: - $ref: '#/components/parameters/Module' requestBody: content: application/json: schema: type: object description: Request body schema for upsert operations, allowing creation or update of records based on duplicate fields. additionalProperties: false required: - data properties: data: type: array maxItems: 100 description: List of records to be created or updated using the upsert operation. items: type: object description: Single record payload containing field-value pairs for upsert. additionalProperties: true properties: id: type: - string - 'null' description: Unique identifier of the record. If null or omitted, a new record may be created. trigger: type: array description: List of automation triggers to be executed during the upsert operation. maxItems: 10 items: type: string description: Name of the trigger to be executed. maxLength: 50 duplicate_check_fields: type: array description: Defines the ordered list of fields used to detect duplicate records during upsert. maxItems: 10 items: type: string description: API name of the field used for duplicate record verification. maxLength: 100 wf_trigger: type: - string - 'null' description: Workflow trigger identifier to be executed as part of the upsert operation. lar_id: type: - string - 'null' description: Layout assignment rule identifier used to determine record layout during upsert. required: true responses: '200': description: Success Response containing the record id content: application/json: schema: $ref: '#/components/schemas/RecordSuccessResponse' '400': description: Failure in Record Update content: application/json: schema: $ref: '#/components/schemas/RecordsErrorResponse' '401': description: Unauthorized - Authentication failed or insufficient OAuth scope permissions. content: application/json: schema: $ref: '#/components/schemas/RecordUnathorizedResponse' '403': description: Forbidden - User lacks permission to add records in the requested module, Records or This API is supported only for admin users. content: application/json: schema: $ref: '#/components/schemas/RecordPermissionResponse' '404': description: Not Found - The requested URL pattern is invalid or the specified resource does not exist. content: application/json: schema: $ref: '#/components/schemas/RecordInvalidURLResponse' '412': description: The record was modified after the time specified. content: application/json: schema: type: object description: Root response object returned when a record update fails due to concurrent modification. additionalProperties: false properties: data: type: array description: List of error objects describing why the request failed. maxItems: 1 items: type: object description: Error object representing a single record modification conflict. additionalProperties: false properties: code: type: string description: Machine-readable error code indicating the type of failure. enum: - ALREADY_MODIFIED message: type: string description: Human-readable explanation of the error. maxLength: 255 status: type: string description: Overall execution status of the request. enum: - error details: type: object description: Additional metadata describing the record state at the time of conflict. additionalProperties: true properties: Modified_Time: type: string format: date-time description: Timestamp indicating when the record was last modified. Created_Time: type: string format: date-time description: Timestamp indicating when the record was originally created. id: type: string description: Unique identifier of the record that caused the conflict. format: int64 Modified_By: type: object additionalProperties: false description: User who last modified the record. properties: name: type: string description: Display name of the modifying user. maxLength: 255 id: type: string description: Unique identifier of the modifying user. format: int64 required: - name - id Created_By: type: object additionalProperties: false description: User who originally created the record. properties: name: type: string description: Display name of the creating user. maxLength: 255 id: type: string description: Unique identifier of the creating user. format: int64 required: - name - id required: - code - message - status '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/RecordInternalErrorResponse' security: - iam-oauth2-schema: - ZohoCRM.modules.Leads.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Contacts.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Accounts.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Deals.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Tasks.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Events.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Calls.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Products.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Vendors.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Campaigns.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Cases.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Solutions.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Quotes.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Invoices.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Forecasts.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Activities.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Notes.CREATE - iam-oauth2-schema: - ZohoCRM.modules.Attachments.CREATE - iam-oauth2-schema: - ZohoCRM.modules.custom.CREATE - iam-oauth2-schema: - ZohoCRM.modules.CREATE tags: - Upsert components: schemas: RecordInvalidURLResponse: description: Response schema returned when the requested API endpoint URL pattern is invalid or unsupported. type: object additionalProperties: false properties: data: type: array maxItems: 100 description: List of error objects indicating an invalid or unsupported API endpoint URL. items: type: object description: Error object representing an invalid API URL pattern. additionalProperties: false properties: code: type: string description: Machine-readable error code indicating an invalid endpoint URL pattern. enum: - INVALID_URL_PATTERN message: type: string maxLength: 1024 description: Human-readable explanation describing why the requested URL is invalid. status: type: string description: Overall execution status of the request. enum: - error required: - code - message - status RecordSuccessResponse: description: Standard success response schema for single or bulk record operations. type: object additionalProperties: false properties: data: type: array maxItems: 100 description: List of successfully processed records with detailed metadata. items: type: object description: Success object representing a single successfully processed record. additionalProperties: false properties: code: type: string description: Machine-readable code indicating a successful operation. enum: - SUCCESS message: type: string maxLength: 1024 description: Human-readable success message describing the operation outcome. status: type: string description: Overall execution status of the operation. enum: - success details: type: object description: Detailed metadata about the processed record. additionalProperties: true properties: id: type: string format: int64 description: Unique identifier of the record. Modified_Time: type: string format: date-time description: Timestamp indicating when the record was last modified. Created_Time: type: string format: date-time description: Timestamp indicating when the record was created. Created_By: type: object description: User who originally created the record. additionalProperties: false properties: name: type: string maxLength: 100 description: Display name of the creating user. id: type: string format: int64 description: Unique identifier of the creating user. required: - name - id Modified_By: type: object description: User who last modified the record. additionalProperties: false properties: name: type: string maxLength: 100 description: Display name of the modifying user. id: type: string format: int64 description: Unique identifier of the modifying user. required: - name - id $approval_state: type: string maxLength: 1024 description: Approval state of the record in the approval workflow. required: - id - Modified_Time - Created_Time - Created_By - Modified_By - $approval_state required: - code - message - status - details required: - data RecordPermissionResponse: description: Response schema returned when a user lacks the necessary permissions to perform a record operation. type: object additionalProperties: false properties: data: type: array maxItems: 100 description: List of error objects indicating insufficient user permissions. items: type: object description: Error object representing a permission denial. additionalProperties: false properties: code: type: string description: Machine-readable error code indicating the user does not have permission. enum: - NO_PERMISSION message: type: string maxLength: 1024 description: Human-readable explanation describing the permission denial. status: type: string description: Overall execution status of the request. enum: - error required: - code - message - status RecordUnathorizedResponse: description: Response schema returned when a request is unauthorized due to OAuth scope mismatches. type: object additionalProperties: false properties: data: type: array maxItems: 100 description: List of error objects indicating that the request is not authorized. items: type: object description: Error object representing an OAuth scope mismatch. additionalProperties: false properties: code: type: string description: Machine-readable error code indicating an OAuth scope mismatch. enum: - OAUTH_SCOPE_MISMATCH message: type: string maxLength: 1024 description: Human-readable explanation describing why the OAuth token is unauthorized. status: type: string description: Overall execution status of the request. enum: - error required: - code - message - status RecordInternalErrorResponse: description: Schema for internal server error responses related to record operations. type: object additionalProperties: false properties: data: type: array maxItems: 100 description: List of error objects describing internal server failures. items: type: object description: Error object representing an unexpected internal server error. additionalProperties: false properties: code: type: string description: Machine-readable error code indicating an internal server failure. enum: - INTERNAL_ERROR message: type: string maxLength: 1024 description: Human-readable description of the internal server error. status: type: string description: Overall execution status of the request. enum: - error required: - code - message - status RecordsErrorResponse: description: Standard error response schema returned when one or more record operations fail. type: object additionalProperties: false properties: data: type: array maxItems: 100 description: List of error objects describing individual record-level failures. items: type: object description: Error object representing a failure encountered while processing a record. additionalProperties: false properties: code: type: string description: Machine-readable error code identifying the reason for the failure. enum: - INVALID_DATA - INVALID_MODULE - MULTIPLE_OR_MULTI_ERRORS - DEPENDENT_FIELD_MISSING - DEPENDENT_SERVICE_ERROR - MANDATORY_NOT_FOUND - DEPENDENT_MISMATCH - INVALID_REQUEST_METHOD - AUTHORIZATION_FAILED - DUPLICATE_DATA - LIMIT_EXCEEDED - RECORD_LOCKED - EXPECTED_FIELD_MISSING details: type: object additionalProperties: true description: Additional details associated with the error. properties: resource_path_index: type: integer format: int32 description: Position of the record in the request payload where the error occurred. api_name: type: string maxLength: 1024 description: The API name of the field associated with the error. json_path: type: string maxLength: 1024 description: JSONPath pointer to the field that caused the error. expected_fields: type: array maxItems: 100 description: Used specifically when the error code is EXPECTED_FIELD_MISSING. items: type: object additionalProperties: false description: Additional information on the missing fields required: - api_name - json_path properties: api_name: maxLength: 1024 type: string description: Name of the missing expected field. json_path: maxLength: 1024 type: string description: JSONPath location of the expected field. message: type: string maxLength: 1024 description: Human-readable explanation of the error. status: type: string description: Indicates the outcome of the operation for the record. enum: - error required: - code - message - status parameters: Module: name: module description: Specifies the module name in: path required: true schema: type: string maxLength: 100 securitySchemes: iam-oauth2-schema: type: oauth2 flows: authorizationCode: authorizationUrl: https://accounts.zoho.com/oauth/v2/auth tokenUrl: https://accounts.zoho.com/oauth/v2/token refreshUrl: https://accounts.zoho.com/oauth/v2/token scopes: ZohoCRM.modules.ALL: CRUD access for all modules ZohoCRM.modules.READ: Read access for all modules ZohoCRM.modules.CREATE: Create access for all modules ZohoCRM.modules.UPDATE: Update access for all modules ZohoCRM.modules.DELETE: Delete access for all modules ZohoCRM.modules.Leads.READ: Read access to Leads ZohoCRM.modules.Leads.CREATE: Create access to Leads ZohoCRM.modules.Leads.UPDATE: Update access to Leads ZohoCRM.modules.Leads.DELETE: Delete access to Leads ZohoCRM.modules.Leads.WRITE: Write access to Leads ZohoCRM.modules.Leads.All: All permissions for Leads ZOHOCRM.modules.Leads.READ: (legacy key) Read access to Leads ZohoCRM.modules.Contacts.READ: Read access to Contacts ZohoCRM.modules.Contacts.CREATE: Create access to Contacts ZohoCRM.modules.Contacts.UPDATE: Update access to Contacts ZohoCRM.modules.Contacts.DELETE: Delete access to Contacts ZohoCRM.modules.Accounts.READ: Read access to Accounts ZohoCRM.modules.Accounts.CREATE: Create access to Accounts ZohoCRM.modules.Accounts.UPDATE: Update access to Accounts ZohoCRM.modules.Accounts.DELETE: Delete access to Accounts ZohoCRM.modules.Deals.READ: Read access to Deals ZohoCRM.modules.Deals.CREATE: Create access to Deals ZohoCRM.modules.Deals.UPDATE: Update access to Deals ZohoCRM.modules.Deals.DELETE: Delete access to Deals ZohoCRM.modules.Tasks.READ: Read access to Tasks ZohoCRM.modules.Tasks.CREATE: Create access to Tasks ZohoCRM.modules.Tasks.UPDATE: Update access to Tasks ZohoCRM.modules.Tasks.DELETE: Delete access to Tasks ZohoCRM.modules.Events.READ: Read access to Events ZohoCRM.modules.Events.CREATE: Create access to Events ZohoCRM.modules.Events.UPDATE: Update access to Events ZohoCRM.modules.Events.DELETE: Delete access to Events ZohoCRM.modules.Calls.READ: Read access to Calls ZohoCRM.modules.Calls.CREATE: Create access to Calls ZohoCRM.modules.Calls.UPDATE: Update access to Calls ZohoCRM.modules.Calls.DELETE: Delete access to Calls ZohoCRM.modules.Products.READ: Read access to Products ZohoCRM.modules.Products.CREATE: Create access to Products ZohoCRM.modules.Products.UPDATE: Update access to Products ZohoCRM.modules.Products.DELETE: Delete access to Products ZohoCRM.modules.Vendors.READ: Read access to Vendors ZohoCRM.modules.Vendors.CREATE: Create access to Vendors ZohoCRM.modules.Vendors.UPDATE: Update access to Vendors ZohoCRM.modules.Vendors.DELETE: Delete access to Vendors ZohoCRM.modules.Campaigns.READ: Read access to Campaigns ZohoCRM.modules.Campaigns.CREATE: Create access to Campaigns ZohoCRM.modules.Campaigns.UPDATE: Update access to Campaigns ZohoCRM.modules.Campaigns.DELETE: Delete access to Campaigns ZohoCRM.modules.Cases.READ: Read access to Cases ZohoCRM.modules.Cases.CREATE: Create access to Cases ZohoCRM.modules.Cases.UPDATE: Update access to Cases ZohoCRM.modules.Cases.DELETE: Delete access to Cases ZohoCRM.modules.Solutions.READ: Read access to Solutions ZohoCRM.modules.Solutions.CREATE: Create access to Solutions ZohoCRM.modules.Solutions.UPDATE: Update access to Solutions ZohoCRM.modules.Solutions.DELETE: Delete access to Solutions ZohoCRM.modules.Quotes.READ: Read access to Quotes ZohoCRM.modules.Quotes.CREATE: Create access to Quotes ZohoCRM.modules.Quotes.UPDATE: Update access to Quotes ZohoCRM.modules.Quotes.DELETE: Delete access to Quotes ZohoCRM.modules.Invoices.READ: Read access to Invoices ZohoCRM.modules.Invoices.CREATE: Create access to Invoices ZohoCRM.modules.Invoices.UPDATE: Update access to Invoices ZohoCRM.modules.Invoices.DELETE: Delete access to Invoices ZohoCRM.modules.Forecasts.READ: Read access to Forecasts ZohoCRM.modules.Forecasts.CREATE: Create access to Forecasts ZohoCRM.modules.Forecasts.UPDATE: Update access to Forecasts ZohoCRM.modules.Forecasts.DELETE: Delete access to Forecasts ZohoCRM.modules.Activities.READ: Read access to Activities ZohoCRM.modules.Activities.CREATE: Create access to Activities ZohoCRM.modules.Activities.UPDATE: Update access to Activities ZohoCRM.modules.Activities.DELETE: Delete access to Activities ZohoCRM.modules.Notes.READ: Read access to Notes ZohoCRM.modules.Notes.CREATE: Create access to Notes ZohoCRM.modules.Notes.UPDATE: Update access to Notes ZohoCRM.modules.Notes.DELETE: Delete access to Notes ZohoCRM.modules.Attachments.READ: Read access to Attachments ZohoCRM.modules.Attachments.CREATE: Create access to Attachments ZohoCRM.modules.Attachments.UPDATE: Update access to Attachments ZohoCRM.modules.Attachments.DELETE: Delete access to Attachments ZohoCRM.modules.custom.READ: Read access to custom modules ZohoCRM.modules.custom.CREATE: Create access to custom modules ZohoCRM.modules.custom.UPDATE: Update access to custom modules ZohoCRM.modules.custom.DELETE: Delete access to custom modules