JSON Widget API

Call the value of Item, People, and Impact Widgets.

JSON Widget API helps you call the value of the following Widgets: 

• Item Count
• People Count
• Impact Unit
• Total Financial Impact
• Time Savings (Hours)
• ROI

By exporting a Widget value, you have access to data in KaiNexus that would otherwise be inaccessible through API. 

How does it work? 

KaiNexus provides an endpoint for accessing Widget data. You will need an API Key and an API tool to make a call. 

Authentication

API Keys are used to authenticate calls to KaiNexus API. Check out this article for instructions on how you can find your organization's API Keys and copy them to your clipboard. 

If you are using Postman, select Basic Auth as the Authorization Type.

• Enter "api" as the username.
• Enter the API Key as the password. 

Exporting a Widget value

After authentication, you can make your first Widget API call. 

To export a Widget value, make a GET request to this URL: 

https://api.kainexus.com/api/public/v1/json/widget?id=XXXXXX

• Replace XXXXX with the Widget's ID. 
• You can find a Widget's ID by hovering over the Widget's title. 
  

Example

Here is an example of the JSON body for an Item Count Widget export: 

{
    "value": 18.0,
    "statistics": {
        "startDate": "2024-05-23T15:39:42.228+0000",
        "endDate": "2024-05-23T15:39:42.282+0000",
        "durationSeconds": 0
    }
}

Arguments

You can further configure the Widget value you export by passing a Location or Date through the API call. The API will return a count meeting the Widget and argument criteria. 

Location Arguments

You can add the following Location arguments to your API Call:

• locationIds
• locationType
• locationAndBelow

Use the "locationIds" argument to call a People Count, Item Count, or Impact for a specific Network Location. For example: 

https://api.kainexus.com/api/public/v1/json/widget?id=12345&locationIds=XXXXX

• Delineate multiple Locations with a comma.
• Replace XXXXX with the Network Location ID. To find a Network Location ID: 
  • Navigate to Admin > Organization > Network.
  • Add an ID column to the list of Locations. 
    
• The "locationIds" argument is applicable for People, Item, and Impact Widgets.

Add the "locationType" argument to for Item Count and Impact Widgets to specify whether an Item must have your specified Location as the Originating or Responsible Location to be included in the Widget's value. For example: 

https://api.kainexus.com/api/public/v1/json/widget?id=12345&locationIds=XXXXX&locationType=Responsible

• Options are "Responsible" and "Originating" 
• Leaving this argument null gives both results. 
• Location Type will not have any effect on People Count Widgets. 

Add the "locationAndBelow" argument for People Count, Item Count, and Impact Widgets to specify whether Locations nested below your specified Location should be included in the Widget's value. For example: 

https://api.kainexus.com/api/public/v1/json/widget?id=12345&locationIds=XXXXX&locationAndBelow=False

• Options are "True" and "False"
• Leaving this argument null results in "True" 

Date Arguments

You can add the following date arguments for Item Count, People Count, and Impact Widgets:

• createDateStart
• createDateEnd
• completeDateStart
• completeDateEnd

These arguments allow you to filter which Item data is counted in the Widget value based on the date range in which the Item was created or completed. 

Example of how to call Items created in a certain date range:

https://api.kainexus.com/api/public/v1/json/widget?id=XXXXX&createDateStart=2023-04-29T16:30:40.000&createDateEnd=2023-05-29T16:30:40.000

Example of how to call People created after a certain date: 

https://sandbox-kainexus.kainexus.com/api/public/v1/json/widget?id=XXXXX&createDateStart=2023-04-29T16:30:40.000

Example of how to call a Time Savings Impact for Items completed before a certain date:

https://api.kainexus.com/api/public/v1/json/widget?id=XXXXX&completeDateEnd=2023-04-29T16:30:40.000

Rate Limits

The following rate limits apply: 

• 10 requests per 10 second window
• 60 requests per 1 minute window
• 1000 requests per 1 hour window

Helpful Tips

• Applying a Location Filter, Board Filter, or Board Quick Filter in KaiNexus will not change the value called by the API. The API only respects the filters set directly on your Widget. 
• The API Key for all Widget API calls must include the View Report Data permission.
• The API Key for calling the following Widgets must include the View Impact permission:
  • Impact Unit
  • Total Financial Impact
  • Time Savings (Hours)
  • ROI

Error Codes

Recommended Reading

• Widget Cards
• Getting Started with API
• Create an API Key