LENS provides a variety of read-only API endpoints that can be used to retrieve data directly from your LENS environment including huddle usage data, users and corresponding board membership information, and a wide array of Voice page data from each of your LENS boards.

Authentication

All API requests require a Personal Access Token, or PAT, sent in the token request header that allows LENS to determine if a request is valid. Once you have been given the neccesary permissions to use the API from the LENS Support Team, you will be able to generate your PAT from your LENS profile page.

Read more about how to create your first token here. A PAT will only be shown to you once and will remain active for one year unless you delete it sooner.

Important: Treat your PAT like a password: use only your own token, store it securely, and do not share it in emails, screenshots, public documents, or request URLs. If you think your PAT may have been exposed, simply generate a new one. This will invalidate any previous PAT that you may have created.

Methods

Each of the endpoints will be built on the base of the LENS url you normally use to sign in to your LENS account. In this documentation, {LENS_URL} represents the web address for your organization’s LENS environment.

For example, if you normally sign in to LENS at:

https://example.safeandreliable.care

then your API requests would begin with:

https://example.safeandreliable.care/api/v2

The LENS API currently supports GET requests only.

Responses

All endpoints return JSON and are designed for reporting, analytics, and for use in tools and dashboards you design outside of LENS. Successful responses include a data array and a metadata object that describes the endpoint used, the number of items returned in the response, and the parameters that were provided in the request.

{
  "data": [],
  "metadata": {
    "endpoint": "cards",
    "count": 0,
    "filters": {
      "groupNames": [],
      "includeArchived": false,
      "days": 7
    }
  }
}

Common Request Parameters

Some endpoints support shared query parameters. All three are optional, and the defaults will be used if they are omitted from the request body. As you dive into the API, we recommend starting with the LENS Boards (Entities) endpoint, as this is where you can retrieve group names to filter endpoint results by LENS unit.

Parameter	Description	Default
`groupNames`	Optional comma-separated list of entity group names used to limit results. If omitted, the request returns data for all entities in the environment. Use the 'Get Entities' endpoint to find valid group names.	`[]`
`includeArchived`	Optional `boolean` value for endpoints that support archived data retrieval.	`false`
`days`	Optional date range value for endpoints that support date filtering. Must be between `1` and `365` days.	`7`

Error Responses

If a request is interrupted or otherwise cannot be completed, it returns an error. Within the error response you receive details that help you understand the reason for the response and how to resolve it. These details can also help the LENS support team troubleshoot, if needed.

Error Code	Description
`Unauthorized`	The PAT was missing, inactive, or not recognized. Please confirm that the token header is included and that the PAT is valid.
`Token expired`	The PAT has expired. You can generate a fresh PAT from your LENS profile page.
`Insufficient permissions`	You can work with the LENS Support Team to ensure you have the necessary permissions to generate tokens and use the API.
`METHOD_NOT_ALLOWED`	The request included an unsupported HTTP method. Currently, only `GET` requests are allowed.
`INTERNAL_SERVER_ERROR`	An unexpected server error occurred. Try the request again later or reach out to our support team if the problem persists.
`GROUP_NAME_NOT_FOUND`	One or more of the group names you provided in your request were not recognized. Make sure the group names you provide match what is provided by the 'Get Entities' endpoint.
`INVALID_INCLUDE_ARCHIVED`	The `includeArchived` parameter must be `true` or `false` if included in a request.
`INVALID_DAYS`	The days parameter must be a valid integer between `1` and `365`.

Looking for more support?

We’re here to help — email us at LENSsupport@safeandreliablecare.com or click the Help button on your LENS board.

LENS API Explained