openapi: 3.0.0
info:
  title: Related Lists
  description: Related lists allow you to display custom data alongside existing records in Zoho Books. Create related lists to show information from external services or custom data sources on entity detail pages.
  contact: {}
  version: 1.0.0
servers:
  - url: https://www.zohoapis.com/books/v3
    description: API Endpoint
tags:
  - name: related-lists
    description: Related Lists Module
paths:
  /settings/relatedlists:
    get:
      tags:
        - related-lists
      operationId: list_related_lists
      summary: List related lists
      description: List all the related lists configured for a specific entity.
      parameters:
        - name: entity
          in: query
          description: Entity type to list related lists for (e.g., <code>invoice</code>, <code>contact</code>, <code>bill</code>, <code>expense</code>).
          required: true
          schema:
            type: string
          example: contact
        - name: status
          in: query
          description: Filter related lists by status.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-related-lists-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    post:
      tags:
        - related-lists
      operationId: create_related_list
      summary: Create a related list
      description: Create a new related list for a module.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-related-list-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-related-list-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /settings/relatedlists/{relatedlist_id}:
    get:
      tags:
        - related-lists
      operationId: get_related_list
      summary: Get a related list
      description: Get the details of a specific related list.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-related-list-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    put:
      tags:
        - related-lists
      operationId: update_related_list
      summary: Update a related list
      description: Update an existing related list.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-related-list-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-related-list-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.UPDATE
    delete:
      tags:
        - related-lists
      operationId: delete_related_list
      summary: Delete a related list
      description: Delete an existing related list.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-related-list-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.DELETE
    parameters:
      - name: relatedlist_id
        in: path
        required: true
        description: Unique identifier of the related list.
        schema:
          type: string
        example: '982000000567001'
      - $ref: '#/components/parameters/organization_id'
  /settings/relatedlists/{relatedlist_id}/status:
    put:
      tags:
        - related-lists
      operationId: update_related_list_status
      summary: Update related list status
      description: Activate or deactivate a related list.
      parameters:
        - name: active
          in: query
          description: Set to <code>true</code> to activate or <code>false</code> to deactivate the related list.
          required: true
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-related-list-status-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.UPDATE
    parameters:
      - name: relatedlist_id
        in: path
        required: true
        description: Unique identifier of the related list.
        schema:
          type: string
        example: '982000000567001'
      - $ref: '#/components/parameters/organization_id'
  /settings/relatedlists/reorder:
    post:
      tags:
        - related-lists
      operationId: reorder_related_lists
      summary: Reorder related lists
      description: Reorder the display order of related lists for a specific entity.
      parameters:
        - name: entity
          in: query
          description: Entity type to reorder related lists for.
          required: true
          schema:
            type: string
          example: contact
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/reorder-related-lists-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/reorder-related-lists-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
    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:
    related_list:
      type: object
      properties:
        relatedlist_id:
          type: string
          description: Unique identifier of the related list.
          example: '982000000567001'
        related_list_name:
          type: string
          description: Name of the related list.
          example: CRM Deals
        entity:
          type: string
          description: The module/entity this related list is associated with.
          example: contact
        description:
          type: string
          description: Description of the related list.
          example: Displays related CRM deals
        shared_with:
          type: string
          description: 'Sharing preference. Allowed values: <code>everyone</code> and <code>onlyme</code>.'
          example: everyone
        is_active:
          type: boolean
          description: Whether the related list is active.
          example: true
    create-related-list-request:
      type: object
      required:
        - related_list_name
        - entity
        - customfunction
      properties:
        related_list_name:
          type: string
          description: Name of the related list. <code>Max-length [25]</code>
          example: CRM Deals
        entity:
          type: string
          description: The module/entity this related list is associated with (e.g., <code>invoice</code>, <code>contact</code>, <code>bill</code>, <code>expense</code>).
          example: contact
        shared_with:
          type: string
          description: 'Sharing preference. Allowed values: <code>everyone</code> and <code>onlyme</code>.'
          example: everyone
        description:
          type: string
          description: Description of the related list. <code>Max-length [255]</code>
          example: Displays related CRM deals
        customfunction:
          type: object
          description: Custom function configuration that powers the related list data.
        is_execute:
          type: boolean
          description: Whether to execute the custom function immediately after creation.
          example: false
        entity_id:
          type: integer
          format: int64
          description: ID of a specific entity record to associate the related list with.
    update-related-list-request:
      type: object
      properties:
        related_list_name:
          type: string
          description: Name of the related list. <code>Max-length [25]</code>
          example: CRM Deals
        entity:
          type: string
          description: The module/entity this related list is associated with.
          example: contact
        shared_with:
          type: string
          description: 'Sharing preference. Allowed values: <code>everyone</code> and <code>onlyme</code>.'
          example: everyone
        description:
          type: string
          description: Description of the related list. <code>Max-length [255]</code>
          example: Displays related CRM deals
        customfunction:
          type: object
          description: Custom function configuration that powers the related list data.
        is_execute:
          type: boolean
          description: Whether to execute the custom function immediately after update.
          example: false
        entity_id:
          type: integer
          format: int64
          description: ID of a specific entity record to associate the related list with.
    create-related-list-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The related list has been created.
        related_list:
          $ref: '#/components/schemas/related_list'
    update-related-list-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The related list has been updated.
        related_list:
          $ref: '#/components/schemas/related_list'
    get-related-list-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        related_list:
          $ref: '#/components/schemas/related_list'
    list-related-lists-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        related_lists:
          type: array
          items:
            $ref: '#/components/schemas/related_list'
    delete-related-list-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The related list has been deleted.
    update-related-list-status-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The related list status has been updated.
    reorder-related-lists-request:
      type: object
      properties:
        reorder_lists:
          type: string
          description: Comma-separated list of related list IDs in the desired order. <code>Max-length [1000]</code>
          example: 982000000567001,982000000567002,982000000567003
    reorder-related-lists-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The related lists have been reordered.
  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
