Zoho CRM Settings API

openapi: 3.2.0
info:
  title: Zoho Crm Settings API
  version: '1.0'
  description: 'Operations tagged Settings across 47 of this provider''s published API definitions: zoho-crm-appointment-preference-openapi.json, zoho-crm-assignment-rules-openapi.json, zoho-crm-audit-log-export-openapi.json, zoho-crm-business-hours-openapi.json, zoho-crm-cadences-openapi.json, zoho-crm-call-preferences-openapi.json, zoho-crm-custom-views-openapi.json, zoho-crm-data-sharing-openapi.json, zoho-crm-duplicate-check-preference-openapi.json, zoho-crm-email-templates-openapi.json, zoho-crm-field-updates-openapi.json, zoho-crm-fields-openapi.json, zoho-crm-fiscal-year-openapi.json, zoho-crm-from-addresses-openapi.json, zoho-crm-global-picklists-openapi.json, zoho-crm-inventory-templates-openapi.json, zoho-crm-layouts-activate-deactivate-openapi.json, zoho-crm-layouts-openapi.json, zoho-crm-map-dependency-openapi.json, zoho-crm-mass-delete-tags-openapi.json, zoho-crm-modules-openapi.json, zoho-crm-pick-list-values-openapi.json, zoho-crm-pipeline-openapi.json, zoho-crm-portal-user-type-openapi.json, zoho-crm-portal-users-openapi.json, zoho-crm-portals-openapi.json, zoho-crm-profiles-openapi.json, zoho-crm-record-locking-configurations-openapi.json, zoho-crm-recycle-bin-openapi.json, zoho-crm-related-lists-openapi.json, zoho-crm-roles-openapi.json, zoho-crm-scoring-rules-openapi.json, zoho-crm-service-preference-openapi.json, zoho-crm-shift-hours-openapi.json, zoho-crm-tags-actions-openapi.json, zoho-crm-tags-openapi.json, zoho-crm-territories-openapi.json, zoho-crm-territory-users-openapi.json, zoho-crm-unsubscribe-links-openapi.json, zoho-crm-user-groups-openapi.json, zoho-crm-variable-groups-openapi.json, zoho-crm-variables-openapi.json, zoho-crm-webhooks-openapi.json, zoho-crm-wizards-openapi.json, zoho-crm-workflow-rules-openapi.json, zoho-crm-workflow-tasks-openapi.json, zoho-crm-zia-enrichment-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://zohoapis.{dc}/crm/{version}
  description: Public Zoho API Server URL for your account region.
  variables:
    dc:
      enum:
      - com
      - eu
      - in
      - cn
      - au
      default: com
      description: The data center domain (top-level domain) corresponding to the account's region.
    version:
      default: v8
      description: API Version
tags:
- name: Settings
paths:
  /settings/appointment_preferences:
    get:
      operationId: getAppointmentPreference
      summary: Retrieve Appointment Preferences
      description: Fetches the existing configuration for appointment preferences, including rules for deal creation, job sheet visibility, and mark as complete configurations.
      parameters:
      - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: Appointment preferences retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                description: A JSON object containing the appointment preferences configured in the CRM.
                additionalProperties: false
                properties:
                  appointment_preferences:
                    type: object
                    description: The complete set of appointment preferences configured in CRM.
                    additionalProperties: false
                    properties:
                      show_job_sheet:
                        type: boolean
                        description: Indicates whether job sheets are shown for appointments.
                      when_duration_exceeds:
                        type: string
                        enum:
                        - mark_as_complete
                        - ask_appointment_provider_to_complete
                        description: Defines how to handle appointments when the scheduled duration is exceeded.
                      when_appointment_completed:
                        type: string
                        enum:
                        - do_not_create_deal
                        - create_deal
                        description: Determines whether a deal is automatically created when an appointment is completed.
                      allow_booking_outside_service_availability:
                        type: boolean
                        description: If true, allows booking appointments outside defined service availability.
                      allow_booking_outside_businesshours:
                        type: boolean
                        description: If true, allows appointments to be scheduled beyond business hours.
                      deal_record_configuration:
                        type: object
                        description: Configuration for creating deal records after an appointment is completed.
                        additionalProperties: false
                        properties:
                          layout:
                            type: object
                            description: Details of the layout used when creating deal records.
                            additionalProperties: false
                            properties:
                              name:
                                type: string
                                description: Name of the layout as shown in the CRM UI.
                                maxLength: 255
                              id:
                                type: string
                                description: Unique identifier for the layout (Zoho internal ID).
                                maxLength: 64
                            required:
                            - name
                          field_mappings:
                            type: array
                            description: List of field mappings from appointment data to deal fields.
                            items:
                              type: object
                              description: A single field mapping object containing the target field, mapping type and mapped value.
                              additionalProperties: false
                              properties:
                                type:
                                  type: string
                                  enum:
                                  - static
                                  - merge_field
                                  description: Specifies whether the mapping uses a static value or data from another field.
                                value:
                                  description: Value assigned to the mapped field.
                                  oneOf:
                                  - type: string
                                    description: 'Merge-field expression string (example: ${!Appointments__s.Field}).'
                                    maxLength: 1000
                                  - type: object
                                    additionalProperties: true
                                    description: Structured static value for complex fields (e.g., lookup objects)
                                field:
                                  type: object
                                  description: The target field in the deal module.
                                  additionalProperties: false
                                  properties:
                                    api_name:
                                      type: string
                                      description: API name of the deal field.
                                      maxLength: 100
                                    id:
                                      type: string
                                      description: Unique identifier of the deal field (Zoho internal ID).
                                      maxLength: 20
                                  required:
                                  - api_name
                                  - id
                              required:
                              - type
                              - value
                              - field
                            maxItems: 100
                          id:
                            type: string
                            description: Unique identifier for the deal record configuration.
                            maxLength: 20
                        required:
                        - layout
                        - field_mappings
                        - id
                    required:
                    - show_job_sheet
                    - when_appointment_completed
                    - allow_booking_outside_service_availability
                    - allow_booking_outside_businesshours
                    - deal_record_configuration
                required:
                - appointment_preferences
      security:
      - iam-oauth2-schema:
        - ZohoCRM.org.READ
      tags:
      - Settings
    put:
      operationId: updateAppointmentPreference
      summary: Update Appointment Preferences
      description: Updates one appointment preferences in Zoho CRM. This endpoint allows configuring how appointments are handled, including deal creation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body containing appointment preference fields to update.
              additionalProperties: false
              properties:
                appointment_preferences:
                  type: object
                  description: The appointment preference data to be updated.
                  additionalProperties: false
                  properties:
                    show_job_sheet:
                      type: boolean
                      description: Set to true to display job sheets for appointments.
                    when_duration_exceeds:
                      type: string
                      enum:
                      - mark_as_complete
                      - ask_appointment_provider_to_complete
                      description: Specifies how to handle appointments exceeding their duration.
                    when_appointment_completed:
                      type: string
                      enum:
                      - do_not_create_deal
                      - create_deal
                      description: Specifies whether to create a deal automatically when an appointment is completed.
                    allow_booking_outside_service_availability:
                      type: boolean
                      description: If true, allows appointments to be booked outside service availability.
                    allow_booking_outside_businesshours:
                      type: boolean
                      description: If true, allows appointments to be booked outside business hours.
                    deal_record_configuration:
                      type: object
                      description: Defines how deal records should be created after an appointment.
                      additionalProperties: false
                      properties:
                        layout:
                          type: object
                          description: Defines which layout to use for the deal record.
                          additionalProperties: false
                          properties:
                            id:
                              type: string
                              description: Unique identifier of the layout (Zoho internal ID).
                              maxLength: 20
                            name:
                              type: string
                              description: Layout name of deals module
                              maxLength: 50
                          required:
                          - id
                        field_mappings:
                          type: array
                          maxItems: 100
                          description: List of field mappings for deal creation.
                          items:
                            type: object
                            description: A single field mapping object containing the target field, mapping type and mapped value.
                            additionalProperties: false
                            properties:
                              type:
                                type: string
                                enum:
                                - static
                                - merge_field
                                description: Type of field mapping - static or merge field.
                              value:
                                description: The value to map to the target field.
                                oneOf:
                                - type: string
                                  description: 'Merge-field expression string (example: ${!Appointments__s.Field}).'
                                  maxLength: 1000
                                - type: object
                                  additionalProperties: true
                                  description: Structured static value (e.g., lookup with id and name).
                              field:
                                type: object
                                description: The target deal field details.
                                additionalProperties: false
                                properties:
                                  api_name:
                                    type: string
                                    description: API name of the target field.
                                    maxLength: 100
                                  id:
                                    type: string
                                    description: Unique identifier of the target field (Zoho internal ID).
                                    maxLength: 20
                                required:
                                - api_name
                                - id
                            required:
                            - value
                            - field
                            - type
                      required:
                      - layout
                      - field_mappings
                  required:
                  - allow_booking_outside_service_availability
                  - allow_booking_outside_businesshours
                  - deal_record_configuration
      responses:
        '200':
          description: Appointment preferences updated successfully.
          content:
            application/json:
              schema:
                type: object
                description: Response object returned after successful update, containing status metadata and details.
                additionalProperties: false
                properties:
                  appointment_preferences:
                    type: object
                    description: Response details confirming the update status.
                    additionalProperties: false
                    properties:
                      status:
                        type: string
                        enum:
                        - success
                        description: Indicates if the request was successful.
                      code:
                        type: string
                        enum:
                        - SUCCESS
                        description: Response code for a successful update.
                      message:
                        type: string
                        enum:
                        - Appointments preferences updated successfully
                        description: Human-readable success message.
                      details:
                        type: object
                        description: Additional details regarding the updated preferences. May contain operation metadata.
                        additionalProperties: true
                    required:
                    - status
                    - code
                    - message
                    - details
                required:
                - appointment_preferences
        '400':
          description: Returned when mandatory parameters are missing or invalid data is provided.
          content:
            application/json:
              schema:
                type: object
                description: Error response for invalid or incomplete request data. Top-level contains an `appointment_preferences` object with error details.
                additionalProperties: false
                properties:
                  appointment_preferences:
                    description: Contains error details for appointment preference validation.
                    oneOf:
                    - type: object
                      description: Error for missing mandatory field.
                      additionalProperties: false
                      properties:
                        status:
                          type: string
                          enum:
                          - error
                          description: Indicates an error response.
                        code:
                          type: string
                          enum:
                          - MANDATORY_NOT_FOUND
                          description: Error code indicating a required field is missing.
                        message:
                          type: string
                          description: Human-readable error message for missing mandatory field.
                          maxLength: 1000
                        details:
                          type: object
                          description: Details about which field is missing and its JSON path.
                          additionalProperties: false
                          properties:
                            api_name:
                              type: string
                              description: API name of the missing field.
                              maxLength: 100
                            json_path:
                              type: string
                              description: JSON path pointing to the missing field in the request body.
                              maxLength: 1000
                    - type: object
                      description: Error for invalid data type or unsupported value.
                      additionalProperties: false
                      properties:
                        status:
                          type: string
                          description: Status of the response
                          enum:
                          - error
                        code:
                          type: string
                          description: error code caused
                          enum:
                          - INVALID_DATA
                        message:
                          type: string
                          description: Human-readable error message describing invalid data.
                          maxLength: 1000
                        details:
                          type: object
                          description: Details about the expected data type and field information.
                          additionalProperties: false
                          properties:
                            expected_data_type:
                              type: string
                              description: The expected data type for the field (e.g., boolean, string).
                              maxLength: 255
                            api_name:
                              type: string
                              description: API name of the field with invalid data.
                              maxLength: 100
                            json_path:
                              type: string
                              description: JSON path pointing to the field with invalid data in the request body.
                              maxLength: 1000
                    - type: object
                      description: Error for dependent field mismatch.
                      additionalProperties: false
                      properties:
                        status:
                          type: string
                          description: Status of the response
                          enum:
                          - error
                        code:
                          type: string
                          description: error code caused
                          enum:
                          - DEPENDENT_MISMATCH
                        message:
                          type: string
                          description: Human-readable error describing dependent field mismatch.
                          maxLength: 1000
                        details:
                          type: object
                          description: Details about which field is missing and its JSON path.
                          additionalProperties: false
                          properties:
                            dependee:
                              type: object
                              description: Details of the dependee field that caused the mismatch.
                              additionalProperties: false
                              properties:
                                api_name:
                                  type: string
                                  description: API name of the dependee field.
                                  maxLength: 100
                                json_path:
                                  type: string
                                  description: JSON path pointing to the dependee field in the request body.
                                  maxLength: 1000
                            api_name:
                              type: string
                              description: API name of the missing field.
                              maxLength: 100
                            json_path:
                              type: string
                              description: JSON path pointing to the missing field in the request body.
                              maxLength: 1000
                required:
                - appointment_preferences
      security:
      - iam-oauth2-schema:
        - ZohoCRM.org.UPDATE
      tags:
      - Settings
    servers:
    - url: https://zohoapis.{dc}/crm/{version}
      description: Public Zoho API Server URL for your account region.
      variables:
        dc:
          enum:
          - com
          - eu
          - in
          - cn
          - au
          default: com
          description: The data center domain (top-level domain) corresponding to the account's region.
        version:
          default: v8
          description: API Version
  /settings/automation/assignment_rules:
    get:
      summary: GET /settings/automation/assignment_rules
      description: To get all assignment rules
      operationId: getAssignmentRules
      security:
      - iam-oauth2-schema:
        - ZohoCRM.settings.assignment_rules.READ
      parameters:
      - $ref: '#/components/parameters/ParamQueryModuleSchema'
      - $ref: '#/components/parameters/ParamQueryIncludeInnerDetails'
      responses:
        '200':
          description: When assignment rules are successfully fetched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllAssignmentRulesSuccessResponse'
        '204':
          description: No assignment rules available
        '400':
          description: Invalid request error cases
          content:
            application/json:
              schema:
                description: Get All AR Possible 400 Error Response Schema
                oneOf:
                - $ref: '#/components/schemas/ErrorResponseInvalidModule'
                - $ref: '#/components/schemas/ErrorResponseFeatureNotSupported'
                - $ref: '#/components/schemas/ErrorResponseModuleNotSupported'
        '403':
          description: Permission denied cases
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseNoPermissionToAccessAPI'
      tags:
      - Settings
    servers:
    - url: https://zohoapis.{dc}/crm/{version}
      description: API Server URL
      variables:
        dc:
          description: API Server URL TLD
          default: com
          enum:
          - eu
          - com
          - au
          - in
          - jp
          - cn
          - ca
        version:
          description: API Version
          default: v8
  /settings/automation/assignment_rules/{id}:
    get:
      summary: GET /settings/automation/assignment_rules/1234567890
      description: To get details of given assignment rule
      operationId: getAssignmentRuleById
      security:
      - iam-oauth2-schema:
        - ZohoCRM.settings.assignment_rules.READ
      parameters:
      - $ref: '#/components/parameters/RequestPathParamId'
      - $ref: '#/components/parameters/ParamQueryIncludeInnerDetails'
      - $ref: '#/components/parameters/ParamQueryModuleRequiredSchema'
      responses:
        '200':
          description: When assignment rule is successfully fetched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSpecificAssignmentRuleSuccessResponse'
        '204':
          description: No assignment rule available
        '400':
          description: Invalid request error cases
          content:
            application/json:
              schema:
                description: Error response for invalid module
                oneOf:
                - $ref: '#/components/schemas/ErrorResponseInvalidModule'
                - $ref: '#/components/schemas/ErrorResponseFeatureNotSupported'
                - $ref: '#/components/schemas/ErrorResponseModuleNotSupported'
        '403':
          description: Forbidden request error cases
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Possible403ErrorResponsesInManagingAR'
      tags:
      - Settings
    servers:
    - url: https://zohoapis.{dc}/crm/{version}
      description: API Server URL
      variables:
        dc:
          description: API Server URL TLD
          default: com
          enum:
          - eu
          - com
          - au
          - in
          - jp
          - cn
          - ca
        version:
          description: API Version
          default: v8
  /settings/audit_log_export:
    post:
      operationId: createAuditLogExport
      summary: Create an Audit Log Export job
      description: Creates a new export job for audit logs based on the specified criteria.
      security:
      - iam-oauth2-schema:
        - ZohoCRM.settings.audit_logs.CREATE
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Request body for creating an audit log export job.
              properties:
                audit_log_export:
                  type: array
                  description: List of audit log export jobs to be created.
                  maxItems: 100
                  items:
                    type: object
                    description: Audit log export job details.
                    properties:
                      criteria:
                        $ref: '#/components/schemas/FilterCriterionRequest'
                    required:
                    - criteria
                    additionalProperties: false
              required:
              - audit_log_export
              additionalProperties: false
      responses:
        '200':
          description: Success Response of Create Audit Log Export
          content:
            application/json:
              schema:
                type: object
                description: Success response object for Create Audit Log Export.
                properties:
                  audit_log_export:
                    type: array
                    description: List of audit log export job responses.
                    maxItems: 1
                    items:
                      type: object
                      description: Audit log export job response details.
                      properties:
                        code:
                          type: string
                          description: Status code for the export job.
                          enum:
                          - SCHEDULED
                        details:
                          type: object
                          description: Additional details for the export job.
                          properties:
                            id:
                              type: string
                              description: Unique identifier for the export job.
                              maxLength: 64
                          additionalProperties: false
                        message:
                          type: string
                          description: Message describing the export job status.
                          maxLength: 256
                        status:
                          type: string
                          description: Status of the export job.
                          enum:
                          - success
                      additionalProperties: false
                additionalProperties: false
        '400':
          description: Bad Request Response of Create Audit Log Export
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  description: Bad request response with audit_log_export array.
                  properties:
                    audit_log_export:
                      type: array
                      description: Array of audit log export errors.
                      items:
                        type: object
                        description: Error object for audit log export.
                        additionalProperties: true
                      maxItems: 100
                  additionalProperties: false
                - type: object
                  description: Bad request response with audit_log_export array.
                  properties:
                    audit_log_export:
                      type: array
                      description: Array of audit log export errors.
                      items:
                        type: object
                        description: Error object for audit log export.
                        additionalProperties: true
                      maxItems: 100
                  additionalProperties: false
                - type: object
                  description: Bad request response with audit_log_export array.
                  properties:
                    audit_log_export:
                      type: array
                      description: Array of audit log export errors.
                      items:
                        type: object
                        description: Error object for audit log export.
                        additionalProperties: true
                      maxItems: 100
                  additionalProperties: false
                - type: object
                  description: Error response for missing mandatory fields.
                  properties:
                    code:
                      type: string
                      description: Error code.
                      enum:
                      - MANDATORY_NOT_FOUND
                    message:
                      type: string
                      description: Error message.
                      maxLength: 256
                    status:
                      type: string
                      description: Error status.
                      enum:
                      - error
                    details:
                      type: object
                      description: Additional error details.
                      additionalProperties: true
                  required:
                  - code
                  - message
                  - status
                  - details
                  additionalPropertie

# --- truncated at 32 KB (2348 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-settings-api-openapi.yml