The User API

The User API is a REST API that gets, adds and updates user/group/department information.

User Authentication

The User REST API requires password authentication, with the appropriate Keys and Values set in the header of the request. If the Basic authentication security feature is also set on your domain, both headers for the Password Authentication and the Basic Authentication will be required for the request.

Password Authentication

Set "X-Cybozu-Authorization" on the request header, with a BASE64 encoded login name and password as the value.
If your log in name is Kintone" and your password is "developer", BASE64 encode "Kintone:developer" and set it on the header as follows:

1

X-Cybozu-Authorization: S2ludG9uZTpkZXZlbG9wZXI=

Session Authentication

Session authentication is a method of authentication where a session ID is assigned to a user by the web server and saved as a cookie. This cookie is used to identify and authenticate the user. Session Authentication can only be used by JavaScript codes that are run on the pages of Kintone. CSRF tokens are necessary when using Session Authentication with POST／PUT／DELETE methods. Refer to the Get CSRF Token documentation for more details on retrieving a CSRF token.

Authentication priority

The priority of authentication is as follows.

1. Password authentication
2. Session authentication

Basic Authentication

If your Kintone environment has set the Basic authentication security feature, add "Authorization" in the request header, with the string "Basic " and a BASE64 encoded login name and password of the Basic authentication as the value.
If the basic authentication log in name is "chocolate" and the basic authentication password is "pudding", place "Basic " in the value, followed by a BASE64 encoded "chocolate:pudding" as follows:

1

Authorization: Basic Y2hvY29sYXRlOnB1ZGRpbmc=

* Domains created after the September 6, 2019 update are unable to use basic authentication.

Refer to the API Updates for September 2019 for details.

Request Headers

These request headers are used for the REST API.

Request URI

Responses

HTTP status code 200 denotes that the request was successful.
Treat any other status code as errors. Errors will respond with JSON data including the following information.

Sample Error Response

1
2
3
4
5

{
  "message": "Invalid JSON string.",
  "id": "1505999166-897850006",
  "code": "CB_IJ01"
}

Data structures used with the User API

ID type

Used for entities (user/group/departments) in Kintone.
An integer between 1 - Long.MAX.

user type

Key	Type	Details
id	ID type	The user ID.
code	String	The log in name of the User.
ctime	ISO-8601 date and time format	The created datetime of the User.
mtime	ISO-8601 date and time format	The updated datetime of the User.
valid	Boolean	If the Status of the user is Active or not.
name	String	The display name of the User.
surName	String	The last name of the User.
givenName	String	The first name of the User.
surNameReading	String	The phonetic reading of the Last name.
givenNameReading	String	The phonetic reading of the First name.
localName	String	The localized display name of the User.
localNameLocale	String	The locale of the localized display name of the User.
timezone	String	The time zone ID of the user's set time zone. See all Available Time Zones in the Kintone Help.
locale	String	The language setting of the user.
description	String	The "About Me" section of the user's profile.
phone	String	The phone number of the User.
mobilePhone	String	The mobile phone number of the User.
extensionNumber	String	The extension number of the User.
email	String	The Email address of the User.
callto	String	The Skype ID of the User.
url	String	The "URL" section of the user's profile.
employeeNumber	String	The Employee Number of the User.
birthDate	ISO-8601 date format or null	The Birthday of the User.
joinDate	ISO-8601 date format or null	The Hire Date of the User.
primaryOrganization	Integer or null	The Department ID of the Priority Department of the User. Set to null if there is no Priority Department.
sortOrder	Integer	The Display Order priority of the User.
customItemValues	customItemValue Arrays.	A list of pairs of Custom Field Names and Custom Field Codes.

Only Users & System Administrators are able to get data of Custom Fields that have the "Visibility" option unchecked.

department type

title type

group type

organizationTitle type

userTitle type

customItemValue type

Custom fields may have their "Visibility" option's "Make this field public" setting unchecked. Only Users & System Administrators are able to get data of Custom Fields that have the "Visibility" option unchecked.

Notes

X-HTTP-Method-Override Header

• Add the X-HTTP-Method-Override header to work around the Request URI Too Large error that occurs when the request URI exceeds 4KB. All User APIs support this header.
• If a GET request of a User API is sent using Kintone REST API Request method, and the URI length exceeds 4KB, the X-HTTP-Method-Override header will automatically be added and the request will be sent as a POST request. This allows User API requests with long URIs to be executed without errors.