Query parameters

• page integer

  Page number

  Minimum value is 1. Default value is 1.

• page_size integer

  Items per page

  Minimum value is 1, maximum value is 200. Default value is 20.

• search string

  Search term. For organizations (distributors, resellers, customers), searches across name, description, and all custom_data fields (vat, address, city, contact, email, phone, language, notes, etc.). For systems, also searches across ipv4_address and ipv6_address.

  Minimum length is 1.

• sort_by string

  Field to sort distributors by

  Values are name, description, created_at, updated_at, suspended_at, or creator_name.

• sort_direction string

  Sort direction

  Values are asc or desc. Default value is asc.

• status array[string]

  Filter organizations by status. Supports multiple values.

  • enabled: not suspended and not deleted
  • suspended: suspended but not deleted
  • deleted: soft-deleted

  When "deleted" is combined with other statuses, both deleted and non-deleted matching records are returned.

  Values are enabled, suspended, or deleted.

• created_by array[string]

  Filter organizations by creator user ID or creator organization ID (exact match). Each provided ID is checked against both the user_id and organization_id fields of the organization creator (custom_data.createdByUser). Supports multiple values for checkbox filtering. Allowed values come from GET /api/filters/{distributors|resellers|customers}.

  Examples:

  • ?created_by=kyfy0tlnlk3l - matches organizations created by user with ID kyfy0tlnlk3l
  • ?created_by=obhdyclbfx4t - matches organizations created by users in organization obhdyclbfx4t
  • ?created_by=kyfy0tlnlk3l&created_by=obhdyclbfx4t - matches organizations created by the user OR by users in the organization
• organization_id array[string]

  Filter by owning organization Logto ID (custom_data.createdBy, the ownership key RBAC visibility walks). Supports multiple values; combine with include_hierarchy to cover a whole subtree. Results always stay within the caller's RBAC scope.

• include_hierarchy boolean

  When true (and organization_id is provided), each organization_id is expanded to the organization plus all its descendants (a distributor's resellers and their customers, a reseller's customers) before filtering

  Default value is false.

Responses

• 200 application/json

  Distributors retrieved successfully

  Hide response attributes Show response attributes object

  • code integer
  • message string
  • data object
    Hide data attributes Show data attributes object

    • distributors array[object]

      Organization with inline count statistics, returned in list responses

      Hide distributors attributes Show distributors attributes object

      Organization with inline count statistics, returned in list responses

      • id string

        Database UUID of the organization

      • logto_id string

        Logto organization ID (use this value for assignment operations)

      • name string

        Organization name

      • description string

        Organization description

      • custom_data object

        Custom organization data

        Additional properties are allowed.

      • suspended_at string(date-time) | null

        Timestamp when the organization was suspended. NULL means enabled, non-NULL means blocked/suspended.

      • suspended_by_org_id string | null

        Organization ID that caused cascade suspension (for resellers and customers only). NULL means directly suspended or not suspended. When set, the entity can only be reactivated by the parent organization that initiated the cascade.

      • rebranding_enabled boolean

        Whether rebranding is active for this organization (directly or inherited from parent)

      • rebranding_org_id string | null

        The organization ID that provides the rebranding (the org where rebranding is configured). Only present when rebranding_enabled is true.

      • created_by object

        Snapshot of the user who created an organization (distributor, reseller or customer). The user identity fields are point-in-time; organization_name is kept in sync when the referenced organization is renamed.

        Hide created_by attributes Show created_by attributes object

        • user_id string

          Logto ID of the user who created the organization

        • username string

          Username of the creator

        • name string

          Full name of the creator

        • email string

          Email of the creator

        • organization_id string

          Organization ID the creator belongs to

        • organization_name string

          Organization name the creator belongs to

        • on_behalf_of boolean

          True when the organization was attributed to a different organization via created_by_organization_id (the user acted on behalf of organization_name rather than belonging to it). Omitted when false.

      • promoted_from object

        Trace of the promotion that gave the organization its level. Distributors only, and only those promoted from reseller level (PATCH /resellers/{id}/promote) - omitted for an organization created at its level.

        Hide promoted_from attributes Show promoted_from attributes object

        • level string

          The organization level the promotion moved up from

        • at string(date-time)

          When the promotion ran

        • detached_from_organization_id string

          Logto ID of the organization that manages the promoted organization at its old level and drops it from its scope. Omitted when the organization carried no createdBy.

        • by object

          Snapshot of the user who ran the promotion

          Hide by attributes Show by attributes object

          • user_id string

            Logto ID of the user who created the organization

          • username string

            Username of the creator

          • name string

            Full name of the creator

          • email string

            Email of the creator

          • organization_id string

            Organization ID the creator belongs to

          • organization_name string

            Organization name the creator belongs to

          • on_behalf_of boolean

            True when the organization was attributed to a different organization via created_by_organization_id (the user acted on behalf of organization_name rather than belonging to it). Omitted when false.

      • systems_count integer

        Number of systems in this organization

      • resellers_count integer

        Number of resellers created by this distributor (distributors only)

      • customers_count integer

        Number of customers in the hierarchy (distributors and resellers only)

      • applications_count integer

        Number of certified applications (certification_level 4 or 5) in the hierarchy

    • pagination object
      Hide pagination attributes Show pagination attributes object

      • page integer

        Current page number

        Minimum value is 1.

      • page_size integer

        Number of items per page

        Minimum value is 1, maximum value is 200.

      • total_count integer

        Total number of items

        Minimum value is 0.

      • total_pages integer

        Total number of pages

        Minimum value is 0.

      • has_next boolean

        Whether there is a next page

      • has_prev boolean

        Whether there is a previous page

      • next_page integer | null

        Next page number if available

      • prev_page integer | null

        Previous page number if available

      • sort_by string | null

        Field used for sorting

      • sort_direction string | null

        Sort direction

        Values are asc or desc.

• 401 application/json

  Unauthorized - invalid or missing token

  Hide response attributes Show response attributes object

  • code integer
  • message string
  • data object | null
• 403 application/json

  Forbidden - insufficient permissions

  Hide response attributes Show response attributes object

  • code integer
  • message string
  • data object | null