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.

Developing Applications​

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.

Obtaining Credentials​

Interacting with the Lens API requires an access_token. Before you start testing in the API Playground or integrating with your application, you'll need to complete the following steps:

  1. Create an API Connection in the Poly Lens Portal.
  2. Exchange the API Connection Credentials for an access_token.

Step 1 - 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 Integrations API List.

For each API Connection

FieldDescription
NameThe API Connection Name is the name assigned to this connection and it a link to the Sample Code.
Client IDThe Client ID can be copied to the clipboard to insert into the code.
SecretThe Secret viewed and copied to the clipboard to use as the client_secret in the code.
Date CreatedDisplays the date the API Connection was created.
RoleDisplays the Role assigned to the API Connection. Note: The Role can be modified in this field.

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.

Step 2 - 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

If you plan on testing in the Lens API Playground, copy the access_token (the alpha-numeric value between the "") - you'll need this for the next section.

If you're ready to start developing, you can put the 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.

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.

Once you've built your query or mutation, adjust the variables as needed, and grab the code snippet in any of the supported languages.

If you want to test the query or mutation you'll need to add your access_token to the HTTP Headers section.

  • Syntax: {"authorization": "Bearer access_token"}
  • Example with fakeaccess_token: {"authorization": "Bearer eyJz93a...k4laUWw"}

Click 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. The error field contains a message with a link to access the interactive Poly Lens GraphQL Playground.

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.

Get Help​

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