People API

JSON User API

The JSON User API can be used to export and update an organization's users. This includes creating new users, inactivating users, and updating profiles.

Making Requests

Requests to KaiNexus User API are sent to different variations of the following URL:

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

GET requests to the URL will export user information, and PUT requests to the URL will allow you to update user information or add new users. 

Authentication

The username will be "api" and the password will be the API Key. See this article for information on obtaining the API Key. 

Exporting User Information

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

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

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

https://api.kainexus.com/api/public/v1/json/user?id=XXXXX
  • Replace "XXXXX" with the User ID.

To export a specific List of Users, execute a GET request to this URL:

https://api.kainexus.com/api/public/v1/json/userList?id=XXXXX

To populate a User's badges, include the includeBadges=true param with any user GET requests. 

Updating User Information

To update or add multiple Users, execute a PUT request to this URL:

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

To update or add 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:

  1. If an ID is provided, the existing User with that ID will be updated.
  2. If an ID is not provided, and a User exists with the username specified, the user with that username will be updated.
  3. If no ID is specified and no user exists with the specified username, a new User will be created.
  4. Network Locations can be referenced by name or ID and at least one is required for a user.
  5. Roles can be referenced by name or ID.
  6. 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:

  1. Titles
  2. Positions
  3. Employment Statuses
  4. 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.