<img height="1" width="1" style="display:none" src="https://www.facebook.com/tr?id=749646578535459&amp;ev=PageView&amp;noscript=1">
Skip to content
  • There are no suggestions because the search field is empty.

Using the KaiNexus API

Use Postman or another API application to test your connection and start making new API calls.

After you have completed the initial setup in KaiNexus and have your authentication Credentials, you can start interacting with the KaiNexus API. 

This guide covers the fundamental patterns used across all KaiNexus endpoints, including:

Ofie Profile PicPro Tip: For a refresher on initial configuration, visit API Setup in KaiNexus.  

Connection Environments

Depending on your organization’s location and your current goal (testing vs. production), you will use one of the following base URLs:

  • Production (Standard): https://api.kainexus.com
  • Production (EU): https://eu-prod.kainexus.com
  • Sandbox: https://sandbox.kainexus.com

Supported Request Methods

KaiNexus utilizes two primary HTTP methods:

  • GET: Used to retrieve information (e.g., exporting a list of Users or Items).
  • PUT: Used to both add new data and update existing data. 

Supported API Endpoints

The following table outlines the most common endpoints. Replace XXXXX with the appropriate ID value. Replace TYPE with the corresponding Impact Type.

Endpoint Purpose API Type
/api/public/v1/json/userList Export, create, and update users People
/api/public/v1/json/userList?id=XXXXX Export a specific User List People
/api/public/v1/json/itemList?id=XXXXX Export a specific Item List Item
/api/public/v1/json/itemList Create and update Items Item
/api/public/v1/json/itemList?fullSync=true Update Charts using JSON Chart
/api/public/v1/json/itemList?id=XXXXX&includeCharts=true Export a specific Chart List to JSON Chart 
/api/public/v1/excel/multiChartImport Update Charts using XLSX Chart 
/api/public/v1/excel/chartList?id=XXXXX Export Chart Lists using XLSX Chart 
/api/public/v1/json/networkLocationList Export, update, and create Network Locations Network 
/api/public/v1/json/networkLocation?id=XXXXX Export an individual Network Location Network
/api/public/v1/json/widget?id=XXXXX Export Widget values Widget
/api/public/v1/json/itemAttributeValueList Export, update, and create Attribute Values and Folders Attribute Value
/api/public/v1/json/itemAttributeValue?id=XXXXX Export an individual Attribute Value or Folder Attribute Value
/api/public/v1/json/impactValueList Export, update, and create Impact Values and Folders Impact Value
/api/public/v1/json/impactValue?id=XXXXX&impactValueType=TYPE Export an individual Impact Value or Folder Impact Value

Testing your API connection

Before writing complex scripts, verify your access using one of these two methods. 

Testing is especially important for large organizations that utilize firewalls and other security measures that might block the API connection. 

Method A: Web Browser (API Keys only)

  1. Paste a GET URL into your browser (e.g,. https://api.kainexus.com/api/public/v1/json/userList).
  2. When prompted for credentials:
    1. Username: api
    2. Password: Your API Key
  3. If successful, the browser will display the raw JSON data

Method B: API Client

You can use any standard API development tool (such as Postman, Insomnia, or a built-in IDE client) to verify your connection.

  1. Open your API client and configure a new request.
  2. Set up Authentication: 
    1. If using API Keys: 
      1. Set authentication type to Basic Auth.
      2. Username: api
      3. Password: Your API Key
    2. If using OAuth 2.0, reference Authenticating with OAuth 2.0 for details on how to use the Client ID and Client Secret to generate a token. 
  3. Set the HTTP request method to GET and enter your endpoint URL (e.g,. https://api.kainexus.com/api/public/v1/json/userList).
  4. Click Send. A successful connection will return a 200 OK status code, and the structured JSON data will populate the response body.

Status Codes

After your API request is sent, you will receive a Status Code that informs you whether the request was successful or if there was an error. 

Important codes include:

  • 200: The request was successful. This is what you are looking for. 
  • 401: Authorization error. Confirm your API Key is correct and it has permission to access the information you are requesting. 
  • 404: Connection error. Confirm you are using the correct URL. 
  • 400: Another type of error. View the response for more information.
    • Check whether the syntax in the body of your request is correct.
    • Check that you have the correct ID number. 

Pagination

For Item exports, two parameters can be specified to control paging:

  • offset: The (zero-based) offset of the first Item in the collection to return - optional - defaults to 0.
  • limit: The max number of Items to return - optional - defaults to 30000. It cannot exceed 30000.

For User Exports, two parameters can be specified to control paging:

  • offset: the (zero-based_ offset of the first item in the collection to return -optional- defaults to 0
  • limit: the max number of items to return - optional- defaults to 20000. It cannot exceed 20000. 

Ofie Profile PicExample: To retrieve the second page of 1000 users: https://api.kainexus.com/api/public/v1/json/userList?id=12345&amp

offset=1000&limit=1000 (replacing 12345 with the ID of the correct list of users)

Rate Limits

The KaiNexus API enforces rate limits to ensure system stability. We recommend limiting your rate of API calls to no more than 5 calls per minute. 

Recommended Reading:

Now that you understand the basics of KaiNexus API, we recommend checking out our documentation for the specific type of API call your organization will be using.