openapi: 3.0.0
info:
  title: Custom Views
  description: Custom views allow you to create and manage saved filters and column configurations for different modules in Zoho Books. Define criteria, select display columns, and organize views to quickly access the data you need.
  contact: {}
  version: 1.0.0
servers:
  - url: https://www.zohoapis.com/books/v3
    description: API Endpoint
tags:
  - name: custom-views
    description: Custom Views Module
paths:
  /customviews:
    get:
      tags:
        - custom-views
      operationId: list_custom_views
      summary: List custom views
      description: List all the custom views configured for the organization. You can filter by entity type.
      parameters:
        - name: entity_type
          in: query
          description: Filter custom views by entity type(s). Comma-separated values allowed (e.g., <code>invoice,contact</code>).
          required: false
          schema:
            type: string
          example: invoice
        - name: sub_entity_type
          in: query
          description: Filter by sub-entity type within the entity.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-custom-views-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    post:
      tags:
        - custom-views
      operationId: create_custom_view
      summary: Create a custom view
      description: Create a new custom view for a specific entity type. <br><strong>Note:</strong> Filter criteria fields must use the format <code>${entity.field_name}</code> (e.g., <code>${invoice.status}</code> for standard fields, <code>${invoice.cf_text_field}</code> for custom fields). Use <code>${PLACEHOLDER.EMPTY}</code> as the value to match empty/null fields.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-custom-view-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-custom-view-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /customviews/{customview_id}:
    get:
      tags:
        - custom-views
      operationId: get_custom_view
      summary: Get a custom view
      description: Get the details of a specific custom view.
      parameters:
        - name: entity_type
          in: query
          description: Entity type of the custom view.
          required: false
          schema:
            type: string
        - name: sub_entity_type
          in: query
          description: Sub-entity type within the entity.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-custom-view-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    put:
      tags:
        - custom-views
      operationId: update_custom_view
      summary: Update a custom view
      description: Update an existing custom view.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-custom-view-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-custom-view-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.UPDATE
    delete:
      tags:
        - custom-views
      operationId: delete_custom_view
      summary: Delete a custom view
      description: Delete an existing custom view.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-custom-view-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.DELETE
    parameters:
      - name: customview_id
        in: path
        required: true
        description: Unique identifier of the custom view.
        schema:
          type: string
        example: '982000000567001'
      - $ref: '#/components/parameters/organization_id'
  /customviews/reorder:
    post:
      tags:
        - custom-views
      operationId: reorder_custom_views
      summary: Reorder custom views
      description: Reorder the custom views for a specific entity type.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/reorder-custom-views-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/reorder-custom-views-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /createdviews:
    get:
      tags:
        - custom-views
      operationId: list_created_views
      summary: List created views
      description: List all the custom views created by the current user.
      parameters:
        - name: filter_by
          in: query
          description: 'Filter by entity type. Allowed values: <code>Entity.All</code>, <code>Entity.Invoice</code>, <code>Entity.Estimate</code>, <code>Entity.SalesOrder</code>, <code>Entity.CreditNote</code>, <code>Entity.Bill</code>, <code>Entity.Expense</code>, <code>Entity.PurchaseOrder</code>, etc.'
          required: false
          schema:
            type: string
          example: Entity.Invoice
        - name: sort_column
          in: query
          description: 'Sort column. Allowed values: <code>created_time</code> and <code>title</code>.'
          required: false
          schema:
            type: string
          example: created_time
        - name: sort_order
          in: query
          description: 'Sort order. Allowed values: <code>ascending</code> and <code>descending</code>.'
          required: false
          schema:
            type: string
          example: ascending
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-created-views-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /advancesearch:
    get:
      tags:
        - custom-views
      operationId: get_advance_search_fields
      summary: Get advance search fields
      description: Get the available fields and operators for advanced search/filter criteria for a specific entity type.
      parameters:
        - name: entity_type
          in: query
          description: Entity type to get search fields for.
          required: true
          schema:
            type: string
          example: invoice
        - name: from_entity_type
          in: query
          description: Source entity type for cross-entity search.
          required: false
          schema:
            type: string
        - name: for_lookup_criteria
          in: query
          description: Whether the search is for lookup criteria.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-advance-search-fields-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    parameters:
      - $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_view:
      type: object
      properties:
        customview_id:
          type: string
          description: Unique identifier of the custom view.
          example: '982000000567001'
        name:
          type: string
          description: Name of the custom view.
          example: Overdue Invoices
        entity_type:
          type: string
          description: Entity type of the custom view.
          example: invoice
        placeholder:
          type: string
          description: Placeholder identifier for the custom view.
          example: cv_overdue_invoices
        shared_with:
          type: string
          description: 'Sharing type of the custom view. Allowed values: <code>everyone</code>, <code>onlyme</code> and <code>selected</code>.'
          example: everyone
        is_favorite:
          type: boolean
          description: Whether this custom view is marked as favorite.
          example: true
        is_default:
          type: boolean
          description: Whether this is the default custom view for the entity type.
          example: false
        select_columns:
          type: array
          description: Columns to display in the view.
          items:
            type: object
            properties:
              field:
                type: string
                description: Field name of the column.
                example: invoice_number
              width:
                type: integer
                description: Column width in pixels.
                example: 200
              is_pinned:
                type: boolean
                description: Whether the column is pinned.
                example: false
        rule:
          type: object
          description: Filter rule defining criteria for the custom view.
          properties:
            criteria_string:
              type: string
              description: Expression combining criteria conditions using logical operators. Reference conditions by their <code>index</code>. E.g., <code>1</code>, <code>( 1 AND 2 )</code>, <code>( 1 OR 2 )</code>.
              example: ( 1 AND 2 )
            columns:
              type: array
              description: Filter criteria columns.
              items:
                type: object
                properties:
                  index:
                    type: integer
                    description: Index of the criteria.
                    example: 1
                  field:
                    type: string
                    description: 'Field identifier in the format. For standard fields: <code>status</code>, <code>balance</code>. For custom fields: <code>${invoice.cf_text_field}</code>.'
                    example: status
                  comparator:
                    type: string
                    description: Comparator operator.
                    example: equal
                  value:
                    type: string
                    description: Value to compare against.
                    example: overdue
    create-custom-view-request:
      type: object
      required:
        - name
        - entity_type
        - select_columns
      properties:
        name:
          type: string
          description: Name of the custom view.
          example: Overdue Invoices
        entity_type:
          type: string
          description: Entity type for the custom view (e.g., invoice, contact, bill, expense).
          example: invoice
        sub_entity_type:
          type: string
          description: Sub-entity type, if applicable.
        placeholder:
          type: string
          description: Placeholder identifier for the custom view.
          example: cv_overdue_invoices
        rule:
          type: object
          description: Filter rule for the view. Defines criteria conditions that records must match to appear in this custom view.
          properties:
            columns:
              type: array
              items:
                type: object
                properties:
                  index:
                    type: integer
                    example: 1
                  field:
                    type: string
                    description: 'Field identifier in the format. For standard fields: <code>status</code>, <code>balance</code>. For custom fields: <code>${invoice.cf_text_field}</code>.'
                    example: status
                  comparator:
                    type: string
                    example: equal
                  value:
                    type: string
                    example: overdue
            criteria_string:
              type: string
              example: (1)
        select_columns:
          type: array
          description: Columns to display in the view.
          items:
            type: object
            required:
              - field
            properties:
              field:
                type: string
                example: invoice_number
              width:
                type: integer
                example: 200
              is_pinned:
                type: boolean
                example: false
        shared_with:
          type: string
          description: 'Sharing type. Allowed values: <code>everyone</code>, <code>onlyme</code> and <code>selected</code>.'
          example: everyone
        is_favorite:
          type: boolean
          description: Mark as favorite.
          example: false
        is_default:
          type: boolean
          description: Set as default view.
          example: false
        column_orientation_type:
          type: string
          description: 'Column text orientation. Allowed values: <code>clip</code> and <code>wrap</code>.'
          example: clip
    update-custom-view-request:
      type: object
      properties:
        name:
          type: string
          description: Name of the custom view.
          example: Overdue Invoices
        rule:
          type: object
          description: Filter rule for the view.
          properties:
            columns:
              type: array
              items:
                type: object
                properties:
                  index:
                    type: integer
                  field:
                    type: string
                    description: 'Field identifier in the format. For standard fields: <code>status</code>, <code>balance</code>. For custom fields: <code>${invoice.cf_text_field}</code>.'
                  comparator:
                    type: string
                  value:
                    type: string
            criteria_string:
              type: string
        select_columns:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              width:
                type: integer
              is_pinned:
                type: boolean
        shared_with:
          type: string
          description: 'Sharing type. Allowed values: <code>everyone</code>, <code>onlyme</code> and <code>selected</code>.'
        is_favorite:
          type: boolean
        is_default:
          type: boolean
        column_orientation_type:
          type: string
          description: 'Column text orientation. Allowed values: <code>clip</code> and <code>wrap</code>.'
    reorder-custom-views-request:
      type: object
      required:
        - entity_type
        - order
      properties:
        entity_type:
          type: string
          description: Entity type to reorder views for.
          example: invoice
        sub_entity_type:
          type: string
          description: Sub-entity type, if applicable.
        order:
          type: array
          description: Ordered list of custom views.
          items:
            type: object
            required:
              - index
              - customview_id
            properties:
              index:
                type: integer
                description: New position index.
                example: 1
              customview_id:
                type: string
                description: Custom view ID.
                example: '982000000567001'
    create-custom-view-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The custom view has been created.
        custom_view:
          $ref: '#/components/schemas/custom_view'
    update-custom-view-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The custom view has been updated.
        custom_view:
          $ref: '#/components/schemas/custom_view'
    get-custom-view-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        custom_view:
          $ref: '#/components/schemas/custom_view'
    list-custom-views-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        custom_views:
          type: array
          items:
            $ref: '#/components/schemas/custom_view'
    delete-custom-view-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The custom view has been deleted.
    reorder-custom-views-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The custom views have been reordered.
    list-created-views-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        custom_views:
          type: array
          items:
            $ref: '#/components/schemas/custom_view'
    get-advance-search-fields-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        fields:
          type: array
          items:
            type: object
            properties:
              field_name:
                type: string
                description: Name of the field.
                example: status
              display_name:
                type: string
                description: Display name of the field.
                example: Status
              data_type:
                type: string
                description: Data type of the field.
                example: string
              comparators:
                type: array
                description: Available comparator operators for this field.
                items:
                  type: string
                example:
                  - equal
                  - not_equal
                  - contains
  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
