JSON People API

A JSON People API can be used to create, update, or inactivate users in KaiNexus.

A JSON People API helps you automate the addition and upkeep of your organization's KaiNexus users. It is particularly helpful for large organizations that regularly have people enter and leave their organization. Using API to automate user account maintenance can save a lot of time for administrators.

You can use a JSON People API to:

• Export a list of your organization's users in JSON format. You can export all users in your organization, individual People List Cards, or individual users. 

• Update every part of an existing user's profile.
• Create new users. This makes it easy to give new employees KaiNexus accounts. 

How does it work? 

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

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. 

Exporting user information

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

KaiNexus's People Export APIs allow you to export:

• A list of all users in the organization
• An individual user
• A specific People List Card

To export a list of every user in your organization, make a GET request to the following URL:

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

• If your organization has fewer than 20,000 users, this call will retrieve a list of all your users in JSON format. 
• If your organization has more than 20,000 users, this call will retrieve a list of the first 20,000 users in your organization in alphabetical order. 

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's ID.
• You can find a user's ID by adding an ID column to the People section or the User Management Admin page. 
  
  

To export a specific People List Card, execute a GET request to this URL:

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

• Replace "XXXXX" with the People List Card's ID. 
• You can find a People List Card's ID by hovering over the Card's header. A tooltip will appear that shows the Card's ID.

• If the Card includes fewer than 20,000 users, this call will retrieve a list of all its users in JSON format. 
• If the Card includes more than 20,000 users, this call will retrieve a list of its first 20,000 users in order. 

Importing and updating users

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

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

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

Here is an example of JSON format for importing a list of Users:

{
   "items": [
      {
         "id": 39,
         "username": "james",
         "firstName": "James",
         "lastName": "Montague",
         "email": "",
         "userType": "GENERAL",
         "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": "GENERAL",
         "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"
            }
         ]
      }
   ]
}

To update or add an individual user, execute a PUT request to this URL:

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

Here is an example of the JSON format for importing a single user: 

{
  "item": {
    "id": 314,
    "username": "allister",
    "firstName": "Ali",
    "lastName": "Black",
    "email": "",
    "userType": "GENERAL",
    "workNumber": "",
    "mobileNumber": "555-215-6629",
    "pagerNumber": "",
    "networkLocations": [
      {
        "name": "Agriculture"
      }
    ],
    "roles": [
      {
        "name": "Frontline"
      },
      {
        "name": "Report Viewer"
      }
    ],
    "titles": [],
    "positions": [],
    "employmentStatuses": [],
    "certifications": [],
    "badges": []
  }
}

The API will recognize whether each user included in the request already exists and should be updated or if a new one needs to be created. 

• If an ID is provided, the existing user with that ID will be updated. 
• If an ID is not provided, but the specified username is already in use, the user with that username will be updated.
• If no ID is specified and the specified username is not in use, a new user with that username will be created if the following required information is provided:
  
  • Username
  • User Type
  • First and Last Name
  • Network Location

Helpful Tips

Here are some helpful tips for updating and creating Users:

1. Network Locations can be referenced by name or ID and at least one is required for each user
2. Roles can be referenced by name or ID.
3. To inactivate a user, set their userType to INACTIVE
4. All dates use ISO 8601 format. Example: "2019-04-29T16:30:40.000+0000"

Pagination

For User Exports, two parameters can be specified to control paging:

• offset: The (zero-based) offset of the first users in the collection to return. Offset is optional and defaults to 0.  
• limit: The maximum number of users to return. The limit is optional and defaults to 20,000, which is the maximum number of users that can be exported in one call. 

Example:

To retrieve the first page of 1000 users, you would use the following call:

https://api.kainexus.com/api/public/v1/json/userList?offset=0&limit=1000

To retrieve the second page of 1000 users, you would use the following call:

https://api.kainexus.com/api/public/v1/json/userList?offset=1000&limit=1000

To retrieve the third page of 1000 users, you would use the following call:

https://api.kainexus.com/api/public/v1/json/userList?offset=2000&limit=1000

Additional information about KaiNexus users

User attributes

4 types of user attributes can be assigned to a user. By default, these are called:

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

An organization may choose to rename these attributes. However, in JSON format, the user attribute names will remain constant as "titles", "positions", "employmentStatuses", and "certifications" respectively.

You can find your organization's existing values for these user attributes on their respective administration pages.

By default, if you try to assign a user attribute value that does not yet exist in your system, your API call will fail. However, you can choose to have the API automatically create any user attribute values that are included in the request but which have not yet been added to KaiNexus. To do so, include the following in your JSON request: "createIfMissing": true.

In the following example of a partial API call, if the Certification "Product Expert" does not already exist in KaiNexus, when the call is performed, it will be automatically added to the system. If that Certification does already exist in the system, it will be unaffected.

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

User Types

A user's User Type must be set to one of the following values:

GENERAL 

CAPTURE 

OFFLINE 

WALLBOARD 

SETUP 

KIOSK 

INACTIVE

Persona

A user's Persona must be set to one of the following values:

FRONTLINE 

LEADER 

EXECUTIVE 

CI_EXPERT

CHAMPION

Badges

Badges are awards that can be granted to users manually or automatically when users meet certain criteria. Your organization may utilize the Universal Badges available to all KaiNexus customers or Custom Badges that are unique to your organization. 

You can export the following information for each Badge a user has earned using the JSON People API: 

• The Badge's ID
• The Badge's name
• The date the Badge was initially awarded
• The user's streak count for the Badge, if applicable

When importing or updating users, you can grant and remove their manually-awarded Badges. Here is an example of a call that would update a user's Badges:

{
     "item": {
          "id": 318,
          "username": "Alex Apple",
          "badges": [
               {
                     "id": 54,
                     "name": "Creative Commenter"
               },
               {
                     "id": 38,
                     "name": "Team Player"
               }
          ]
     }
}

Keep in mind:

• Only manually-awarded Badges will be updated. Automatically-awarded Badges (i.e., Badges awarded based on Team Roles or other activities) are ignored. 
• The user's manually awarded badges will be updated to match the list you provide. If the "badges" key is included in your JSON body but one of their existing manually awarded badges is missing from the array, that badge will be removed from their profile when the request is processed.
• You cannot update a Badge's streak count or awarded date. When you give a user a Badge, the awarded date will be today. 

Example: Curl Script for exporting a list of users

curl -s -D - --user api:APIKEY == -X GET https://api.kainexus.com/api/public/v1/json/userList 

• Replace APIKEY with the API Key generated in KaiNexus

Error Messages

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

What data is supported by JSON People API?

Not all data recorded on KaiNexus users can be exported and updated through JSON People API. The following table shows which user data can be exported and which can be updated during imports:

The following data is not supported on imports or exports:

• Habit Scores
• Notification Preferences
• Profile pictures
• Badge comments and Multi-Award Badge count