openapi: 3.2.0 info: title: Global Picklists API description: Global sets are collections of picklist values that can be associated with multiple picklists across modules. Example use cases include maintaining a consistent set of status values or priority levels across different modules in a CRM system. By using global sets, administrators can ensure uniformity and simplify the management of picklist values, as any updates to the global set automatically reflect in all associated picklists. This feature enhances data integrity and reduces redundancy, making it easier to manage and analyze data across various modules. 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: description: API Version default: v8 security: - iam-oauth2-schema: - ZohoCRM.settings.global_picklist.ALL - ZohoCRM.settings.ALL - ZohoCRM.settings.global_picklist.READ - ZohoCRM.settings.global_picklist.CREATE - ZohoCRM.settings.global_picklist.UPDATE - ZohoCRM.settings.global_picklist.DELETE tags: - name: Global Picklists paths: /settings/global_picklists/{id}/actions/replace_picklist_values: post: summary: Replace picklist values for a global picklist operationId: replacePicklistValues tags: - Global Picklists description: Schedules or executes replacement of picklist values for the specified global picklist. You can specify either `id`, `display_value`, or both for `old_value` and `new_value`. If both are provided, the system validates them for consistency. The `from` (old) value can be non-existent in the current picklist, but the `to` (new) value must be in the **used** state of the picklist option. parameters: - $ref: '#/components/parameters/Id' requestBody: required: true content: application/json: schema: type: object description: Request body for replacing picklist values in a global picklist. properties: replace_picklist_values: type: array description: Array of picklist value replacement pairs. maxItems: 1 items: type: object description: Represents a single picklist value replacement pair. properties: old_value: type: object description: The existing picklist value to be replaced. properties: id: $ref: '#/components/schemas/Id' display_value: $ref: '#/components/schemas/PickListDisplayValue' additionalProperties: false new_value: type: object description: The new picklist value that will replace the old one. properties: id: $ref: '#/components/schemas/Id' display_value: $ref: '#/components/schemas/PickListDisplayValue' additionalProperties: false required: - old_value - new_value additionalProperties: false required: - replace_picklist_values additionalProperties: false responses: '200': description: OK — Replacement completed immediately since the global set is not associated with any fields. content: application/json: schema: type: object description: Response object for immediate replacement completion. properties: replace_picklist_values: type: array description: Array of replacement operation results. maxItems: 1 items: type: object description: Replacement operation result object. properties: code: type: string description: Indicates that the replacement operation completed successfully. maxLength: 50 details: type: object description: Additional details about the replacement operation. additionalProperties: false message: type: string description: Human-readable message about the replacement operation. maxLength: 255 status: type: string description: Status of the replacement operation. maxLength: 50 required: - code - details - message - status additionalProperties: false required: - replace_picklist_values additionalProperties: false '202': description: Accepted — Replacement scheduled successfully for associated fields. content: application/json: schema: description: response object for scheduled replacement of picklist values. type: object properties: replace_picklist_values: maxItems: 1 type: array description: Array of replacement operation results. items: type: object description: Replacement operation result object. properties: code: type: string description: Indicates that the replacement operation has been scheduled. maxLength: 50 details: type: object description: Additional details about the replacement operation. properties: job_id: type: string description: The ID of the scheduled replacement job. maxLength: 100 required: - job_id additionalProperties: false message: type: string description: Human-readable message about the replacement operation. maxLength: 255 status: type: string description: Status of the replacement operation. maxLength: 50 required: - code - details - message - status additionalProperties: false required: - replace_picklist_values additionalProperties: false '400': description: Bad Request — Invalid data, missing fields, ambiguity, or disallowed actions, or if limits exceeded. content: application/json: schema: oneOf: - type: object description: Error response with array of replacement operation errors. properties: replace_picklist_values: type: array description: Array of replacement operation error details. maxItems: 1 items: type: object description: Replacement operation error object. additionalProperties: false properties: code: type: string description: Error code indicating the type of validation or constraint failure. enum: - INVALID_DATA - AMBIGUITY_DURING_PROCESSING - MANDATORY_NOT_FOUND - EXPECTED_FIELD_MISSING - NOT_ALLOWED - LIMIT_EXCEEDED details: type: object description: Additional error-specific details. additionalProperties: false properties: api_name: type: string description: name of the field causing the error. maxLength: 100 json_path: type: string description: JSON path to the field causing the error. maxLength: 255 ambiguity_due_to: type: array description: if both id and display_value are provided and they don't match maxItems: 30 items: type: object description: Field causing ambiguity. additionalProperties: false properties: api_name: type: string description: name of the ambiguous field. maxLength: 100 json_path: type: string description: JSON path to the ambiguous field. maxLength: 255 expected_fields: type: array description: List of expected fields that are missing. maxItems: 10 items: type: object description: Expected field information. additionalProperties: false properties: api_name: type: string description: name of the expected field. maxLength: 100 json_path: type: string description: JSON path to where the field is expected. maxLength: 255 limit_due_to: type: array description: List of picklist values that caused the limit to be exceeded. maxItems: 10 items: type: object description: Field causing limit exceeded error. additionalProperties: false properties: api_name: type: string description: API name of the field causing limit issue. maxLength: 100 json_path: type: string description: JSON path to the field causing limit issue. maxLength: 255 limit: type: integer description: The maximum allowed limit that has been exceeded. if this exists in details, limit_due_to will also be present. format: int32 message: type: string description: Human-readable message describing the error. maxLength: 255 status: type: string description: Status of the error response. enum: - error required: - code - details - message - status required: - replace_picklist_values additionalProperties: false - type: object description: Top-level validation or system restriction errors. additionalProperties: false properties: code: type: string description: Error code indicating invalid data or disallowed action. enum: - INVALID_DATA - NOT_ALLOWED details: type: object description: Additional details about the top-level error. additionalProperties: false properties: resource_path_index: type: integer description: Index in the resource path indicating the error location. format: int32 enum: - 2 required: - resource_path_index message: type: string description: Human-readable error message describing the issue. maxLength: 255 status: type: string description: Status of the error response. maxLength: 50 required: - code - message - status '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' security: - iam-oauth2-schema: - ZohoCRM.settings.global_picklist.ALL /settings/global_picklists/{id}/actions/replaced_values: get: summary: Get picklist values which is in replace scheduler operationId: getReplacedValues tags: - Global Picklists description: Retrieves picklist values that are currently being replaced through a replace scheduler for the given global picklist ID. parameters: - $ref: '#/components/parameters/Id' responses: '200': description: OK — Replace scheduler in progress. Returns values which are currently being replaced. content: application/json: schema: type: object description: Response object containing picklist values that are currently being replaced. properties: replaced_values: type: array description: Array of picklist values that are currently being replaced. maxItems: 500 items: type: object description: Object representing a replaced picklist value. properties: display_value: $ref: '#/components/schemas/PickListDisplayValue' reference_value: $ref: '#/components/schemas/PickListReferenceValue' required: - display_value - reference_value additionalProperties: false required: - replaced_values additionalProperties: false '204': description: No Content — No replace scheduler is currently in progress for the given picklist. '400': description: Bad Request — Invalid data or not allowed action. content: application/json: schema: description: Error response object containing code, message, details, and status. type: object properties: code: type: string enum: - INVALID_DATA - NOT_ALLOWED description: 'Error code indicating the failure reason. Possible values: INVALID_DATA, NOT_ALLOWED.' details: description: Details about the error, including the resource path index. type: object properties: resource_path_index: type: integer enum: - 2 format: int32 description: This value is always 2. required: - resource_path_index additionalProperties: false message: type: string maxLength: 250 description: 'Describes the reason for the failure. Examples: ''the id given seems to be invalid'' or ''global picklist deletion in progress.''' status: type: string description: Status of the error response. maxLength: 100 required: - code - message - status additionalProperties: false '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' security: - iam-oauth2-schema: - ZohoCRM.settings.global_picklist.READ /settings/global_picklists/{id}/actions/associations: get: summary: To get the fields associated with a global picklist operationId: getGlobalPickListFieldAssociations tags: - Global Picklists description: Retrieves associations of picklist values with modules, fields, and layouts for a given global picklist ID. parameters: - $ref: '#/components/parameters/Id' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - name: include_inner_details in: query required: false description: 'Comma-separated list of nested details to include (e.g., `module.plural_label,module.module_name,layouts.status`). Allowed values: module.plural_label, module.module_name, layouts.status.' schema: type: array items: type: string description: Allowed values for including nested details in the response. enum: - module.plural_label - module.module_name - layouts.status maxItems: 3 style: form explode: false responses: '200': description: Successful response containing picklist associations. content: application/json: schema: type: object description: Response object containing associations of global picklist fields and modules. properties: associations: type: array description: List of associations between global picklist and fields/modules/layouts. maxItems: 1000 items: type: object description: Association object for a global picklist field. properties: field: type: object description: Field details associated with the global picklist. properties: api_name: $ref: '#/components/schemas/ApiName' id: $ref: '#/components/schemas/Id' field_label: $ref: '#/components/schemas/FieldLabel' required: - api_name - id additionalProperties: false module: type: object description: Module details associated with the field. properties: plural_label: $ref: '#/components/schemas/ModulepluralLabel' api_name: $ref: '#/components/schemas/ApiName' module_name: $ref: '#/components/schemas/ModuleName' id: $ref: '#/components/schemas/Id' required: - api_name - id additionalProperties: false layouts: type: array description: List of layouts associated with the field. maxItems: 100 items: type: object description: Layout details. properties: name: $ref: '#/components/schemas/LayoutName' id: $ref: '#/components/schemas/Id' status: type: string description: Layout status. maxLength: 20 required: - name - id additionalProperties: false required: - field - module - layouts additionalProperties: false info: type: object description: Pagination and record info for associations response. properties: per_page: type: integer description: Number of records per page. format: int32 count: type: integer description: Number of records returned. format: int32 page: type: integer description: Current page number. format: int32 more_records: type: boolean description: Whether more records are available. required: - per_page - count - page - more_records additionalProperties: false required: - associations - info additionalProperties: false '204': description: if there is no picklist field associated with the global picklist. '400': description: Bad Request — Invalid data or not allowed action. content: application/json: schema: description: Error response object containing code, message, details, and status. type: object properties: code: type: string enum: - INVALID_DATA - NOT_ALLOWED description: 'Error code indicating the failure reason. Possible values: INVALID_DATA, NOT_ALLOWED.' details: type: object description: Additional details about the error. properties: resource_path_index: type: integer const: 2 description: This value is always 2. format: int32 required: - resource_path_index additionalProperties: false message: maxLength: 250 type: string description: 'Describes the reason for the failure. Examples: ''the id given seems to be invalid'' or ''global picklist deletion in progress.''' status: type: string description: Status of the error response. maxLength: 100 required: - code - message - status additionalProperties: false '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' security: - iam-oauth2-schema: - ZohoCRM.settings.global_picklist.READ components: parameters: Page: name: page in: query required: false description: 'Page number (positive integer). Default: 1.' schema: type: integer format: int32 minimum: 1 default: 1 Id: name: id in: path required: true description: Numeric id of the resource. schema: type: string format: int64 PerPage: name: per_page in: query required: false description: 'Number of records per page. Default and maximum: 200.' schema: type: integer minimum: 1 maximum: 200 default: 200 format: int64 schemas: Id: type: string description: Id of the resource. format: int64 PickListReferenceValue: type: string maxLength: 120 description: Reference value of the picklist field. LayoutName: type: string description: Name of the layout maxLength: 50 ModulepluralLabel: type: string description: Plural label of the module. maxLength: 25 PickListDisplayValue: type: string maxLength: 120 description: The picklist display value(translated value if translation enabled). FieldLabel: type: string description: Name of the field label. maxLength: 100 ApiName: type: string description: API name of the resource. It will start with alphabets and can contain alphanumeric characters and underscores. pattern: ^[A-Za-z][A-Za-z0-9_]*$ maxLength: 50 ModuleName: type: string description: Name of the module maxLength: 100 responses: Forbidden: description: Forbidden content: application/json: schema: type: object description: Error response object containing code, message, details, and status. properties: code: type: string description: Error code indicating the type of error. maxLength: 50 message: type: string description: Human-readable error message. maxLength: 255 details: type: object description: Additional details about the error. properties: permissions: type: array description: List of permissions required to access the resource. items: type: string enum: - Crm_Implied_Customize_Zoho_CRM description: Permission required to access the resource. maxItems: 1 additionalProperties: false status: type: string description: Status of the error response. enum: - error maxLength: 100 required: - code - message - details - status additionalProperties: false InternalServerError: description: Internal Server Error content: application/json: schema: type: object description: Internal server error response object containing code, message, details, and status. properties: code: type: string description: Error code indicating the type of error. maxLength: 50 message: type: string description: Human-readable error message. maxLength: 255 details: type: object description: Additional details about the error. additionalProperties: true status: type: string description: Status of the error response. enum: - error required: - code - message - details - status additionalProperties: false 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.settings.global_picklist.ALL: Access to all global picklist operations ZohoCRM.settings.global_picklist.READ: Access to read global picklist details ZohoCRM.settings.global_picklist.CREATE: Access to create global picklists ZohoCRM.settings.global_picklist.UPDATE: Access to update global picklists ZohoCRM.settings.global_picklist.DELETE: Access to delete global picklists ZohoCRM.settings.ALL: Access to all settings operations