How to List Groups and Group Devices via OMS API

Audience: Third-party platform integrators / developers
Objective: Retrieve groups available to your account and list devices inside a selected group via OMS API.
Scope: Get groups -> copy groupdId -> list devices in one group.

Prerequisites

· OMS Account & OMS Token (OMS Portal -> System Settings -> API).

· Base URL: Your OMS API gateway base (e.g., https://oms-apiservice.optoma.com/)

· Auth: Send your token in header x-oms-token.

· Pagination: num must be >= 1 and size must be between 1 and 100.

· groupdId: Use the exact groupdId field returned by GET /groups as the {groupId} path value for the next API.

· Access behavior: GET /groups/{groupId}/devices may return 404 when the group does not exist or you do not have access.

High-level Flow

  1. List groups: call GET /groups to retrieve the groups visible to your token.

  2. Pick the target group: copy the exact groupdId value from the selected row.

  3. List devices in that group: call GET /groups/{groupId}/devices with the selected groupdId.

  4. Use returned device fields: hardwareIdentity.deviceId is typically the next identifier used by device-specific APIs.

API Details & Examples

Summary

Recommended way to use these APIs

  1. Start with GET /groups: use it to build your group picker or filter list, and keep both name and groupdId.

  2. Use the exact groupdId value: the next API expects {groupId}, and the response field is spelled groupdId in the OpenAPI schema.

  3. Use pageInfo for paging: do not guess whether more data exists; rely on pageInfo.num, pageInfo.size, pageInfo.items, and pageInfo.pages.

  4. Use deviceId for follow-on device APIs: after listing group devices, the most important next-step identifier is hardwareIdentity.deviceId.

  5. Expect access-related 404 on the second API: GET /groups/{groupId}/devices may return 404 for either an unknown group or a group you cannot access.