Powered by Temper

JSON People API

The JSON User API can be used to export and import (create, update, delete) 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:

  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 delete a User, set their userType to "INACTIVE"

User Attributes

There are 4 types of attributes that can be assigned to a user:

  1. Titles
  2. Positions
  3. Employment Statuses
  4. Certifications

An organization may chose 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.

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

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": []
}
}

 

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

Error Code Explanation
NOT_FOUND  If receiving an error of NOT_FOUND, this 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  If receiving an error of EMPTY, this could be due to one of the following:
  • The JSON is empty.
  • A required field is blank.
SIZE  If receiving an error of SIZE, this could be due to one of the following:
  • A field exceeded its minimum or maximum size.
ACCESS_DENIED  If receiving an error of ACCESS_DENIED, this could be due to one of the following:
  • The API Key in use does not have Global User Administrator permission.

 

 

Have more questions? Submit a request