openapi: 3.0.0
info:
  title: Custom Actions
  description: Custom actions allow you to define automated actions that can be triggered by workflows, custom buttons, or other events in Zoho Books. Configure email notifications, field updates, webhooks, and custom function executions as part of your automation.
  contact: {}
  version: 1.0.0
servers:
  - url: https://www.zohoapis.com/books/v3
    description: API Endpoint
tags:
  - name: custom-actions
    description: Custom Actions Module
paths:
  /settings/customactions:
    get:
      tags:
        - custom-actions
      operationId: list_custom_actions
      summary: List custom actions
      description: List all the custom actions configured for the organization.
      parameters:
        - name: filter_by
          in: query
          description: Filter custom actions by entity type.
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: Page number for pagination. Default is 1.
          required: false
          schema:
            type: integer
            default: 1
          example: 1
        - name: per_page
          in: query
          description: Number of records per page.
          required: false
          schema:
            type: integer
            default: 10
          example: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-custom-actions-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    post:
      tags:
        - custom-actions
      operationId: create_custom_action
      summary: Create a custom action
      description: Create a new custom action.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-custom-action-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-custom-action-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /settings/customactions/{customaction_id}:
    get:
      tags:
        - custom-actions
      operationId: get_custom_action
      summary: Get a custom action
      description: Get the details of a specific custom action.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-custom-action-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    put:
      tags:
        - custom-actions
      operationId: update_custom_action
      summary: Update a custom action
      description: Update an existing custom action.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-custom-action-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-custom-action-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.UPDATE
    delete:
      tags:
        - custom-actions
      operationId: delete_custom_action
      summary: Delete a custom action
      description: Delete an existing custom action.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-custom-action-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.DELETE
    parameters:
      - name: customaction_id
        in: path
        required: true
        description: Unique identifier of the custom action.
        schema:
          type: string
        example: '982000000567001'
      - $ref: '#/components/parameters/organization_id'
components:
  parameters:
    organization_id:
      name: organization_id
      description: ID of the organization
      in: query
      required: true
      schema:
        type: string
      example: '10234695'
  schemas:
    custom_action:
      type: object
      properties:
        customaction_id:
          type: string
          description: Unique identifier of the custom action.
          example: '982000000567001'
        action_name:
          type: string
          description: Name of the custom action.
          example: Notify Sales Team
        entity:
          type: string
          description: The module/entity this action is associated with.
          example: invoice
        action_type:
          type: string
          description: Type of action (e.g., email, field_update, webhook, custom_function).
          example: email
        is_active:
          type: boolean
          description: Whether the custom action is active.
          example: true
    create-custom-action-request:
      type: object
      required:
        - action_name
        - entity
      properties:
        action_name:
          type: string
          description: Name of the custom action.
          example: Notify Sales Team
        entity:
          type: string
          description: The module/entity this action is associated with.
          example: invoice
        action_type:
          type: string
          description: Type of action.
          example: email
    update-custom-action-request:
      type: object
      properties:
        action_name:
          type: string
          description: Name of the custom action.
          example: Notify Sales Team
        action_type:
          type: string
          description: Type of action.
          example: email
    create-custom-action-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The custom action has been created.
        custom_action:
          $ref: '#/components/schemas/custom_action'
    update-custom-action-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The custom action has been updated.
        custom_action:
          $ref: '#/components/schemas/custom_action'
    get-custom-action-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        custom_action:
          $ref: '#/components/schemas/custom_action'
    list-custom-actions-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        custom_actions:
          type: array
          items:
            $ref: '#/components/schemas/custom_action'
    delete-custom-action-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The custom action has been deleted.
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoBooks.settings.CREATE: Create Settings
            ZohoBooks.settings.UPDATE: Update Settings
            ZohoBooks.settings.READ: Read Settings
            ZohoBooks.settings.DELETE: Delete Settings
