User API Overview
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:
|
|
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 following documentation for more details on retrieving a CSRF token:
Get CSRF Token
Authentication priority
The priority of authentication is as follows.
- Password authentication
- Session authentication
Basic authentication (Legacy)
Warning
As of June 2020, Basic Authentication has been deprecated, and is no longer available for use.
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:
|
|
Request Headers
These request headers are used for the REST API.
HEADER | REQUIRED | VALUE |
---|---|---|
Host | Required | {subdomain}.kintone.com:443 |
Content-Type | Conditional | application/json. Specify this only if the request body is in JSON format. |
X-Cybozu-Authorization | Conditional | login_name:password encoded in Base64.Only required when using Password Authentication. For more information on Password Authentication, refer to the following documentation: Password Authentication |
Authorization | Conditional | Basic followed by a Base64 encoded login_name:password .Only required when using deprecated Basic Authentication, which is no longer available as of June 2020. For more information on Basic Authentication, refer to the following documentation: Basic Authentication |
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
|
|
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. Refer to the following section for more information on ID types: ID type |
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 list of time zones in the Kintone Help: List of Time Zones |
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. |
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. Refer to the following section for more information on customItemValues: customItemValue type |
Only Users & System Administrators are able to get data of Custom Fields that have the Visibility option unchecked.
For more information on Users & System Administrators, refer to the following link:
Types of Administrators
Department type
Key | Type | Details |
---|---|---|
id | ID type | The ID of the Department. Refer to the following section for more information on ID types: ID type |
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. Refer to the following section for more information on ID types: ID type |
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. Refer to the following section for more information on ID types: ID type |
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. Refer to the following section for more information on department types: department type |
title | title type or null |
The Job Title information. null for no title. Refer to the following section for more information on title types:title type |
UserTitle type
Key | Type | Details |
---|---|---|
user | user type | The User information. Refer to the following section for more information on user types: user type |
title | title type or null |
The Job Title information. null for no title. Refer to the following section for more information on user types:title type |
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 the user themselves and Users & System Administrators are able to get data of Custom Fields that have the Visibility option unchecked.
For more information on Users & System Administrators, refer to the following link:
Types of Administrators
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 the 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 aPOST
request. This allows User API requests with long URIs to be executed without errors.
For more information on the Kintone REST API Request method, refer to the following link:
Kintone REST API Request