The User API
The User API is a REST API that gets, adds and updates user/group/department information.
PROTOCOL |
FORMAT |
CHARACTER ENCODING |
ESCAPE SEQUENCE |
HTTPS |
JSON |
UTF-8 |
Use "\" |
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.
- Password authentication
- 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.
These request headers are used for the REST API.
HEADER |
VALUE |
Host |
{subdomain}.kintone.com:443 |
Request URI
PURPOSE |
URI |
DETAILS |
General |
https://{subdomain}.kintone.com/v1/{API_command}.json |
This is the general format for User APIs.
|
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.
KEY |
VALUE |
message |
The error message. The language of the message will differ depending on the user's language settings of the Kintone user used for the authentication. |
id |
The ID of the error. |
code |
The code of the error, to specify the type of error it is. |
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
Key |
Type |
Details |
id |
ID type |
The ID of the Department. |
code |
String |
The Code of the Department. |
name |
String |
The display name of the Department. |
localName |
String |
The localized name of the Department. |
localNameLocale |
String |
The locale of the localized name of the Department. |
parentCode |
String |
The code of the Parent Department. null, if the parent is the Root. |
description |
String |
The description of the Department. |
title type
Key |
Type |
Details |
id |
ID type |
The ID of the Job Title. |
code |
String |
The code of the Job Title. |
name |
String |
The name of the Job Title. |
description |
String |
The description of the Job Title. |
group type
Key |
Type |
Details |
id |
ID type |
The ID of the Group. |
code |
String |
The code of the Group. |
name |
String |
The display name of the Group. |
description |
String |
The description of the Group. |
organizationTitle type
Key |
Type |
Details |
organization |
department type |
The Department information. |
title |
title type or null |
The Job Title information. null for "no title". |
userTitle type
Key |
Type |
Details |
user |
user type |
The User information. |
title |
title type or null |
The Job Title information. null for "no title". |
customItemValue type
Key |
Type |
Details |
code |
String |
Code |
value |
String |
Value |
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
- 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.