Skip to main content

How To Get 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. You will use these credentials to access the API Marketplace or to authenticate your custom application.

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 Poly API Marketplace​

Fully released and supported Lens GraphQL Management and Insights APIS are published in the Poly API Marketplace at https://developer.poly.com/. To Access, start by logging in with your Poly Lens credentials and navigate to the API listing that's appropriate for your use case - in this case you're looking for Lens in the menu on the left. If you don’t have a Poly Lens account, you can quickly create one by going to the Poly Lens Portal. The Lens API listings are grouped by common tasks such as: - Platform Management - Inventory Reporting - Device Controls.

Select a listing that applies to your use case. From there you're taken to a built-in API playground where you learn, understand, and experiment with each API.

The API Playground is broken out into three main sections:

  • Left: The Root, which shows the available query and mutations for the listing you selected. Expanding the query or mutations dropdown shows the arguments, types, and fields for that object.
  • Middle: A section to write your GraphQL Queries, add variables, and put your access_token in the HTTP Headers section. You'll also see a Test Endpoint button which will run your query.
  • Right: Code Snippets gives you the option to select a language and copy the query. Results gives you the option to see the Data Object returned from testing the endpoint.

Poly API Inventory Reporting API Documentation portal window

To Test your Endpoint​

  1. Build your query or mutation and adjust the variables as needed.
  2. Select Get Token – enter the Client ID and Client Secret from the Poly Lens API Connection tool. The rest of the fields should be prepopulated.
  3. Select Authorize.
  4. Select Test Endpoint - you should see a 200 Success message populate in Results. The Response Body is highlighted by default and returns an object containing data and errors. The data field is the response back from your query. As an additional resource, the error field contains a message with a link to access the interactive Poly Lens GraphQL Playground.
  5. Once satisfied with the results, grab the code snippet in any of the supported languages.

Poly API Inventory Reporting API Documentation window showing Authorization

Accessing and Using the Poly Lens GraphQL Playground​

Another available development tool is the Poly Lens GraphQL Playground. The playground provides a more immersive experience for:

  • Digging into the entire Poly Lens Schema
  • Grouping all available query & mutation fields into a single list
  • Easier construction of complex query and testing
  • A table view of the response object
  • Exporting the response object as JSON

Notes:

  • Unlike the Poly API Marketplace, the Poly Lens GraphQL playground is user authenticated. This means that queries and mutations in this playground are based on data that your user profile has access to.
  • Using Bearer access_token or client_id and secrets are not supported in this playground.

Developing Applications and Obtaining Credentials​

Before you start integrating your application, you'll need to complete the following steps to retrieve an access_token.

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.

Exchange the API Connection Credential for an access_token​

You need to run a POST request to exchange the API Connection Credentials (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 the 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​

For information about using, authenticating, and integrating with the Poly Lens API’s contact us here.