Network API

JSON Network API

A JSON Network Location API can be used to create, update, or delete Network Locations in the system.

Two Line OfieREQUIRED: Your organization must have the API Module enabled to perform the actions mentioned in this article. Reach out to your Customer Success Manager if you're interested in this module.


A JSON Network API helps you automate changes to your organization's Network Locations. It is particularly helpful for large organizations with complex or frequently changing Networks.

Ofie Profile PicThe Network is used to organize people and work into distinct functional areas of an organization. It consists of many Network Locations organized in a nested hierarchy. You can learn more about the Network in this support article


You can use a JSON Network API to:

  • Export a list of your organization's Network Locations in JSON format. You can export all Locations in your organization or individual Locations.

Ofie Profile PicPRO TIP: Exporting the Network in JSON format is a great way to reference the correct JSON format before creating new or updating existing Locations. 

  • Update every part of an existing Network Location.
  • Create new Network Locations. 
  • Delete existing Network Locations.

How does it work? 

KaiNexus provides an endpoint where you can access Network information. To make a call, you will need an API Key and an API tool. 

Ofie Profile PicPRO TIP: We recommend using Postman for your API calls. It's easy to use and works well with KaiNexus API. 

Authentication

API Keys are used for authenticating 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. 

Two Line OfieMake sure your API Key has been granted the Quality Administrator permission so that it can complete the Network API calls.

Exporting Network Locations

After authentication, you can make your first JSON Network API call. We recommend starting with a GET request to retrieve a list of Network Locations in proper JSON format. This will be useful as a reference for the correct JSON format when updating or creating Locations. 


KaiNexus's Network Export APIs allow you to export:

To export a list of all Network Locations, make a GET request to this URL:

https://api.kainexus.com/api/public/v1/json/networkLocationList

    To export an individual Network Location, execute a GET request to this URL:

    https://api.kainexus.com/api/public/v1/json/networkLocation?id=XXXXX
    • Replace XXXXX with the Network Location's ID.
    • You can find a Location's ID by adding an ID column to the Network administration page.
    The Network admin page with an arrow pointing to the ID column

    Importing and updating Network Locations

    After you have exported Network Locations in JSON format, you can use that code as a reference to update or create new Locations.

    To update or create multiple Network Locations, execute a PUT request to this URL:

    https://api.kainexus.com/api/public/v1/json/networkLocationList


    To update or create an individual Network Location, execute a PUT request to this URL:

    https://api.kainexus.com/api/public/v1/json/networkLocation


    The API will recognize whether the Network Locations in your request already exist or if a new Location needs to be created.

    • If an ID is provided, the existing Network Location with that ID will be updated.
    • If an ID is not provided, but a Network Location exists with the name specified, the Network Location with that name will be updated.
    • If no ID is specified and no Location with the specified name exists, a new Network Location with that name will be created.

    Deleting Network Locations

    To delete a Network Location, include "delete": true in the request.

    In the following example, the Location with the ID 683 will be deleted.

    {
        "item": {
            "id": 683,
            "delete": true
        }
    }

    Example: Curl Script for exporting a list of Network Locations

    curl -s -D - --user api:APIKEY https://api.kainexus.com/api/public/v1/json/networkLocationList -d @FILEPATH -X PUT -H "Content-Type: application/json"
    • Replace APIKEY with the API Key generated in KaiNexus

    Example: JSON format for importing a list of Network Locations:

    {
        "items": [
        {
                "id": 5,
              "name": "KaiNexus Corporation",
                "levelType": {
                  "id": 4,
                  "name": "System"
                }
            },
            {
                "id": 29,
                "name": "Corporate",
                "levelType": {
                  "id": 1,
                  "name": "Department"
                },
                "parent": {
                  "id": 5,
                  "name": "KaiNexus Corporation"
                }
            },
            {
              "id": 16,
              "name": "Accounting",
                "levelType": {
                  "id": 12,
                  "name": "Administration"
                },
                "parent": {
                  "id": 29,
                  "name": "Corporate"
                }
          }
      ]
    }

    Example: JSON format for importing an individual Network Location

    {
        "item": {
            "id": 29,
            "name": "Corporate",
            "levelType": {
                "id": 1,
                "name": "Department"
            },
            "parent": {
                "id": 5,
              "name": "KaiNexus Corporation"
            }
        }
    }

    Error Messages

    Failed updates will return an error containing a code and message that can be referenced below:

      Error Code Explanation
      NOT_FOUND  A NOT_FOUND error could be due to one of the following:
      • A Network Location could not be found by ID.
      • A Parent Location was not found by ID or name.
      • A Level Type was not found by ID or name.
      EMPTY  An EMPTY error could be due to one of the following:
      • The JSON request is empty.
      • The required field (i.e. the Location's name) is blank.
      SIZE A field exceeded its minimum or maximum size.
      NOT_EMPTY

      If receiving an error of NOT_EMPTY, this could be due to one of the following:

      • You are deleting a Network Location that is the parent of another Network Location.
      • You are deleting a Network Location that has users currently assigned to it.
      ACCESS_DENIED The API Key in use does not have Quality Administrator permission.