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:
- 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&
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:
|
| EMPTY | An EMPTY error could be due to one of the following:
|
| SIZE | A field exceeded its minimum or maximum size. |
| ACCESS_DENIED | The API Key in use does not have Global User Administrator permission. |