openapi: 3.0.0
info:
  title: Roles
  description: Roles define the permissions a user holds in an organization. Use these endpoints to list, create, update, delete, and toggle the status of roles in Zoho Inventory.
  contact: {}
  version: 1.0.0
servers:
  - url: https://www.zohoapis.com/inventory/v1
    description: API Endpoint
tags:
  - name: roles
    description: Roles Module
paths:
  /roles:
    post:
      tags:
        - roles
      operationId: create_role
      summary: Create a role
      description: Create a role with a set of entity-wise permissions for your organization.
      parameters:
        - name: portal_id
          in: query
          description: Unique ID of the portal.
          required: false
          schema:
            type: string
          example: '982000000123005'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-a-role-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-a-role-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.CREATE
    get:
      tags:
        - roles
      operationId: list_roles
      summary: List Roles
      description: Get the list of all roles in the organization. Filter and sort the results using the available query parameters.
      parameters:
        - name: sort_column
          in: query
          description: 'Sort roles. Allowed Values: <code>role_name</code> and <code>role_description</code>.'
          required: false
          schema:
            type: string
          example: role_name
        - name: description
          in: query
          description: Search roles by description.
          required: false
          schema:
            type: string
          example: Manage day-to-day operations
        - name: created_by
          in: query
          description: Filter roles by the user IDs that created them. Pass a comma-separated list of user IDs.
          required: false
          schema:
            type: string
          example: '982000000554041'
        - name: modified_by
          in: query
          description: Filter roles by the user IDs that last modified them. Pass a comma-separated list of user IDs.
          required: false
          schema:
            type: string
          example: '982000000554041'
        - name: created_date
          in: query
          description: Filter roles by created date in <code>yyyy-mm-dd</code> format. Use <code>created_date_start</code> and <code>created_date_end</code> for a range.
          required: false
          schema:
            type: string
            format: date
          example: '2024-01-15'
        - name: modified_date
          in: query
          description: Filter roles by last modified date in <code>yyyy-mm-dd</code> format. Use <code>modified_date_start</code> and <code>modified_date_end</code> for a range.
          required: false
          schema:
            type: string
            format: date
          example: '2024-01-15'
        - name: created_date_start
          in: query
          description: Filter roles created on or after this date. Format <code>yyyy-mm-dd</code>.
          required: false
          schema:
            type: string
            format: date
          example: '2024-01-01'
        - name: created_date_end
          in: query
          description: Filter roles created on or before this date. Format <code>yyyy-mm-dd</code>.
          required: false
          schema:
            type: string
            format: date
          example: '2024-01-31'
        - name: modified_date_start
          in: query
          description: Filter roles last modified on or after this date. Format <code>yyyy-mm-dd</code>.
          required: false
          schema:
            type: string
            format: date
          example: '2024-01-01'
        - name: modified_date_end
          in: query
          description: Filter roles last modified on or before this date. Format <code>yyyy-mm-dd</code>.
          required: false
          schema:
            type: string
            format: date
          example: '2024-01-31'
        - name: rule
          in: query
          description: Advanced search rule passed as a JSON object string. Supports <code>columns</code> (array of <code>{index, field, value, comparator}</code> where <code>comparator</code> is <code>with</code> or <code>with_out</code>) and <code>criteria_string</code>.
          required: false
          schema:
            type: string
          example: '{"columns":[{"index":0,"field":"role_name","value":"Manager","comparator":"with"}],"criteria_string":"1"}'
        - name: role_type
          in: query
          description: Filter roles by role type.
          required: false
          schema:
            type: string
          example: custom
        - name: portal_id
          in: query
          description: Unique ID of the portal.
          required: false
          schema:
            type: string
          example: '982000000123005'
        - name: page
          in: query
          description: Page number to be fetched. Default value is 1.
          required: false
          schema:
            type: integer
            default: 1
          example: 1
        - name: per_page
          in: query
          description: Number of records to be fetched per page. Default value is 10.
          required: false
          schema:
            type: integer
            default: 10
          example: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-roles-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.READ
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /roles/{role_id}:
    get:
      tags:
        - roles
      operationId: get_role
      summary: Retrieve a role
      description: Get the details of a role, including its entity-wise permissions.
      parameters:
        - name: role_type
          in: query
          description: Type of the role.
          required: false
          schema:
            type: string
          example: custom
        - name: portal_id
          in: query
          description: Unique ID of the portal.
          required: false
          schema:
            type: string
          example: '982000000123005'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-a-role-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.READ
    put:
      tags:
        - roles
      operationId: update_role
      summary: Update a role
      description: Update the details of a role.
      parameters:
        - name: portal_id
          in: query
          description: Unique ID of the portal.
          required: false
          schema:
            type: string
          example: '982000000123005'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-a-role-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-a-role-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.UPDATE
    delete:
      tags:
        - roles
      operationId: delete_role
      summary: Delete a role
      description: Delete a role from your organization. Roles assigned to active users cannot be deleted.
      parameters:
        - name: portal_id
          in: query
          description: Unique ID of the portal.
          required: false
          schema:
            type: string
          example: '982000000123005'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-a-role-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.DELETE
    parameters:
      - name: role_id
        in: path
        required: true
        description: Unique identifier of the role.
        schema:
          type: string
        example: '982000000006005'
      - $ref: '#/components/parameters/organization_id'
  /roles/{role_id}/active:
    post:
      tags:
        - roles
      operationId: activate_role
      summary: Activate a role
      description: Activate a role to make it available for assignment to users.
      parameters:
        - $ref: '#/components/parameters/organization_id'
        - name: role_id
          in: path
          description: Unique identifier of the role.
          required: true
          schema:
            type: string
          example: '982000000006005'
        - name: portal_id
          in: query
          description: Unique ID of the portal.
          required: false
          schema:
            type: string
          example: '982000000123005'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/role-status-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.CREATE
  /roles/{role_id}/inactive:
    post:
      tags:
        - roles
      operationId: deactivate_role
      summary: Deactivate a role
      description: Deactivate a role to prevent it from being assigned to users.
      parameters:
        - $ref: '#/components/parameters/organization_id'
        - name: role_id
          in: path
          description: Unique identifier of the role.
          required: true
          schema:
            type: string
          example: '982000000006005'
        - name: portal_id
          in: query
          description: Unique ID of the portal.
          required: false
          schema:
            type: string
          example: '982000000123005'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/role-status-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.CREATE
components:
  parameters:
    organization_id:
      name: organization_id
      description: 'ID of the organization. Note: This value is a set of numeric characters.'
      in: query
      required: true
      schema:
        type: string
      example: '10234695'
  schemas:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/role-response'
    role-response:
      type: object
      description: Details of a single role.
      properties:
        role_id:
          description: Unique ID of the role.
          type: string
          example: '982000000006005'
        role_name:
          description: Name of the role. Max-length [200].
          type: string
          example: Manager
        description:
          description: Description of the role. Max-length [2000].
          type: string
          example: Can view, create, and edit transactions across modules.
        display_name:
          description: Display name of the role. Max-length [200].
          type: string
          example: Manager
        role_type:
          description: Type of the role.
          type: string
          example: custom
        access_type:
          description: Access type of the role.
          type: string
          example: full
        permissions:
          description: Entity-wise permissions assigned to the role.
          type: array
          items:
            $ref: '#/components/schemas/role-permission'
        segmentation_details:
          description: Segmentation details applied to the role.
          type: array
          items:
            $ref: '#/components/schemas/role-segmentation-detail'
    role-permission:
      type: object
      description: Permissions configured for a single entity within a role.
      required:
        - entity
      properties:
        entity:
          description: Name of the entity (module). Max-length [200].
          type: string
          example: invoices
        can_create:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: true
        can_edit:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: true
        can_view:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: true
        can_delete:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: false
        can_approve:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: false
        can_edit_locked_records:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: false
        full_access:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: false
        apply_segment:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: false
        vendor_bank_account:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: false
        assign_owner:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: false
        more_permissions:
          description: Entity-specific additional permissions.
          type: array
          items:
            $ref: '#/components/schemas/entity-specific-permission'
        field_permissions:
          description: Field-level permissions for the entity.
          type: array
          items:
            $ref: '#/components/schemas/field-permission'
    entity-specific-permission:
      type: object
      required:
        - permission
        - is_enabled
      properties:
        permission:
          description: Name of the entity-specific permission.
          type: string
          example: can_export
        is_enabled:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: true
    field-permission:
      type: object
      required:
        - field_name
        - permission
      properties:
        field_name:
          description: Name of the field.
          type: string
          example: vendor_bank_account
        permission:
          description: 'Permission level for the field. Allowed Values: <code>write</code>, <code>read</code>, and <code>none</code>.'
          type: string
          example: read
    role-segmentation-detail:
      type: object
      properties:
        entity_id:
          description: Unique ID of the entity.
          type: string
          example: '982000000045123'
        entity_type:
          description: Type of the entity. Max-length [50].
          type: string
          example: customer
        is_segmentation_enabled:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: true
        can_allow_viewing:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: true
        can_show_unassigned:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: false
        supported_entity_list:
          description: List of supported entities for segmentation.
          type: array
          items:
            $ref: '#/components/schemas/supported-entity'
    supported-entity:
      type: object
      required:
        - entity_name
        - is_enabled
      properties:
        entity_name:
          description: 'Name of the supported entity. Allowed Values: <code>customer</code>, <code>vendor</code>, and <code>item</code>.'
          type: string
          example: customer
        is_enabled:
          description: Allowed values <code>true</code> and <code>false</code>.
          type: boolean
          example: true
    page:
      description: Current page number.
      type: integer
      example: 1
    per_page:
      description: Number of records per page.
      type: integer
      example: 10
    has_more_page:
      description: Indicates whether more pages are available.
      type: boolean
      example: false
    sort_column:
      description: Column used for sorting.
      type: string
      example: role_name
    sort_order:
      description: 'Order used to sort. Allowed Values: <code>A</code> (ascending) and <code>D</code> (descending).'
      type: string
      example: A
    applied_filter:
      description: Filter applied to the list.
      type: string
      example: Status.All
    report_name:
      description: Name of the report currently run.
      type: string
      example: Roles
    page_context:
      type: object
      properties:
        page:
          $ref: '#/components/schemas/page'
        per_page:
          $ref: '#/components/schemas/per_page'
        has_more_page:
          $ref: '#/components/schemas/has_more_page'
        report_name:
          $ref: '#/components/schemas/report_name'
        applied_filter:
          $ref: '#/components/schemas/applied_filter'
        sort_column:
          $ref: '#/components/schemas/sort_column'
        sort_order:
          $ref: '#/components/schemas/sort_order'
    list-roles-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        roles:
          type: array
          items:
            $ref: '#/components/schemas/role-response'
        page_context:
          $ref: '#/components/schemas/page_context'
    get-a-role-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        role:
          $ref: '#/components/schemas/role-response'
    create-a-role-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: The role has been created.
          readOnly: true
        role:
          $ref: '#/components/schemas/role-response'
    update-a-role-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: The role information has been updated.
          readOnly: true
        role:
          $ref: '#/components/schemas/role-response'
    delete-a-role-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: The role has been deleted.
          readOnly: true
    role-status-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
    create-a-role-request:
      required:
        - role_name
      type: object
      properties:
        role_name:
          description: Name of the role. Max-length [200].
          type: string
          example: Manager
        description:
          description: Description of the role. Max-length [2000].
          type: string
          example: Can view, create, and edit transactions across modules.
        display_name:
          description: Display name of the role. Max-length [200].
          type: string
          example: Manager
        access_type:
          description: Access type for the role.
          type: string
          example: full
        role_type:
          description: Type of the role. Max-length [200].
          type: string
          example: custom
        permissions:
          description: Entity-wise permissions for the role.
          type: array
          items:
            $ref: '#/components/schemas/role-permission'
        segmentation_details:
          description: Segmentation details for the role.
          type: array
          items:
            $ref: '#/components/schemas/role-segmentation-detail'
    update-a-role-request:
      type: object
      allOf:
        - $ref: '#/components/schemas/create-a-role-request'
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoInventory.settings.CREATE: Create Settings
            ZohoInventory.settings.READ: Read Settings
            ZohoInventory.settings.UPDATE: Update Settings
            ZohoInventory.settings.DELETE: Delete Settings
