JSON User API

The JSON User API can be used to export and import (create, update, inactivate) an Organization's Users using JSON format.

To export a list of all Users, execute a GET request to this URL:

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

To populate the badges of a user, include the includeBadges=true param with the request.

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

https://api.kainexus.com/api/public/v1/json/user?id=XYZ

(where XYZ is the ID of the User)

To update a list of Users, execute a PUT request to this URL:

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

To update an individual User, execute a PUT request to this URL:

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

Example Curl Script:

curl -s -D - --user api:APIKEY https://api.kainexus.com/api/public/v1/json/userList -d @FILEPATH -X PUT -H "Content-Type: application/json"

See The API Module for more information on how to configure API keys.

Things to note:

If an ID is provided, the existing User with that ID will be updated.
If an ID is not provided, and a User exists with the username specified, the user with that username will be updated.
If no ID is specified and no user exists with the specified username, a new User will be created.
Network Locations can be referenced by name or ID and at least one is required for a user.
Roles can be referenced by name or ID.
To inactivate a User, set their userType to "INACTIVE"

User Attributes

There are 4 types of attributes that can be assigned to a User.

By default, these are:

Titles
Positions
Employment Statuses
Certifications

An organization may choose to rename these attributes. However, in JSON format, the attribute names will remain constant as "titles", "positions", "employmentStatuses", and "certifications" respectively. If your organization has renamed these attributes, work with your Customer Experience representative to understand how they map to the desired attribute names.

If you are trying to assign a value for one of these User attributes that has not already been created in your system, you can do so by including the following in your JSON request: "createIfMissing": true.

Example:

{
    "items": [
        {
            "id": XXXXX,
            "certifications": [
            	{
            		"name": "Product Expert",
                    "createIfMissing": true
            	}
            ]
        }
    ]
}

User Types

User Type must be set to one of the following values:

SUPERUSER 

GENERAL 

CAPTURE 

OFFLINE 

WALLBOARD 

SETUP 

KIOSK 

INACTIVE

Persona

Persona must be set to one of the following values:

FRONTLINE 

LEADER 

EXECUTIVE 

CI_EXPERT 

OTHER

Pagination

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.

Example: 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)

Example JSON format for a list of Users:

{
  "items": [
    {
      "id": 39,
      "username": "james",
      "firstName": "James",
      "lastName": "Montague",
      "email": "",
      "userType": "SUPERUSER",
      "workNumber": "",
      "mobileNumber": "555-123-0948",
      "pagerNumber": "",
      "networkLocations": [
        {
          "id": 23,
          "name": "Transportation"
        }
      ],
      "roles": [
        {
          "id": 18,
          "name": "KaiNexus General User"
        },
        {
          "id": 40,
          "name": "Location Leader"
        },
        {
          "id": 19,
          "name": "KaiNexus Reports User"
        }
      ],
      "titles": [
        {
          "id": 6,
          "name": "MD"
        }
      ],
      "positions": [],
      "employmentStatuses": [
        {
          "id": 8,
          "name": "Full Time"
        }
      ],
      "certifications": [],
      "badges": []
    },
    {
      "id": 40,
      "username": "arnold",
      "firstName": "Arnold",
      "lastName": "Smith",
      "email": "",
      "userType": "SUPERUSER",
      "workNumber": "",
      "mobileNumber": "",
      "pagerNumber": "",
      "networkLocations": [
        {
          "id": 2,
          "name": "Austin"
        },
        {
          "id": 23,
          "name": "Transportation"
        }
      ],
      "roles": [
        {
          "id": 40,
          "name": "Location Leader"
        },
        {
          "id": 19,
          "name": "KaiNexus Reports User"
        },
        {
          "id": 18,
          "name": "KaiNexus General User"
        }
      ],
      "titles": [
        {
          "id": 21,
          "name": "Facilities Engineer"
        }
      ],
      "positions": [],
      "employmentStatuses": [
        {
          "id": 8,
          "name": "Full Time"
        }
      ],
      "certifications": [],
      "badges": [
        {
          "id": 2,
          "name": "10th Improvement"
        }
      ]
    },
    {
      "id": 41,
      "username": "karen",
      "firstName": "Karen",
      "lastName": "Rogers",
      "email": "",
      "userType": "SUPERUSER",
      "workNumber": "",
      "mobileNumber": "555-234-8521",
      "pagerNumber": "",
      "networkLocations": [
        {
          "id": 23,
          "name": "Transportation"
        }
      ],
      "roles": [
        {
          "id": 18,
          "name": "KaiNexus General User"
        },
        {
          "id": 19,
          "name": "KaiNexus Reports User"
        },
        {
          "id": 40,
          "name": "Location Leader"
        }
      ],
      "titles": [
        {
          "id": 3,
          "name": "CRNA"
        }
      ],
      "positions": [],
      "employmentStatuses": [
        {
          "id": 8,
          "name": "Full Time"
        }
      ],
      "certifications": [],
      "badges": []
    },
    {
      "id": 42,
      "username": "pam",
      "firstName": "Pam",
      "lastName": "Avery",
      "email": "",
      "userType": "SUPERUSER",
      "workNumber": "",
      "mobileNumber": "555-423-0894",
      "pagerNumber": "",
      "networkLocations": [
        {
          "id": 2,
          "name": "Austin"
        },
        {
          "id": 23,
          "name": "Transportation"
        }
      ],
      "roles": [
        {
          "id": 18,
          "name": "KaiNexus General User"
        },
        {
          "id": 40,
          "name": "Location Leader"
        },
        {
          "id": 44,
          "name": "Persona: Project Leader Role"
        },
        {
          "id": 19,
          "name": "KaiNexus Reports User"
        }
      ],
      "titles": [
        {
          "id": 5,
          "name": "PHD"
        }
      ],
      "positions": [],
      "employmentStatuses": [
        {
          "id": 8,
          "name": "Full Time"
        }
      ],
      "certifications": [],
      "badges": []
    },
    {
      "id": 43,
      "username": "nick",
      "firstName": "Nick",
      "lastName": "Monroe",
      "email": "",
      "userType": "SUPERUSER",
      "workNumber": "",
      "mobileNumber": "555-0929-0031",
      "pagerNumber": "",
      "networkLocations": [
        {
          "id": 2,
          "name": "Austin"
        },
        {
          "id": 23,
          "name": "Transportation"
        }
      ],
      "roles": [
        {
          "id": 19,
          "name": "KaiNexus Reports User"
        },
        {
          "id": 18,
          "name": "KaiNexus General User"
        }
      ],
      "titles": [
        {
          "id": 6,
          "name": "MD"
        }
      ],
      "positions": [],
      "employmentStatuses": [
        {
          "id": 8,
          "name": "Full Time"
        }
      ],
      "certifications": [],
      "badges": []
    }
  ]
}

Example JSON format for an individual User (id=49):

{
  "item": {
    "id": 49,
    "username": "lauren",
    "firstName": "Lauren",
    "lastName": "Villa",
    "email": "",
    "userType": "SUPERUSER",
    "workNumber": "",
    "mobileNumber": "555-215-6629",
    "pagerNumber": "",
    "networkLocations": [
      {
        "id": 23,
        "name": "Transportation"
      }
    ],
    "roles": [
      {
        "id": 18,
        "name": "KaiNexus General User"
      },
      {
        "id": 19,
        "name": "KaiNexus Reports User"
      }
    ],
    "titles": [],
    "positions": [],
    "employmentStatuses": [],
    "certifications": [],
    "badges": []
  }
}

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 User could not be found by ID A Role was not found by ID or name A Network Location was not found by ID or name A User Attribute was not found by ID or name A Language was not found by ID or name
EMPTY	An EMPTY error could be due to one of the following: The JSON is empty. A required field is blank.
SIZE	A field exceeded its minimum or maximum size.
ACCESS_DENIED	The API Key in use does not have Global User Administrator permission.