API for fetching and updating appointment preferences in Zoho CRM. These preferences define how appointments behave, including job sheet visibility, deal creation, and booking constraints.
{
"openapi": "3.1.0",
"info": {
"title": "Appointment Preference",
"description": "API for fetching and updating appointment preferences in Zoho CRM. These preferences define how appointments behave, including job sheet visibility, deal creation, and booking constraints.",
"version": "8.0"
},
"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"
}
}
}
],
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.modules.ALL"
]
}
],
"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"
]
}
]
},
"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"
]
}
]
}
}
},
"components": {
"parameters": {
"Include": {
"name": "include",
"in": "query",
"required": false,
"description": "Include additional related data in the response. For example, specify `deal_record_configuration` to include deal configuration details.",
"schema": {
"type": "string",
"enum": [
"deal_record_configuration"
]
}
}
},
"securitySchemes": {
"iam-oauth2-schema": {
"type": "oauth2",
"description": "OAuth 2.0 authorization using Zoho Accounts for secure API access.",
"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.settings.modules.ALL": "Perform read, update operation for an appointment preference in org",
"ZohoCRM.org.UPDATE": "Perform update operation for an appointment preference in org",
"ZohoCRM.org.READ": "Perform read operation for an appointment preference in org"
}
}
}
}
}
}
}