Zoho

Zoho Upsert API

The Upsert API from Zoho — 1 operation(s) for upsert.

GitHub OpenAPI

Documentation

📖
Documentation
https://www.zoho.com/crm/developer/docs/api/
📖
APIReference
https://www.zoho.com/crm/developer/docs/api/v8/
📖
GettingStarted
https://www.zoho.com/crm/developer/docs/
📖
Documentation
https://desk.zoho.com/DeskAPIDocument
📖
Documentation
https://www.zoho.com/analytics/api/v2/introduction.html
📖
APIReference
https://www.zoho.com/analytics/api/v2/
📖
Documentation
https://www.bigin.com/developer/docs/apis/v2/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/zoho/refs/heads/main/openapi/zoho-upsert-api-openapi.yml

Code Examples

💻
CodeExamples
https://github.com/zoho/ZohoDesk-PortalSDK-Sample-apps-iOS
💻
CodeExamples
https://github.com/zoho/ZohoDesk-PortalSDK-sample-apps-android
💻
CodeExamples
https://github.com/zoho/ZohoDesk-PortalSDK-sample-apps-flutter
💻
CodeExamples
https://github.com/zoho/ZohoDesk-PortalSDK-sample-apps-reactnative
💻
CodeExamples
https://github.com/zoho/Zoho-Desk-ASAP-Mobile-SDK-API-Samples
💻
CodeExamples
https://github.com/zoho/analytics-codestudio

Other Resources

🔗
SDKs
https://packagist.org/packages/zohocrm/php-sdk-8.0
🔗
SDKs
https://pypi.org/project/zohocrmsdk8-0/
🔗
SDKs
https://www.nuget.org/packages/ZOHOCRMSDK-8.0/
🔗
SDKs
https://github.com/zoho/zohocrm-java-sdk-8.0
🔗
SDKs
https://www.npmjs.com/package/@zohocrm/nodejs-sdk-8.0
🔗
SDKs
https://www.npmjs.com/package/@zohocrm/typescript-sdk-8.0
🔗
SDKs
https://rubygems.org/gems/ZOHOCRMSDK8_0
🔗
SDKs
https://github.com/zoho/zohocrm-javascript-sdk-8.0
🔗
SDKs
https://github.com/zoho/zohocrm-scala-sdk-8.0
🔗
SDKs
https://cocoapods.org/pods/ZCRMiOS
🔗
DeveloperPortal
https://www.zoho.com/desk/developers/
🔗
SDKs
https://github.com/zoho/ZohoDeskPortalSDK
🔗
SDKs
https://github.com/zoho/react-native-zohodesk-portal-sdk
🔗
SDKs
https://github.com/zoho/zdesk-asap-flutter
🔗
SDKs
https://github.com/zoho/cordova-plugin-zohodesk-portal
🔗
Tools
https://github.com/zoho/analytics-mcp-server
🔗
Integrations
https://github.com/zoho/analytics-dataiku-import-plugin
🔗
Integrations
https://github.com/zoho/analytics-dataiku-export-plugin
🔗
DeveloperPortal
https://www.bigin.com/developer-center.html

OpenAPI Specification

zoho-upsert-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Helpcenter Upsert API
  version: 1.0.0
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:
    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
    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
    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
    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
    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:
      $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema
x-entity: Helpcenter