API specification for Fiscal Year. Published by Zoho in its first-party OpenAPI 3.1.0 repository github.com/zoho/crm-oas; 2 operation(s).
{
"openapi": "3.1.0",
"info": {
"title": "Fiscal Year",
"description": "API specification for Fiscal Year",
"version": "8"
},
"servers": [
{
"url": "https://zohoapis.{dc}/crm/{version}",
"description": "API Server URL",
"variables": {
"dc": {
"description": "API Server URL TLD",
"default": "com",
"enum": [
"com",
"eu",
"in",
"cn",
"au",
"ca",
"jp"
]
},
"version": {
"description": "API Version",
"default": "v8"
}
}
}
],
"paths": {
"/settings/fiscal_year": {
"get": {
"summary": "GET /settings/fiscal_year",
"description": "API DOC : https://learn.zoho.in/portal/zohocorp/manual/v3-apis-1/article/custom-fiscal-year-support",
"operationId": "getFiscalYear",
"responses": {
"200": {
"description": "OK - Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetfiscalyearResponse200"
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.fiscal_year.READ"
]
}
]
},
"put": {
"summary": "PUT /settings/fiscal_year",
"description": "Only Admins can update Fiscal YearAPI DOC : https://learn.zoho.in/portal/zohocorp/manual/v3-apis-1/article/custom-fiscal-year-support",
"operationId": "updateFiscalYear",
"requestBody": {
"description": "Request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PutfiscalyearRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK - Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateFiscalYearResponse"
}
}
}
},
"400": {
"description": "Bad Request - The request cannot be processed due to invalid syntax.",
"content": {
"application/json": {
"schema": {
"description": "Fiscal Year Error Responses",
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"description": "Wrapped error response with fiscal_year",
"properties": {
"fiscal_year": {
"oneOf": [
{
"$ref": "#/components/schemas/FiscalInvalidStartDateError"
},
{
"$ref": "#/components/schemas/FiscalInvalidCalendarTypeError"
},
{
"$ref": "#/components/schemas/FiscalInvalidStructureError"
},
{
"$ref": "#/components/schemas/FiscalInvalidStartDateMonthError"
},
{
"$ref": "#/components/schemas/FiscalInvalidSurplusWeekError"
},
{
"$ref": "#/components/schemas/FiscalInvalidMonthError"
},
{
"$ref": "#/components/schemas/FiscalInvalidDisplayOptionError"
},
{
"$ref": "#/components/schemas/FiscalInvalidCalendarError"
},
{
"$ref": "#/components/schemas/FiscalInvalidEndMonthConfigError"
},
{
"$ref": "#/components/schemas/FiscalInvalidStartYearError"
},
{
"$ref": "#/components/schemas/FiscalInvalidSurpluYearError"
},
{
"$ref": "#/components/schemas/FiscalCompletedSurplusError"
},
{
"$ref": "#/components/schemas/AmbiguityError"
},
{
"$ref": "#/components/schemas/DependentFieldMissingError"
}
]
}
},
"required": [
"fiscal_year"
]
}
]
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.fiscal_year.UPDATE"
]
}
]
}
}
},
"components": {
"schemas": {
"GETFiscalYearNested": {
"type": "object",
"additionalProperties": false,
"description": "Nested schema for fiscal_year",
"properties": {
"calendar_type": {
"type": "string",
"description": "Field: calendar_type",
"maxLength": 255
},
"display_based_on": {
"type": "string",
"description": "Field: display_based_on",
"maxLength": 255
},
"surplus_week": {
"$ref": "#/components/schemas/GETSurplusWeekNested"
},
"start_month": {
"type": "string",
"description": "Field: start_month",
"maxLength": 255
},
"interval_display_option": {
"type": [
"string",
"null"
],
"description": "Field: interval_display_option",
"maxLength": 255
},
"id": {
"type": "string",
"description": "Field: id",
"maxLength": 255
},
"structure": {
"type": [
"string",
"null"
],
"description": "Field: structure",
"maxLength": 255
},
"past_surplus_weeks": {
"type": "null",
"description": "Field: past_surplus_weeks"
},
"start_date": {
"type": [
"string",
"null"
],
"description": "Field: start_date",
"maxLength": 255
}
},
"required": [
"calendar_type",
"display_based_on",
"id",
"interval_display_option",
"past_surplus_weeks",
"start_date",
"start_month",
"structure",
"surplus_week"
]
},
"SurplusWeekNested": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"description": "In Custom Fiscal Year, a surplus week is an extra week added to keep the fiscal calendar aligned with the actual calendar year.",
"properties": {
"period": {
"type": [
"string",
"null"
],
"description": "Period of the surplus week",
"maxLength": 1
},
"year": {
"type": [
"string",
"null"
],
"description": "year of the surplus week.Can configure only for current year and the following year only",
"maxLength": 4
},
"quarter": {
"type": [
"string",
"null"
],
"description": "quarter of the surplus week",
"maxLength": 1
}
}
},
"FiscalInvalidMonthError": {
"type": "object",
"additionalProperties": false,
"description": "Invalid start_month",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"api_name": {
"type": "string",
"description": "Detail field: api_name",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "Detail field: json_path",
"maxLength": 1000
},
"supported_values": {
"type": "array",
"description": "Detail field: supported_values",
"items": {
"type": "string",
"description": "Detail Field: supported_values",
"maxLength": 255
},
"maxItems": 25
}
},
"required": [
"api_name",
"json_path",
"supported_values"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"Please give a valid month"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Error Response Core"
},
"FiscalInvalidStartYearError": {
"type": "object",
"additionalProperties": false,
"description": "while configuring fiscal year start date other than current year",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"api_name": {
"type": "string",
"description": "Detail field: api_name",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "Detail field: json_path",
"maxLength": 1000
}
},
"required": [
"api_name",
"json_path"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"custom fiscal year can be configured only with current year"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Error Response Core"
},
"GetfiscalyearResponse200": {
"type": "object",
"additionalProperties": false,
"description": "Successful API operation completed",
"properties": {
"fiscal_year": {
"$ref": "#/components/schemas/GETFiscalYearNested"
}
},
"required": [
"fiscal_year"
]
},
"FiscalInvalidDisplayOptionError": {
"type": "object",
"additionalProperties": false,
"description": "Invalid display_based_on",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"api_name": {
"type": "string",
"description": "Detail field: api_name",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "Detail field: json_path",
"maxLength": 1000
},
"supported_values": {
"type": "array",
"description": "Detail field: supported_values",
"items": {
"type": "string",
"description": "Detail Field: supported_values",
"maxLength": 255
},
"maxItems": 25
}
},
"required": [
"api_name",
"json_path",
"supported_values"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"Please give a valid display based on",
"Please give a valid interval_display_option"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Error Response Core"
},
"UpdateFiscalYearResponse": {
"type": "object",
"additionalProperties": false,
"description": "Successful API operation completed",
"properties": {
"fiscal_year": {
"$ref": "#/components/schemas/FiscalYearNested1"
}
}
},
"FiscalInvalidStartDateMonthError": {
"type": "object",
"additionalProperties": false,
"description": "when start_month is given and does not match with start_date",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"api_name": {
"type": "string",
"description": "Detail field: api_name",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "Detail field: json_path",
"maxLength": 1000
}
},
"required": [
"api_name",
"json_path"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"start_month does not match with start_date",
"start_date does not match with start_month"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Error Response Core"
},
"FiscalYearNested": {
"type": "object",
"additionalProperties": false,
"description": "Root key of the API",
"properties": {
"calendar_type": {
"type": [
"string",
"null"
],
"description": "calendar_type of the fiscal_year can only be configured with \"gregorian\" or \"custom\" which indicates standard or custom fiscal year.",
"enum": [
"gregorian",
"custom"
],
"maxLength": 10
},
"display_based_on": {
"type": [
"string",
"null"
],
"description": "Indicates whether the fiscal year label is based on the start month or end month",
"enum": [
"start_month",
"end_month"
],
"maxLength": 20
},
"surplus_week": {
"$ref": "#/components/schemas/SurplusWeekNested",
"description": "In Custom Fiscal Year, a surplus week is an extra week added to keep the fiscal calendar aligned with the actual calendar year."
},
"start_month": {
"type": [
"string",
"null"
],
"description": "start_month is the month when the fiscal year begins. It can be configured for standard fiscal year(calendar_type = 'gregorian').",
"enum": [
"JANUARY",
"FEBRUARY",
"MARCH",
"APRIL",
"MAY",
"JUNE",
"JULY",
"AUGUST",
"SEPTEMBER",
"OCTOBER",
"NOVEMBER",
"DECEMBER"
],
"maxLength": 20
},
"interval_display_option": {
"type": [
"string",
"null"
],
"description": "interval_display_option indicates the display format for which the periods should get displayed.",
"enum": [
"year",
"quarter"
],
"maxLength": 7
},
"structure": {
"type": [
"string",
"null"
],
"description": "Structure pattern for custom fiscal year configuration. It allows 7 structures 4-4-5, 4-5-4, 5-4-4 (quarter-based) and 3-3-3-4, 3-3-4-3, 3-4-3-3, 4-3-3-3 (year-based) -- describing how weeks are distributed across \"periods\" and \"quarters\".",
"enum": [
"4-4-5",
"4-5-4",
"5-4-4",
"3-3-3-4",
"3-3-4-3",
"3-4-3-3",
"4-3-3-3"
],
"maxLength": 10
},
"start_date": {
"type": [
"string",
"null"
],
"format": "date",
"description": "It indicates the start_date for the custom fiscal year which can be configured only for the current year.",
"maxLength": 10
}
}
},
"FiscalInvalidStructureError": {
"type": "object",
"additionalProperties": false,
"description": "Invalid structure",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"api_name": {
"type": "string",
"description": "Detail field: api_name",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "Detail field: json_path",
"maxLength": 1000
},
"supported_values": {
"type": "array",
"description": "Detail field: supported_values",
"items": {
"type": "string",
"description": "Detail Field: supported_values",
"maxLength": 255
},
"maxItems": 25
}
},
"required": [
"api_name",
"json_path",
"supported_values"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"Please give a valid structure"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Error Response Core"
},
"FiscalInvalidCalendarTypeError": {
"type": "object",
"additionalProperties": false,
"description": "Invalid structure",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"api_name": {
"type": "string",
"description": "Detail field: api_name",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "Detail field: json_path",
"maxLength": 1000
},
"supported_values": {
"type": "array",
"description": "Detail field: supported_values",
"items": {
"type": "string",
"description": "Detail Field: supported_values",
"maxLength": 255
},
"maxItems": 25
}
},
"required": [
"api_name",
"json_path",
"supported_values"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"Please give a valid calendar type"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Fiscal Year: Invalid Calendar Type Error"
},
"PutfiscalyearRequest": {
"type": "object",
"additionalProperties": false,
"description": "Request body schema",
"properties": {
"fiscal_year": {
"$ref": "#/components/schemas/FiscalYearNested",
"description": "Root key of the API (Required)"
}
},
"required": [
"fiscal_year"
]
},
"DetailsNested": {
"type": "object",
"additionalProperties": false,
"description": "Nested schema for details",
"properties": {
"id": {
"type": "string",
"description": "Field: id",
"maxLength": 255
}
}
},
"FiscalInvalidStartDateError": {
"type": "object",
"additionalProperties": false,
"description": "Invalid start_date",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"api_name": {
"type": "string",
"description": "Detail field: api_name",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "Detail field: json_path",
"maxLength": 1000
}
},
"required": [
"api_name",
"json_path"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"Please give a valid start_date"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Error Response Core"
},
"FiscalInvalidSurpluYearError": {
"type": "object",
"additionalProperties": false,
"description": "While configuring surplus week for future years.",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"NOT_ALLOWED"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"api_name": {
"type": "string",
"description": "Detail field: api_name",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "Detail field: json_path",
"maxLength": 1000
},
"supported_values": {
"type": "array",
"description": "Detail field: supported_values",
"items": {
"type": "integer",
"format": "int32",
"description": "Detail Field: supported_values"
},
"maxItems": 25
}
},
"required": [
"api_name",
"json_path",
"supported_values"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"Surplus week can be updated only for current year and next year"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Error Response Core"
},
"FiscalInvalidEndMonthConfigError": {
"type": "object",
"additionalProperties": false,
"description": "When display_based_on configured as 'end_month' for date lying 'January' or 'February'",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"api_name": {
"type": "string",
"description": "Detail field: api_name",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "Detail field: json_path",
"maxLength": 1000
}
},
"required": [
"api_name",
"json_path"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"Cannot configure end month as display based option for January and February for custom calendar type"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Error Response Core"
},
"FiscalYearNested1": {
"type": "object",
"additionalProperties": false,
"description": "Nested schema for fiscal_year",
"properties": {
"code": {
"type": "string",
"description": "Field: code",
"maxLength": 255
},
"details": {
"$ref": "#/components/schemas/DetailsNested"
},
"message": {
"type": "string",
"description": "Field: message",
"maxLength": 255
},
"status": {
"type": "string",
"description": "Field: status",
"maxLength": 255
}
}
},
"FiscalCompletedSurplusError": {
"type": "object",
"additionalProperties": false,
"description": "Updating or deleting surplus week for completed years",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"NOT_ALLOWED"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"api_name": {
"type": "string",
"description": "Detail field: api_name",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "Detail field: json_path",
"maxLength": 1000
}
},
"required": [
"api_name",
"json_path"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"Cannot edit surplus week for completed fiscal year"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"title": "Error Response Core"
},
"FiscalInvalidSurplusWeekError": {
"type": "object",
"additionalProperties": false,
"description": "Invalid surplus_week",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"description": "Error details with validation information",
"properties": {
"api_name": {
"type": "string",
"description": "Detail field: api_name",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "Detail field: json_path",
"maxLength": 1000
}
},
"required": [
"api_name",
"json_path"
]
},
"message": {
"type": "string",
"description": "Error message",
"enum": [
"invalid data"
]
},
"status": {
"type": "string",
"description": "Error status",
"enum": [
"error"
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-fiscal-year-openapi.json