Skip to main content

Getting Started

Lens APIs Overview​

The Poly Lens Management and Insights API supports all the features seen in the Poly Lens Portal. With access to these APIs, you can build applications to manage accounts, device inventory, device configuration, gather insights, and much more.

The Lens Management and Insight APIs (Lens APIs) are written in the GraphQL query language. Among others, one benefit to using GraphQL is the ability to send a single HTTP request and get back all the data your app needs. This means that any application capable of making HTTP requests can use the Lens APIs. GraphQL supports many languages, so whether you're building native or web-based applications, you'll be covered.

Before you begin, you will want to create an API Connection to generate a set of API credentials in the Poly Lens Portal. The GraphQL Playground will use this API Connection behind the scenes and if you're developing outside Poly tooling, you'll need them for authentication.

Create an API Connection in the Poly Lens Portal​

  1. Login to the Poly Lens Portal.
  2. Go to the ACCOUNT menu > Manage Accounts.
  3. Select an Account from the list.
  4. Select Integrations > API from the side menu.
  5. Select Create API Connection.
  6. Enter a Name and Role. Select Confirm.
  7. This new connection will populate the API Connection List.

Edit an API Connection​

  1. Go to the ACCOUNT menu > Manage Accounts.
  2. Select an Account from the list.
  3. Select Integrations > API from the side tabs.
  4. Select an API connection from the list (this enables the Edit button).
  5. Select Edit.
  6. Edit the connection as needed and select Confirm.

Delete an API Connection​

  1. Go to the ACCOUNT menu > Manage Accounts.
  2. Select an Account from the list.
  3. Select Integrations > API from the side tabs.
  4. Select an API connection from the list (this enables the Delete button).
  5. Select Delete.
  6. Select Delete to confirm. The API Connection is deleted from the list.

Accessing and Using the GraphQL Playground​

You can reference our documented and supported Poly Lens GraphQL APIs in the Use Cases & Supported APIs section

To access the GraphQL Playground, start by logging in with your Poly Lens credentials. By default, the GraphQL Playground is tied to your user's authentication. If your user can access multiple Poly Lens tenants, the response is aggregate data from those tenants.

If you need to test within a specific tenant, we've exposed an option to use Client Credentials - also known as the API Connection you created in the steps above. To select a set of credentials, select the Client Credentials toggle in the upper left hand corner of the page. Select the credentials to use from the dropdown list, and then continue on with your testing.

Poly GraphQL Client Credentials Option

From here, the GraphQL Playground is displayed ine three main sections:

  • Left: The Root, which shows all available query and mutations. Expanding the query or mutations dropdown shows the arguments, types, and fields for that object.
  • Middle: A section to write your GraphQL Queries/Mutations, add variables, and run your operation.
  • Right: A section to see the Response Object. You'll see the HTTP Response Status and have the option to view the object as JSON or in a table view.

Poly GraphQL Playground main page after authenticating

Developing Applications and Obtaining Credentials​

Before you start integrating Lens APIs into your application, you'll need to complete the following steps to retrieve an access_token. If you didn't create an API Connection in the steps above, you'll need to do that now.

Create an API Connection in the Poly Lens Portal

  1. Login to the Poly Lens Portal.
  2. Go to ACCOUNT menu > Manage Accounts.
  3. Select an Account from the list.
  4. Select Integrations > API from the side menu.
  5. Select Create API Connection.
  6. Enter a Name and Role. Select Confirm.
  7. This new connection will populate the API Connection List.

Exchange the API Connection Credential for an access_token​

Now that you have API Connection Credentials, you need to run a POST request to exchange the ClientID and Secret for an access_token. We've created a pre-populated cURL request to make it easy to copy and paste into your API tool of choice (Terminal, Postman, etc.). Alternatively, you can request the access_token directly from your custom application.

Obtaining the Pre-Populated cURL Request

  1. Login to the Poly Lens Portal.
  2. Go to ACCOUNT menu > Manage Accounts.
  3. Select an Account from the list.
  4. Select Integrations > API from the side menu.
  5. Select the Name of a Connection API from the list.
  6. This opens a popup with Sample Code.
  7. Copy this to your clipboard.

Generating an access_token

Paste the Sample Code into your API tool of choice. If you're using a CLI, it should look something like this (with your unique client_id and client_secret in those fields).

    Curl --request POST

    --url https://login.silica-prod01.io.lens.poly.com/oauth/token

    --header 'content-type: application/json'

    --data '{"client_id":"[insert client ID]","client_secret":"[Insert secret]","grant_type":"client_credentials"}'

After sending the request you should receive a HTTP 200 ok response containing:

  • access_token - a very long alphanumeric value
  • token_type - "Bearer"
  • expires_in - 86400

Use this access_token in your application and point it to the GraphQL endpoint - https://api.silica-prod01.io.lens.poly.com/graphql

Note: Tokens expire in 24 hours.

Get Help​

Please reach out for information about using, authenticating, and integrating with the Poly Lens APIs.