> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Poly Lens

> Connect Serval to Poly Lens so workflows can look up your Poly devices, rooms, and sites, and act on devices: reboot them, start or end calls, and collect logs.

## About Poly Lens

Poly Lens is HP's cloud service for managing Poly devices, such as video conferencing systems, and the rooms and sites they're placed in. This integration connects Serval to the Lens API so workflows can look up devices, rooms, and sites, and act on devices: reboot them, start or end calls, and collect logs.

**Authentication:** Poly Lens API credentials, a client ID and client secret created in the Poly Lens Admin Portal. Serval stores the secret encrypted and exchanges the credentials for a Lens access token, which it adds to requests server-side, so workflows never handle the credentials or the token. Serval sends the credentials only to the Poly token endpoint, `login.lens.poly.com`, and the token only to the Lens API, `api.silica-prod01.io.lens.poly.com`.

**Data sync:** No background sync starts when you connect, and the integration has no installable workflows. Data access is on demand through workflows.

## What the Poly Lens integration enables

| Capability | Description |
| - | - |
| Lens GraphQL access | Workflows use the "Poly Lens GraphQL request" action to send a GraphQL query or mutation to the Lens API. Serval's workflow builder works from a curated catalog of Lens operations, chosen from the use cases Poly documents for the Lens API. |
| Device inventory | Search, filter, and count devices, fetch devices by ID, and read a device's current settings. Device records include name, serial number, MAC address, external IP address, hardware family, software version, connection state, when the device was last detected, and its site and room. |
| Rooms, sites, and accounts | List the rooms and sites in an account, read a single room or site, list the Lens accounts the credentials can reach, and read an account's audit logs. |
| Device actions | Reboot a device, every device at a site, or a device group. Rename a device or move it to another site or room, update its operating system, or factory reset it. Add a device to Poly Lens or remove one from it. |
| Calls | Start a call from a device by dial string, or end a call on a device. |
| Diagnostics | Get a download link for a device's logs, or ask a device to upload a new log or diagnostics bundle. |
| Connection health check | One built-in check confirms Serval can exchange the credentials for a token and list the accounts they reach. |

## Get your credentials

Serval needs a set of Poly Lens API credentials. Creating them requires Administrator permissions in Poly Lens.

**1. Open API Credentials**

Sign in to the [Poly Lens Admin Portal](https://lens.poly.com/), open the **Account** menu, then go to **Account Settings** then **API Credentials**.

**2. Add credentials for Serval**

Select **Add New** and choose the data scope: **Just this account**, or **Multiple accounts** if Serval should work across several. Serval can reach only the accounts in scope.

**3. Name the credentials and choose a role**

Enter a name, for example `Serval`, and choose a role. Lens uses the role to control what the credentials can access, so choose one that covers only what your workflows need. Select **Confirm**.

**4. Copy the Client ID and Client Secret**

Copy both values from the new credentials. They aren't tied to your SSO user account.

> [!NOTE]
>
> The Poly Lens GraphQL request action can send any query or mutation that Lens accepts, including ones that reboot or factory reset devices, end calls, or remove devices from Poly Lens. The action doesn't restrict which operations it sends: the credentials' role and data scope in Lens are what limit what a workflow can change. A reboot ends all active calls on the device and takes it offline for several minutes. A factory reset resets all the device's settings and its connection to Poly Lens.

## Connect in Serval

**1. Open the Poly Lens connect form**

Add a new Poly Lens connection from your Serval integrations page. There's no address to enter: Serval always connects to the Poly Lens API, and the credentials' data scope decides which accounts it reaches.

**2. Enter the Client ID**

Paste the **Client ID** from the API credentials you created.

**3. Enter the Client Secret**

Paste the **Client Secret** shown with that Client ID. It's stored encrypted and shown masked after saving.

**4. Save, then check the health check**

Saving doesn't test the credentials. The health check runs automatically after you connect: confirm it passes before you build workflows on the connection.

> [!TIP]
>
> To rotate credentials, create new API credentials in Lens, edit the connection, enter both the new **Client ID** and the new **Client Secret**, and confirm the health check passes. Then delete the old credentials in Lens. If you change only the Client ID and leave the masked secret, Serval keeps the old secret, and Poly rejects the mismatched pair.

## Verifying the connection

The connection ships one health check that makes a live call to Poly Lens:

* **List Poly Lens Accounts:** exchanges the credentials for an access token, then asks Lens for one account the credentials can reach. On success: "Successfully reached Poly Lens (accounts visible: 1)."

When the check passes, the credentials are valid and Serval can reach the Lens API. Because the check asks for a single account, the count is at most 1, however many accounts the credentials reach. The check doesn't test whether the role can read devices or run device actions.

## Gotchas and troubleshooting

> [accordion] The health check passes with 0 accounts visible
>
> Lens accepted the credentials but returned no account for them. Check the credentials' data scope and role in Lens.

> [accordion] The health check fails
>
> The check reports "Unable to reach Poly Lens." An error saying the credentials were rejected means Poly refused the Client ID and Client Secret pair. Confirm that both values come from the same API credentials under **Account Settings** then **API Credentials**, rather than an SSO sign-in, and that the credentials still exist in Lens.

> [accordion] Revoking credentials in Lens
>
> Serval reuses each access token until shortly before its 24-hour expiry, and requests a new token as soon as you save different credentials on the connection. Deleting the API credentials in Lens stops Serval from getting new tokens, but whether Lens still accepts a token it already issued is up to Poly. To stop Serval's access right away, also delete the connection in Serval or replace its credentials.

> [accordion] Any GraphQL error fails the workflow step
>
> Lens answers a failed operation with HTTP 200 and a list of errors. Even when part of the data came back, the Poly Lens GraphQL request action turns that list into a step error that starts with "Poly Lens GraphQL request returned errors."

> [accordion] Large queries can exceed Poly's cost limits
>
> Lens prices each request in points. A single request must stay under 10,000 points, and requests draw from a 100,000-point balance that resets every 60 seconds. Select only the fields a workflow needs, and page through large inventories instead of requesting everything at once.

> [accordion] Device search returns 10 devices per page by default
>
> `deviceSearch` returns 10 devices unless you set `params.pageSize`, up to 5,000. To read every device, pass `pageInfo.nextToken` back as `params.nextToken` until `pageInfo.hasNextPage` is false. Send the same `pageSize` on every page: Lens returns an error if it changes after the first request, including dropping it to fall back to the default.

> [accordion] Some Lens queries are deprecated
>
> Lens marks the `devices`, `searchDevices`, `rooms`, and `sites` queries as deprecated. In workflows you write yourself, use `deviceSearch`, `roomData`, and `siteData` instead.

> [accordion] Outbound network access
>
> Serval calls two Poly hosts: `login.lens.poly.com` for access tokens and `api.silica-prod01.io.lens.poly.com` for the Lens API. If the Serval deployment or worker serving the connection restricts outbound traffic, allow HTTPS to both.

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Poly Lens integration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.