Zoho CRM Upsert API

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